@ddlqhd/agent-sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,10 +1,13 @@
-import { S as StorageConfig, M as Message, a as SessionInfo, b as StorageAdapter, T as ToolResult, c as ToolDefinition, A as AgentConfig, d as SystemPrompt, e as StreamEvent, f as AgentResult, g as MCPServerConfig, h as SessionTokenUsage, i as TokenUsage, j as StreamChunk, P as ParsedSkill, k as MemoryConfig } from './types-C0aX_Qdp.cjs';
-export { l as AgentCallbacks, m as AskUserQuestionAnswer, n as AskUserQuestionItem, o as AskUserQuestionResolver, p as AssistantMessage, C as CLIConfig, q as CanUseToolCallback, r as ChatOptions, s as CommandHookConfig, t as CompletionResult, u as ContentPart, v as ContextManagerConfig, w as CreateAskUserQuestionToolOptions, F as FlatCommandHookEntry, x as FunctionHook, H as HookContext, y as HookEventType, z as HookGroupConfig, B as HookManager, D as HookResult, E as HooksSettings, G as HooksSettingsFile, I as ImageContent, J as MCPOptions, K as MCPPromptArgument, L as MCPResourceContent, N as MessageRole, O as ModelAdapter, Q as ModelCapabilities, R as ModelParams, U as RunOptions, V as SessionListOptions, W as SkillConfig, X as SkillDefinition, Y as SkillMetadata, Z as SkillOptions, _ as StreamChunkType, $ as StreamEventAnnotations, a0 as StreamEventType, a1 as SystemMessage, a2 as SystemPromptConfig, a3 as TextContent, a4 as ThinkingContent, a5 as ToolCall, a6 as ToolExecutionContext, a7 as ToolExecutionPolicy, a8 as ToolHandler, a9 as ToolListOptions, aa as ToolMessage, ab as ToolResultMetadata, ac as ToolSchema, ad as UserMessage, ae as buildHookEnv, af as createAskUserQuestionTool, ag as createFunctionHook, ah as formatAnswerSummary, ai as formatAskUserQuestionPrompt, aj as getInteractionTools, ak as matchTool, al as mergeCommandHookLayers, am as questionTool } from './types-C0aX_Qdp.cjs';
-import { T as ToolRegistry, S as SkillRegistry } from './index-RTPmFjMp.cjs';
-export { C as CreateAgentToolOptions, D as DEFAULT_GREP_HEAD_LIMIT, M as MAX_LINE_LENGTH, a as SkillLoader, b as SkillLoaderConfig, c as SubagentRequest, d as SubagentRunner, e as ToolExecuteOptions, f as ToolRegistryConfig, g as agentTool, h as bashTool, i as createAgentTool, j as createSkillLoader, k as createSkillRegistry, l as createSkillTool, m as createTool, n as editTool, o as getAllBuiltinTools, p as getFileSystemTools, q as getGlobalRegistry, r as getGrepTools, s as getSafeBuiltinTools, t as getShellTools, u as getSkillTools, v as getSubagentTools, w as getTaskTools, x as getWebTools, y as globTool, z as grepTool, A as loadHooksSettingsFromProject, B as loadHooksSettingsFromUser, E as parseHooksSettingsFile, F as readFileTool, G as subagentRequestSchema, H as taskCreateTool, I as taskListTool, J as taskUpdateTool, K as truncateMatchLineForDisplay, L as webFetchTool, N as webSearchTool, O as writeFileTool } from './index-RTPmFjMp.cjs';
-export { AnthropicAdapter, AnthropicConfig, CreateModelConfig, ModelProvider, OllamaAdapter, OllamaConfig, OpenAIAdapter, OpenAIConfig, createAnthropic, createModel, createOllama, createOpenAI } from './models/index.cjs';
+import { S as StorageConfig, M as Message, a as SessionInfo, b as StorageAdapter, c as MCPServerConfig, T as ToolResult, d as ToolDefinition, A as AgentConfig, e as SystemPrompt, f as StreamEvent, g as AgentResult, h as ModelAdapter, i as SessionTokenUsage, j as SDKLogger, L as LogEvent, k as TokenUsage, l as StreamChunk, P as ParsedSkill, m as MemoryConfig } from './types-CWPAYWzr.cjs';
+export { n as AgentCallbacks, o as AgentErrorContext, p as AgentLifecycleCallbacks, q as AgentModelConfig, r as AgentRunContext, s as AgentRunEndContext, t as AgentRunEndReason, u as AgentRunStartContext, v as AskUserQuestionAnswer, w as AskUserQuestionItem, x as AskUserQuestionResolver, y as AssistantMessage, C as CLIConfig, z as CanUseToolCallback, B as ChatOptions, D as CommandHookConfig, E as CompletionResult, F as ContentPart, G as ContextManagerConfig, H as CreateAskUserQuestionToolOptions, I as FlatCommandHookEntry, J as FunctionHook, K as HookContext, N as HookDecisionContext, O as HookEventType, Q as HookGroupConfig, R as HookManager, U as HookObservationContext, V as HookResult, W as HooksSettings, X as HooksSettingsFile, Y as ImageContent, Z as LogRedactionConfig, _ as MCPOptions, $ as MCPPromptArgument, a0 as MCPResourceContent, a1 as MODEL_STREAM_EVENT_TYPES, a2 as MessageObservationContext, a3 as MessageRole, a4 as ModelCapabilities, a5 as ModelParams, a6 as ModelRequestStartContext, a7 as RunOptions, a8 as SDKLogLevel, a9 as SessionListOptions, aa as SkillConfig, ab as SkillDefinition, ac as SkillMetadata, ad as SkillOptions, ae as StreamChunkType, af as StreamEventAnnotations, ag as StreamEventType, ah as SystemMessage, ai as SystemMessageSource, aj as SystemPromptConfig, ak as TextContent, al as ThinkingContent, am as ToolCall, an as ToolExecutionBaseContext, ao as ToolExecutionContext, ap as ToolExecutionEndContext, aq as ToolExecutionPolicy, ar as ToolHandler, as as ToolHookObserver, at as ToolListOptions, au as ToolMessage, av as ToolResultMetadata, aw as ToolResultObservationContext, ax as ToolSchema, ay as UserMessage, az as UserMessageSource, aA as buildHookEnv, aB as createAskUserQuestionTool, aC as createFunctionHook, aD as formatAnswerSummary, aE as formatAskUserQuestionPrompt, aF as getInteractionTools, aG as isModelStreamEventType, aH as matchTool, aI as mergeCommandHookLayers, aJ as questionTool } from './types-CWPAYWzr.cjs';
+import { T as ToolRegistry, S as SkillRegistry } from './index-D2Qntkn_.cjs';
+export { C as CreateAgentToolOptions, D as DEFAULT_GREP_HEAD_LIMIT, M as MAX_LINE_LENGTH, a as SkillLoader, b as SkillLoaderConfig, c as SubagentRequest, d as SubagentRunner, e as ToolExecuteOptions, f as ToolRegistryConfig, g as agentTool, h as bashTool, i as createAgentTool, j as createSkillLoader, k as createSkillRegistry, l as createSkillTool, m as createTool, n as editTool, o as getAllBuiltinTools, p as getFileSystemTools, q as getGlobalRegistry, r as getGrepTools, s as getPlanningTools, t as getSafeBuiltinTools, u as getShellTools, v as getSkillTools, w as getSubagentTools, x as getWebTools, y as globTool, z as grepTool, A as loadHooksSettingsFromProject, B as loadHooksSettingsFromUser, E as parseHooksSettingsFile, F as readFileTool, G as subagentRequestSchema, H as todoWriteTool, I as truncateMatchLineForDisplay, J as webFetchTool, K as webSearchTool, L as writeFileTool } from './index-D2Qntkn_.cjs';
+export { AnthropicAdapter, AnthropicConfig, AnthropicFetchRetryOptions, CreateModelConfig, DEFAULT_ADAPTER_CAPABILITIES, ModelProvider, OllamaAdapter, OllamaConfig, OpenAIAdapter, OpenAIConfig, createAnthropic, createModel, createOllama, createOpenAI } from './models/index.cjs';
 import 'zod';
 
+/** Published package version, read from package root `package.json`. */
+declare const PACKAGE_VERSION: string;
+
 /**
  * 会话管理器配置
  */
@@ -73,18 +76,6 @@ declare class SessionManager {
  */
 declare function createSessionManager(config?: StorageConfig): SessionManager;
 
-interface StdioMCPConfig {
-    name: string;
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-}
-interface HttpMCPConfig {
-    name: string;
-    url: string;
-    headers?: Record<string, string>;
-}
-type MCPClientConfig = StdioMCPConfig | HttpMCPConfig;
 interface MCPTool {
     name: string;
     description?: string;
@@ -120,7 +111,7 @@ declare class MCPClient {
     private _connected;
     private _tools;
     private _serverInfo?;
-    constructor(config: MCPClientConfig);
+    constructor(config: MCPServerConfig);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     listTools(): Promise<MCPTool[]>;
@@ -139,12 +130,12 @@ declare class MCPClient {
     } | undefined;
     get tools(): MCPTool[];
 }
-declare function createMCPClient(config: MCPClientConfig): MCPClient;
+declare function createMCPClient(config: MCPServerConfig): MCPClient;
 
 declare class MCPAdapter {
     private clients;
     private toolMap;
-    addServer(config: MCPClientConfig): Promise<void>;
+    addServer(config: MCPServerConfig): Promise<void>;
     removeServer(name: string): Promise<void>;
     getToolDefinitions(): ToolDefinition[];
     executeTool(fullName: string, args: unknown): Promise<ToolResult>;
@@ -158,6 +149,8 @@ declare class MCPAdapter {
 }
 declare function createMCPAdapter(): MCPAdapter;
 
+/** Default upper bound for model↔tool rounds per user turn when `AgentConfig.maxIterations` is omitted. */
+declare const DEFAULT_MAX_ITERATIONS = 400;
 /**
  * 流式执行选项
  */
@@ -185,7 +178,9 @@ declare class Agent {
     private agentDepth;
     private activeSubagentRuns;
     private sessionUsage;
+    private static resolveModel;
     constructor(config: AgentConfig);
+    private log;
     /**
      * 注册内置 + 自定义工具，或仅 {@link AgentConfig.exclusiveTools}。
      */
@@ -204,6 +199,16 @@ declare class Agent {
      */
     private initializeMCP;
     private annotateStreamEvent;
+    private baseRunContext;
+    /**
+     * 分发流式事件到 `callbacks.onEvent` 与 `lifecycle.onModelEvent` / `onModelUsage`。
+     */
+    private emitStreamEvent;
+    /** 标注、触发观察回调并返回供 `yield` 的事件 */
+    private streamOut;
+    private emitAgentError;
+    private safeLifecycleVoid;
+    private emitRunEnd;
     private static createEmptySessionUsage;
     private resetSessionState;
     /**
@@ -243,6 +248,10 @@ declare class Agent {
      * 获取 Skill 注册中心
      */
     getSkillRegistry(): SkillRegistry;
+    /**
+     * 解析后的模型适配器（`modelConfig` 已在构造时合并 `env` 并实例化）。
+     */
+    getModel(): ModelAdapter;
     /**
      * 处理用户输入，检测并处理 skill 调用
      * @param input 用户输入
@@ -353,13 +362,28 @@ declare class Agent {
  */
 declare function createAgent(config: AgentConfig): Agent;
 
+/**
+ * 当前 `process.env` 中值为 string 的键的快照，再叠 `overrides`（后者覆盖同名键）。
+ * 供应用层构造 model（如显式传入 `apiKey`）与 Agent 内部合并 MCP stdio 环境共用。
+ *
+ * 注意：快照包含当前进程 environ 中的敏感变量；传入 MCP 子进程时由调用方控制 `env` / `overrides`。
+ */
+declare function mergeProcessEnv(overrides?: Record<string, string>): Record<string, string>;
+/**
+ * stdio MCP 子进程环境：`process.env` + 可选 Agent 级 `env` + 可选单服务 `MCPServerConfig.env`（优先级递增）。
+ */
+declare function mergeMcpStdioEnv(agentEnv?: Record<string, string>, serverEnv?: Record<string, string>): Record<string, string>;
+
 /**
  * Agent SDK 默认系统提示词
  *
  * 占位符说明：
  * - {{SKILL_LIST}}: 会被运行时注入的skill列表替换
  */
-declare const DEFAULT_SYSTEM_PROMPT = "You are an AI assistant powered by the Agent SDK. You can help users with various tasks by using your built-in tools and capabilities.\n\n## Core Capabilities\n\n### Tools\nYou have access to a set of tools that allow you to:\n- **File Operations**: read, write, list, delete files and directories\n- **Code Execution**: run shell commands, Python scripts, Node.js code\n- **Web Access**: make HTTP requests, fetch webpages, download files\n- **Custom Tools**: additional tools registered by the user or skills\n\nWhen to use tools:\n- Use tools when the task requires real-world actions (file I/O, computation, API calls)\n- Prefer reading files before modifying them\n- Use the simplest tool that gets the job done\n- Run multiple independent tool calls in parallel when possible\n\n**Prefer dedicated tools over Bash:** Do not use `Bash` to do work that has a first-class tool. This keeps actions reviewable and consistent.\n- **Read** for file contents \u2014 not `cat`, `head`, `tail`, or `sed` to print files\n- **Write** to create or overwrite files \u2014 not shell redirection or heredocs\n- **Edit** for targeted file changes \u2014 not `sed`, `awk`, or ad-hoc scripts to patch files\n- **Glob** to find paths by pattern \u2014 not `find` or `ls` for discovery\n- **Grep** to search file contents \u2014 not `grep` or `rg` in the shell (built-in line-by-line regex search; correct integration)\n- **WebFetch** / **WebSearch** when the task needs HTTP or web search (when configured)\n\nReserve **Bash** for real shell needs: `git`, package managers, build commands, compilers, and other operations that require a shell or are not covered above.\n\n### Skills\nSkills are instruction guides for specialized tasks. When activated, you receive the skill's full content including any referenced file paths.\n\n{{SKILL_LIST}}\n\n**Usage:**\n- **Listing skills**: When the user asks about available skills (e.g., \"what skills do you have\", \"\u4F60\u6709\u54EA\u4E9B\u6280\u80FD\", \"list your skills\") \u2192 Simply describe the skills listed above. Do NOT activate any skill.\n- **Activating skills**: When the user has a specific task that matches a skill's purpose \u2192 Call `Skill` with the skill name, then follow the returned instructions.\n- After activation, use the provided Base Path to read any referenced files.\n\n### Sessions\n- Conversations are persisted in sessions\n- Use session IDs to maintain context across multiple interactions\n- Previous messages provide important context for current tasks\n\n## Task Execution Principles\n\n1. **Plan First for Complex Tasks**: For multi-step tasks, you MUST call `TaskCreate` BEFORE any other tool. Do NOT skip this step.\n2. **Be Direct**: Go straight to the point. Try the simplest approach first.\n3. **Be Concise**: If you can say it in one sentence, don't use three.\n4. **Read Before Modify**: Always understand existing code before changing it.\n5. **No Over-Engineering**: Only make changes directly requested or clearly necessary.\n6. **Prefer Edit Over Create**: Modify existing files rather than creating new ones when appropriate.\n7. **Handle Errors Gracefully**: Report errors clearly with actionable suggestions.\n\n## Task Management with Todo List\n\n**MANDATORY**: For multi-step tasks, call `TaskCreate` FIRST.\n\n**Workflow:**\n1. Receive complex task -> call `TaskCreate` immediately\n2. Start first task (in_progress) -> complete -> mark completed\n3. Move to next task -> repeat\n4. Cancel tasks that become irrelevant\n\n**Example:**\nUser: \"Open Google, search X, summarize results, open first link, extract info\"\n-> Multi-step task detected -> call `TaskCreate` FIRST, then execute.\n\n## Output Format\n\n- Lead with the answer or action, not the reasoning\n- Skip filler words and unnecessary preamble\n- Use code blocks with language hints for code\n- Structure longer responses with headers and lists\n- Reference file paths with line numbers when relevant (e.g., `src/index.ts:42`)\n\n## Security Guidelines\n\n- Do not introduce security vulnerabilities (injection, XSS, etc.)\n- Validate user inputs at boundaries\n- Do not execute untrusted code without sandboxing\n- Respect file system permissions and access controls\n\n### High-risk actions (confirm with the user first)\n\nThere is no automatic approval UI: **ask in the conversation** (or use `AskUserQuestion`) before proceeding when an action is destructive, hard to reverse, or affects others. Examples:\n- Deleting files or branches, dropping data, `rm -rf`, overwriting uncommitted work\n- Hard-to-reverse git: force-push, `reset --hard`, rewriting published history, amending shared commits\n- Actions visible outside this machine: pushing code, opening/closing/commenting on PRs or issues, sending messages, posting to external services, changing shared CI/CD or cloud permissions\n- Broad dependency or infrastructure changes (e.g. major version bumps, lockfile rewrites) when impact is unclear\n\nDefault to explaining what you intend and getting explicit agreement unless the user already directed that exact action.\n\n## Tool hooks\n\nWhen hooks are configured (e.g. PreToolUse), a tool call may be **blocked** or its **inputs adjusted** before execution. If a tool fails with a message indicating a hook blocked or rejected the call, **do not** retry the identical tool call unchanged \u2014 read the reason, change your approach, or ask the user. Treat hook feedback as binding policy from the environment.\n\n## Interaction Style\n\n- Be helpful and proactive\n- Ask clarifying questions when instructions are ambiguous\n- Provide suggestions when you see opportunities for improvement\n- Acknowledge limitations honestly\n- Maintain a professional, friendly tone";
+declare const DEFAULT_SYSTEM_PROMPT = "You are an AI assistant powered by the Agent SDK. You can help users with various tasks by using your built-in tools and capabilities.\n\n## Core Capabilities\n\n### Tools\nYou have access to a set of tools that allow you to:\n- **File Operations**: read, write, list, delete files and directories\n- **Code Execution**: run shell commands, Python scripts, Node.js code\n- **Web Access**: make HTTP requests, fetch webpages, download files\n- **Custom Tools**: additional tools registered by the user or skills\n\nWhen to use tools:\n- Use tools when the task requires real-world actions (file I/O, computation, API calls)\n- Prefer reading files before modifying them\n- Use the simplest tool that gets the job done\n- Run multiple independent tool calls in parallel when possible\n\n**Prefer dedicated tools over Bash:** Do not use `Bash` to do work that has a first-class tool. This keeps actions reviewable and consistent.\n- **Read** for file contents \u2014 not `cat`, `head`, `tail`, or `sed` to print files\n- **Write** to create or overwrite files \u2014 not shell redirection or heredocs\n- **Edit** for targeted file changes \u2014 not `sed`, `awk`, or ad-hoc scripts to patch files\n- **Glob** to find paths by pattern \u2014 not `find` or `ls` for discovery\n- **Grep** to search file contents \u2014 not `grep` or `rg` in the shell (built-in line-by-line regex search; correct integration)\n- **WebFetch** / **WebSearch** when the task needs HTTP or web search (when configured)\n- **TodoWrite** for structured multi-step task lists (see **Task Management with Todo List** below)\n\nReserve **Bash** for real shell needs: `git`, package managers, build commands, compilers, and other operations that require a shell or are not covered above.\n\n### Skills\nSkills are instruction guides for specialized tasks. When activated, you receive the skill's full content including any referenced file paths.\n\n{{SKILL_LIST}}\n\n**Usage:**\n- **Listing skills**: When the user asks about available skills (e.g., \"what skills do you have\", \"\u4F60\u6709\u54EA\u4E9B\u6280\u80FD\", \"list your skills\") \u2192 Simply describe the skills listed above. Do NOT activate any skill.\n- **Activating skills**: When the user has a specific task that matches a skill's purpose \u2192 Call `Skill` with the skill name, then follow the returned instructions.\n- After activation, use the provided Base Path to read any referenced files.\n\n### Sessions\n- Conversations are persisted in sessions\n- Use session IDs to maintain context across multiple interactions\n- Previous messages provide important context for current tasks\n\n## Task Execution Principles\n\n1. **Plan First for Complex Tasks**: For multi-step tasks, you MUST call `TodoWrite` BEFORE any other tool. Do NOT skip this step.\n2. **Be Direct**: Go straight to the point. Try the simplest approach first.\n3. **Be Concise**: If you can say it in one sentence, don't use three.\n4. **Read Before Modify**: Always understand existing code before changing it.\n5. **No Over-Engineering**: Only make changes directly requested or clearly necessary.\n6. **Prefer Edit Over Create**: Modify existing files rather than creating new ones when appropriate.\n7. **Handle Errors Gracefully**: Report errors clearly with actionable suggestions.\n\n## Task Management with Todo List\n\n**MANDATORY**: For multi-step tasks, call `TodoWrite` FIRST.\n\n**Workflow:**\n1. Receive complex task -> call `TodoWrite` immediately\n2. Mark tasks `in_progress` / `completed` as you work; several items may be `in_progress` at once when work is parallel\n3. **Replan freely:** if the plan was wrong or incomplete, call `TodoWrite` again with a revised full list (add, remove, reorder, or rewrite steps)\n4. **Before you finish your response** for a multi-step request, ensure **every** todo is `completed` via `TodoWrite` (unless you intentionally pause for a follow-up turn). Do not leave `pending` / `in_progress` items when the work is done\n\n**Example:**\nUser: \"Open Google, search X, summarize results, open first link, extract info\"\n-> Multi-step task detected -> call `TodoWrite` FIRST, then execute.\n\n## Output Format\n\n- Lead with the answer or action, not the reasoning\n- Skip filler words and unnecessary preamble\n- Use code blocks with language hints for code\n- Structure longer responses with headers and lists\n- Reference file paths with line numbers when relevant (e.g., `src/index.ts:42`)\n\n## Security Guidelines\n\n- Do not introduce security vulnerabilities (injection, XSS, etc.)\n- Validate user inputs at boundaries\n- Do not execute untrusted code without sandboxing\n- Respect file system permissions and access controls\n\n### High-risk actions (confirm with the user first)\n\nThere is no automatic approval UI: **ask in the conversation** (or use `AskUserQuestion`) before proceeding when an action is destructive, hard to reverse, or affects others. Examples:\n- Deleting files or branches, dropping data, `rm -rf`, overwriting uncommitted work\n- Hard-to-reverse git: force-push, `reset --hard`, rewriting published history, amending shared commits\n- Actions visible outside this machine: pushing code, opening/closing/commenting on PRs or issues, sending messages, posting to external services, changing shared CI/CD or cloud permissions\n- Broad dependency or infrastructure changes (e.g. major version bumps, lockfile rewrites) when impact is unclear\n\nDefault to explaining what you intend and getting explicit agreement unless the user already directed that exact action.\n\n## Tool hooks\n\nWhen hooks are configured (e.g. PreToolUse), a tool call may be **blocked** or its **inputs adjusted** before execution. If a tool fails with a message indicating a hook blocked or rejected the call, **do not** retry the identical tool call unchanged \u2014 read the reason, change your approach, or ask the user. Treat hook feedback as binding policy from the environment.\n\n## Interaction Style\n\n- Be helpful and proactive\n- Ask clarifying questions when instructions are ambiguous\n- Provide suggestions when you see opportunities for improvement\n- Acknowledge limitations honestly\n- Maintain a professional, friendly tone";
+
+declare function formatSDKLog(event: LogEvent): string;
+declare function createConsoleSDKLogger(): SDKLogger;
 
 /**
  * Same directory as {@link Agent} session storage: `<userBase>/.claude/sessions`.
@@ -562,6 +586,8 @@ declare function fromAsyncIterable(iterable: AsyncIterable<StreamEvent>): AgentS
 interface StreamChunkProcessorOptions {
     /** Emit `text_start` / `text_end` around assistant text deltas (Claude-style content blocks). Default true. */
     emitTextBoundaries?: boolean;
+    /** Emit `thinking_start` / `thinking_end` around assistant thinking deltas. Default true. */
+    emitThinkingBoundaries?: boolean;
 }
 /**
  * Stateful conversion from model `StreamChunk` to normalized `StreamEvent`s.
@@ -571,7 +597,9 @@ declare class StreamChunkProcessor {
     private currentToolCall;
     private lastUsage;
     private inTextBlock;
+    private inThinkingBlock;
     private readonly emitTextBoundaries;
+    private readonly emitThinkingBoundaries;
     constructor(options?: StreamChunkProcessorOptions);
     processChunk(chunk: StreamChunk): StreamEvent[];
     /** End open text block and finalize any in-progress streamed tool call. */
@@ -581,6 +609,16 @@ declare class StreamChunkProcessor {
     private safeParseJSON;
 }
 
+/**
+ * Builds the Agent-facing tool name for an MCP tool: `mcp__<serverName>__<toolName>`.
+ * Avoid `__` inside `serverName` or `toolName`; those segments are not escaped and would make parsing ambiguous.
+ */
+declare function formatMcpToolName(serverName: string, toolName: string): string;
+/**
+ * True if `name` matches the MCP-prefixed tool naming convention (at least `mcp__<server>__<tool>`).
+ */
+declare function isMcpPrefixedToolName(name: string): boolean;
+
 /**
  * 解析 SKILL.md 文件
  * 格式：
@@ -632,6 +670,8 @@ interface MCPConfigFile {
             args?: string[];
             /** 环境变量 */
             env?: Record<string, string>;
+            /** stdio 子进程工作目录 */
+            cwd?: string;
             /** URL (HTTP transport) */
             url?: string;
             /** HTTP headers */
@@ -661,4 +701,4 @@ declare function loadMCPConfig(configPath?: string, startDir?: string, userBaseP
  */
 declare function validateMCPConfig(config: MCPConfigFile): string[];
 
-export { Agent, AgentConfig, AgentResult, AgentStream, DEFAULT_SYSTEM_PROMPT, type HttpMCPConfig, JsonlStorage, MCPAdapter, MCPClient, type MCPClientConfig, type MCPConfigFile, type MCPConfigLoadResult, type MCPPrompt, type MCPResource, MCPServerConfig, type MCPTool, MemoryConfig, MemoryManager, MemoryStorage, Message, ParsedSkill, type PromptMessage, SessionInfo, SessionManager, SessionTokenUsage, SkillRegistry, type StdioMCPConfig, StorageAdapter, StorageConfig, StreamChunk, StreamChunkProcessor, type StreamChunkProcessorOptions, StreamEvent, type StreamOptions, SystemPrompt, TokenUsage, ToolDefinition, ToolRegistry, ToolResult, createAgent, createJsonlStorage, createMCPAdapter, createMCPClient, createMemoryStorage, createSessionManager, createStorage, createStream, fromAsyncIterable, getLatestSessionId, getSessionStoragePath, loadMCPConfig, parseSkillMd, validateMCPConfig };
+export { Agent, AgentConfig, AgentResult, AgentStream, DEFAULT_MAX_ITERATIONS, DEFAULT_SYSTEM_PROMPT, JsonlStorage, LogEvent, MCPAdapter, MCPClient, type MCPConfigFile, type MCPConfigLoadResult, type MCPPrompt, type MCPResource, MCPServerConfig, type MCPTool, MemoryConfig, MemoryManager, MemoryStorage, Message, ModelAdapter, PACKAGE_VERSION, ParsedSkill, type PromptMessage, SDKLogger, SessionInfo, SessionManager, SessionTokenUsage, SkillRegistry, StorageAdapter, StorageConfig, StreamChunk, StreamChunkProcessor, type StreamChunkProcessorOptions, StreamEvent, type StreamOptions, SystemPrompt, TokenUsage, ToolDefinition, ToolRegistry, ToolResult, createAgent, createConsoleSDKLogger, createJsonlStorage, createMCPAdapter, createMCPClient, createMemoryStorage, createSessionManager, createStorage, createStream, formatMcpToolName, formatSDKLog, fromAsyncIterable, getLatestSessionId, getSessionStoragePath, isMcpPrefixedToolName, loadMCPConfig, mergeMcpStdioEnv, mergeProcessEnv, parseSkillMd, validateMCPConfig };

package/dist/index.d.ts

@@ -1,10 +1,13 @@
-import { S as StorageConfig, M as Message, a as SessionInfo, b as StorageAdapter, T as ToolResult, c as ToolDefinition, A as AgentConfig, d as SystemPrompt, e as StreamEvent, f as AgentResult, g as MCPServerConfig, h as SessionTokenUsage, i as TokenUsage, j as StreamChunk, P as ParsedSkill, k as MemoryConfig } from './types-C0aX_Qdp.js';
-export { l as AgentCallbacks, m as AskUserQuestionAnswer, n as AskUserQuestionItem, o as AskUserQuestionResolver, p as AssistantMessage, C as CLIConfig, q as CanUseToolCallback, r as ChatOptions, s as CommandHookConfig, t as CompletionResult, u as ContentPart, v as ContextManagerConfig, w as CreateAskUserQuestionToolOptions, F as FlatCommandHookEntry, x as FunctionHook, H as HookContext, y as HookEventType, z as HookGroupConfig, B as HookManager, D as HookResult, E as HooksSettings, G as HooksSettingsFile, I as ImageContent, J as MCPOptions, K as MCPPromptArgument, L as MCPResourceContent, N as MessageRole, O as ModelAdapter, Q as ModelCapabilities, R as ModelParams, U as RunOptions, V as SessionListOptions, W as SkillConfig, X as SkillDefinition, Y as SkillMetadata, Z as SkillOptions, _ as StreamChunkType, $ as StreamEventAnnotations, a0 as StreamEventType, a1 as SystemMessage, a2 as SystemPromptConfig, a3 as TextContent, a4 as ThinkingContent, a5 as ToolCall, a6 as ToolExecutionContext, a7 as ToolExecutionPolicy, a8 as ToolHandler, a9 as ToolListOptions, aa as ToolMessage, ab as ToolResultMetadata, ac as ToolSchema, ad as UserMessage, ae as buildHookEnv, af as createAskUserQuestionTool, ag as createFunctionHook, ah as formatAnswerSummary, ai as formatAskUserQuestionPrompt, aj as getInteractionTools, ak as matchTool, al as mergeCommandHookLayers, am as questionTool } from './types-C0aX_Qdp.js';
-import { T as ToolRegistry, S as SkillRegistry } from './index-DPsZ1zat.js';
-export { C as CreateAgentToolOptions, D as DEFAULT_GREP_HEAD_LIMIT, M as MAX_LINE_LENGTH, a as SkillLoader, b as SkillLoaderConfig, c as SubagentRequest, d as SubagentRunner, e as ToolExecuteOptions, f as ToolRegistryConfig, g as agentTool, h as bashTool, i as createAgentTool, j as createSkillLoader, k as createSkillRegistry, l as createSkillTool, m as createTool, n as editTool, o as getAllBuiltinTools, p as getFileSystemTools, q as getGlobalRegistry, r as getGrepTools, s as getSafeBuiltinTools, t as getShellTools, u as getSkillTools, v as getSubagentTools, w as getTaskTools, x as getWebTools, y as globTool, z as grepTool, A as loadHooksSettingsFromProject, B as loadHooksSettingsFromUser, E as parseHooksSettingsFile, F as readFileTool, G as subagentRequestSchema, H as taskCreateTool, I as taskListTool, J as taskUpdateTool, K as truncateMatchLineForDisplay, L as webFetchTool, N as webSearchTool, O as writeFileTool } from './index-DPsZ1zat.js';
-export { AnthropicAdapter, AnthropicConfig, CreateModelConfig, ModelProvider, OllamaAdapter, OllamaConfig, OpenAIAdapter, OpenAIConfig, createAnthropic, createModel, createOllama, createOpenAI } from './models/index.js';
+import { S as StorageConfig, M as Message, a as SessionInfo, b as StorageAdapter, c as MCPServerConfig, T as ToolResult, d as ToolDefinition, A as AgentConfig, e as SystemPrompt, f as StreamEvent, g as AgentResult, h as ModelAdapter, i as SessionTokenUsage, j as SDKLogger, L as LogEvent, k as TokenUsage, l as StreamChunk, P as ParsedSkill, m as MemoryConfig } from './types-CWPAYWzr.js';
+export { n as AgentCallbacks, o as AgentErrorContext, p as AgentLifecycleCallbacks, q as AgentModelConfig, r as AgentRunContext, s as AgentRunEndContext, t as AgentRunEndReason, u as AgentRunStartContext, v as AskUserQuestionAnswer, w as AskUserQuestionItem, x as AskUserQuestionResolver, y as AssistantMessage, C as CLIConfig, z as CanUseToolCallback, B as ChatOptions, D as CommandHookConfig, E as CompletionResult, F as ContentPart, G as ContextManagerConfig, H as CreateAskUserQuestionToolOptions, I as FlatCommandHookEntry, J as FunctionHook, K as HookContext, N as HookDecisionContext, O as HookEventType, Q as HookGroupConfig, R as HookManager, U as HookObservationContext, V as HookResult, W as HooksSettings, X as HooksSettingsFile, Y as ImageContent, Z as LogRedactionConfig, _ as MCPOptions, $ as MCPPromptArgument, a0 as MCPResourceContent, a1 as MODEL_STREAM_EVENT_TYPES, a2 as MessageObservationContext, a3 as MessageRole, a4 as ModelCapabilities, a5 as ModelParams, a6 as ModelRequestStartContext, a7 as RunOptions, a8 as SDKLogLevel, a9 as SessionListOptions, aa as SkillConfig, ab as SkillDefinition, ac as SkillMetadata, ad as SkillOptions, ae as StreamChunkType, af as StreamEventAnnotations, ag as StreamEventType, ah as SystemMessage, ai as SystemMessageSource, aj as SystemPromptConfig, ak as TextContent, al as ThinkingContent, am as ToolCall, an as ToolExecutionBaseContext, ao as ToolExecutionContext, ap as ToolExecutionEndContext, aq as ToolExecutionPolicy, ar as ToolHandler, as as ToolHookObserver, at as ToolListOptions, au as ToolMessage, av as ToolResultMetadata, aw as ToolResultObservationContext, ax as ToolSchema, ay as UserMessage, az as UserMessageSource, aA as buildHookEnv, aB as createAskUserQuestionTool, aC as createFunctionHook, aD as formatAnswerSummary, aE as formatAskUserQuestionPrompt, aF as getInteractionTools, aG as isModelStreamEventType, aH as matchTool, aI as mergeCommandHookLayers, aJ as questionTool } from './types-CWPAYWzr.js';
+import { T as ToolRegistry, S as SkillRegistry } from './index-Cw3SfEAB.js';
+export { C as CreateAgentToolOptions, D as DEFAULT_GREP_HEAD_LIMIT, M as MAX_LINE_LENGTH, a as SkillLoader, b as SkillLoaderConfig, c as SubagentRequest, d as SubagentRunner, e as ToolExecuteOptions, f as ToolRegistryConfig, g as agentTool, h as bashTool, i as createAgentTool, j as createSkillLoader, k as createSkillRegistry, l as createSkillTool, m as createTool, n as editTool, o as getAllBuiltinTools, p as getFileSystemTools, q as getGlobalRegistry, r as getGrepTools, s as getPlanningTools, t as getSafeBuiltinTools, u as getShellTools, v as getSkillTools, w as getSubagentTools, x as getWebTools, y as globTool, z as grepTool, A as loadHooksSettingsFromProject, B as loadHooksSettingsFromUser, E as parseHooksSettingsFile, F as readFileTool, G as subagentRequestSchema, H as todoWriteTool, I as truncateMatchLineForDisplay, J as webFetchTool, K as webSearchTool, L as writeFileTool } from './index-Cw3SfEAB.js';
+export { AnthropicAdapter, AnthropicConfig, AnthropicFetchRetryOptions, CreateModelConfig, DEFAULT_ADAPTER_CAPABILITIES, ModelProvider, OllamaAdapter, OllamaConfig, OpenAIAdapter, OpenAIConfig, createAnthropic, createModel, createOllama, createOpenAI } from './models/index.js';
 import 'zod';
 
+/** Published package version, read from package root `package.json`. */
+declare const PACKAGE_VERSION: string;
+
 /**
  * 会话管理器配置
  */
@@ -73,18 +76,6 @@ declare class SessionManager {
  */
 declare function createSessionManager(config?: StorageConfig): SessionManager;
 
-interface StdioMCPConfig {
-    name: string;
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-}
-interface HttpMCPConfig {
-    name: string;
-    url: string;
-    headers?: Record<string, string>;
-}
-type MCPClientConfig = StdioMCPConfig | HttpMCPConfig;
 interface MCPTool {
     name: string;
     description?: string;
@@ -120,7 +111,7 @@ declare class MCPClient {
     private _connected;
     private _tools;
     private _serverInfo?;
-    constructor(config: MCPClientConfig);
+    constructor(config: MCPServerConfig);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     listTools(): Promise<MCPTool[]>;
@@ -139,12 +130,12 @@ declare class MCPClient {
     } | undefined;
     get tools(): MCPTool[];
 }
-declare function createMCPClient(config: MCPClientConfig): MCPClient;
+declare function createMCPClient(config: MCPServerConfig): MCPClient;
 
 declare class MCPAdapter {
     private clients;
     private toolMap;
-    addServer(config: MCPClientConfig): Promise<void>;
+    addServer(config: MCPServerConfig): Promise<void>;
     removeServer(name: string): Promise<void>;
     getToolDefinitions(): ToolDefinition[];
     executeTool(fullName: string, args: unknown): Promise<ToolResult>;
@@ -158,6 +149,8 @@ declare class MCPAdapter {
 }
 declare function createMCPAdapter(): MCPAdapter;
 
+/** Default upper bound for model↔tool rounds per user turn when `AgentConfig.maxIterations` is omitted. */
+declare const DEFAULT_MAX_ITERATIONS = 400;
 /**
  * 流式执行选项
  */
@@ -185,7 +178,9 @@ declare class Agent {
     private agentDepth;
     private activeSubagentRuns;
     private sessionUsage;
+    private static resolveModel;
     constructor(config: AgentConfig);
+    private log;
     /**
      * 注册内置 + 自定义工具，或仅 {@link AgentConfig.exclusiveTools}。
      */
@@ -204,6 +199,16 @@ declare class Agent {
      */
     private initializeMCP;
     private annotateStreamEvent;
+    private baseRunContext;
+    /**
+     * 分发流式事件到 `callbacks.onEvent` 与 `lifecycle.onModelEvent` / `onModelUsage`。
+     */
+    private emitStreamEvent;
+    /** 标注、触发观察回调并返回供 `yield` 的事件 */
+    private streamOut;
+    private emitAgentError;
+    private safeLifecycleVoid;
+    private emitRunEnd;
     private static createEmptySessionUsage;
     private resetSessionState;
     /**
@@ -243,6 +248,10 @@ declare class Agent {
      * 获取 Skill 注册中心
      */
     getSkillRegistry(): SkillRegistry;
+    /**
+     * 解析后的模型适配器（`modelConfig` 已在构造时合并 `env` 并实例化）。
+     */
+    getModel(): ModelAdapter;
     /**
      * 处理用户输入，检测并处理 skill 调用
      * @param input 用户输入
@@ -353,13 +362,28 @@ declare class Agent {
  */
 declare function createAgent(config: AgentConfig): Agent;
 
+/**
+ * 当前 `process.env` 中值为 string 的键的快照，再叠 `overrides`（后者覆盖同名键）。
+ * 供应用层构造 model（如显式传入 `apiKey`）与 Agent 内部合并 MCP stdio 环境共用。
+ *
+ * 注意：快照包含当前进程 environ 中的敏感变量；传入 MCP 子进程时由调用方控制 `env` / `overrides`。
+ */
+declare function mergeProcessEnv(overrides?: Record<string, string>): Record<string, string>;
+/**
+ * stdio MCP 子进程环境：`process.env` + 可选 Agent 级 `env` + 可选单服务 `MCPServerConfig.env`（优先级递增）。
+ */
+declare function mergeMcpStdioEnv(agentEnv?: Record<string, string>, serverEnv?: Record<string, string>): Record<string, string>;
+
 /**
  * Agent SDK 默认系统提示词
  *
  * 占位符说明：
  * - {{SKILL_LIST}}: 会被运行时注入的skill列表替换
  */
-declare const DEFAULT_SYSTEM_PROMPT = "You are an AI assistant powered by the Agent SDK. You can help users with various tasks by using your built-in tools and capabilities.\n\n## Core Capabilities\n\n### Tools\nYou have access to a set of tools that allow you to:\n- **File Operations**: read, write, list, delete files and directories\n- **Code Execution**: run shell commands, Python scripts, Node.js code\n- **Web Access**: make HTTP requests, fetch webpages, download files\n- **Custom Tools**: additional tools registered by the user or skills\n\nWhen to use tools:\n- Use tools when the task requires real-world actions (file I/O, computation, API calls)\n- Prefer reading files before modifying them\n- Use the simplest tool that gets the job done\n- Run multiple independent tool calls in parallel when possible\n\n**Prefer dedicated tools over Bash:** Do not use `Bash` to do work that has a first-class tool. This keeps actions reviewable and consistent.\n- **Read** for file contents \u2014 not `cat`, `head`, `tail`, or `sed` to print files\n- **Write** to create or overwrite files \u2014 not shell redirection or heredocs\n- **Edit** for targeted file changes \u2014 not `sed`, `awk`, or ad-hoc scripts to patch files\n- **Glob** to find paths by pattern \u2014 not `find` or `ls` for discovery\n- **Grep** to search file contents \u2014 not `grep` or `rg` in the shell (built-in line-by-line regex search; correct integration)\n- **WebFetch** / **WebSearch** when the task needs HTTP or web search (when configured)\n\nReserve **Bash** for real shell needs: `git`, package managers, build commands, compilers, and other operations that require a shell or are not covered above.\n\n### Skills\nSkills are instruction guides for specialized tasks. When activated, you receive the skill's full content including any referenced file paths.\n\n{{SKILL_LIST}}\n\n**Usage:**\n- **Listing skills**: When the user asks about available skills (e.g., \"what skills do you have\", \"\u4F60\u6709\u54EA\u4E9B\u6280\u80FD\", \"list your skills\") \u2192 Simply describe the skills listed above. Do NOT activate any skill.\n- **Activating skills**: When the user has a specific task that matches a skill's purpose \u2192 Call `Skill` with the skill name, then follow the returned instructions.\n- After activation, use the provided Base Path to read any referenced files.\n\n### Sessions\n- Conversations are persisted in sessions\n- Use session IDs to maintain context across multiple interactions\n- Previous messages provide important context for current tasks\n\n## Task Execution Principles\n\n1. **Plan First for Complex Tasks**: For multi-step tasks, you MUST call `TaskCreate` BEFORE any other tool. Do NOT skip this step.\n2. **Be Direct**: Go straight to the point. Try the simplest approach first.\n3. **Be Concise**: If you can say it in one sentence, don't use three.\n4. **Read Before Modify**: Always understand existing code before changing it.\n5. **No Over-Engineering**: Only make changes directly requested or clearly necessary.\n6. **Prefer Edit Over Create**: Modify existing files rather than creating new ones when appropriate.\n7. **Handle Errors Gracefully**: Report errors clearly with actionable suggestions.\n\n## Task Management with Todo List\n\n**MANDATORY**: For multi-step tasks, call `TaskCreate` FIRST.\n\n**Workflow:**\n1. Receive complex task -> call `TaskCreate` immediately\n2. Start first task (in_progress) -> complete -> mark completed\n3. Move to next task -> repeat\n4. Cancel tasks that become irrelevant\n\n**Example:**\nUser: \"Open Google, search X, summarize results, open first link, extract info\"\n-> Multi-step task detected -> call `TaskCreate` FIRST, then execute.\n\n## Output Format\n\n- Lead with the answer or action, not the reasoning\n- Skip filler words and unnecessary preamble\n- Use code blocks with language hints for code\n- Structure longer responses with headers and lists\n- Reference file paths with line numbers when relevant (e.g., `src/index.ts:42`)\n\n## Security Guidelines\n\n- Do not introduce security vulnerabilities (injection, XSS, etc.)\n- Validate user inputs at boundaries\n- Do not execute untrusted code without sandboxing\n- Respect file system permissions and access controls\n\n### High-risk actions (confirm with the user first)\n\nThere is no automatic approval UI: **ask in the conversation** (or use `AskUserQuestion`) before proceeding when an action is destructive, hard to reverse, or affects others. Examples:\n- Deleting files or branches, dropping data, `rm -rf`, overwriting uncommitted work\n- Hard-to-reverse git: force-push, `reset --hard`, rewriting published history, amending shared commits\n- Actions visible outside this machine: pushing code, opening/closing/commenting on PRs or issues, sending messages, posting to external services, changing shared CI/CD or cloud permissions\n- Broad dependency or infrastructure changes (e.g. major version bumps, lockfile rewrites) when impact is unclear\n\nDefault to explaining what you intend and getting explicit agreement unless the user already directed that exact action.\n\n## Tool hooks\n\nWhen hooks are configured (e.g. PreToolUse), a tool call may be **blocked** or its **inputs adjusted** before execution. If a tool fails with a message indicating a hook blocked or rejected the call, **do not** retry the identical tool call unchanged \u2014 read the reason, change your approach, or ask the user. Treat hook feedback as binding policy from the environment.\n\n## Interaction Style\n\n- Be helpful and proactive\n- Ask clarifying questions when instructions are ambiguous\n- Provide suggestions when you see opportunities for improvement\n- Acknowledge limitations honestly\n- Maintain a professional, friendly tone";
+declare const DEFAULT_SYSTEM_PROMPT = "You are an AI assistant powered by the Agent SDK. You can help users with various tasks by using your built-in tools and capabilities.\n\n## Core Capabilities\n\n### Tools\nYou have access to a set of tools that allow you to:\n- **File Operations**: read, write, list, delete files and directories\n- **Code Execution**: run shell commands, Python scripts, Node.js code\n- **Web Access**: make HTTP requests, fetch webpages, download files\n- **Custom Tools**: additional tools registered by the user or skills\n\nWhen to use tools:\n- Use tools when the task requires real-world actions (file I/O, computation, API calls)\n- Prefer reading files before modifying them\n- Use the simplest tool that gets the job done\n- Run multiple independent tool calls in parallel when possible\n\n**Prefer dedicated tools over Bash:** Do not use `Bash` to do work that has a first-class tool. This keeps actions reviewable and consistent.\n- **Read** for file contents \u2014 not `cat`, `head`, `tail`, or `sed` to print files\n- **Write** to create or overwrite files \u2014 not shell redirection or heredocs\n- **Edit** for targeted file changes \u2014 not `sed`, `awk`, or ad-hoc scripts to patch files\n- **Glob** to find paths by pattern \u2014 not `find` or `ls` for discovery\n- **Grep** to search file contents \u2014 not `grep` or `rg` in the shell (built-in line-by-line regex search; correct integration)\n- **WebFetch** / **WebSearch** when the task needs HTTP or web search (when configured)\n- **TodoWrite** for structured multi-step task lists (see **Task Management with Todo List** below)\n\nReserve **Bash** for real shell needs: `git`, package managers, build commands, compilers, and other operations that require a shell or are not covered above.\n\n### Skills\nSkills are instruction guides for specialized tasks. When activated, you receive the skill's full content including any referenced file paths.\n\n{{SKILL_LIST}}\n\n**Usage:**\n- **Listing skills**: When the user asks about available skills (e.g., \"what skills do you have\", \"\u4F60\u6709\u54EA\u4E9B\u6280\u80FD\", \"list your skills\") \u2192 Simply describe the skills listed above. Do NOT activate any skill.\n- **Activating skills**: When the user has a specific task that matches a skill's purpose \u2192 Call `Skill` with the skill name, then follow the returned instructions.\n- After activation, use the provided Base Path to read any referenced files.\n\n### Sessions\n- Conversations are persisted in sessions\n- Use session IDs to maintain context across multiple interactions\n- Previous messages provide important context for current tasks\n\n## Task Execution Principles\n\n1. **Plan First for Complex Tasks**: For multi-step tasks, you MUST call `TodoWrite` BEFORE any other tool. Do NOT skip this step.\n2. **Be Direct**: Go straight to the point. Try the simplest approach first.\n3. **Be Concise**: If you can say it in one sentence, don't use three.\n4. **Read Before Modify**: Always understand existing code before changing it.\n5. **No Over-Engineering**: Only make changes directly requested or clearly necessary.\n6. **Prefer Edit Over Create**: Modify existing files rather than creating new ones when appropriate.\n7. **Handle Errors Gracefully**: Report errors clearly with actionable suggestions.\n\n## Task Management with Todo List\n\n**MANDATORY**: For multi-step tasks, call `TodoWrite` FIRST.\n\n**Workflow:**\n1. Receive complex task -> call `TodoWrite` immediately\n2. Mark tasks `in_progress` / `completed` as you work; several items may be `in_progress` at once when work is parallel\n3. **Replan freely:** if the plan was wrong or incomplete, call `TodoWrite` again with a revised full list (add, remove, reorder, or rewrite steps)\n4. **Before you finish your response** for a multi-step request, ensure **every** todo is `completed` via `TodoWrite` (unless you intentionally pause for a follow-up turn). Do not leave `pending` / `in_progress` items when the work is done\n\n**Example:**\nUser: \"Open Google, search X, summarize results, open first link, extract info\"\n-> Multi-step task detected -> call `TodoWrite` FIRST, then execute.\n\n## Output Format\n\n- Lead with the answer or action, not the reasoning\n- Skip filler words and unnecessary preamble\n- Use code blocks with language hints for code\n- Structure longer responses with headers and lists\n- Reference file paths with line numbers when relevant (e.g., `src/index.ts:42`)\n\n## Security Guidelines\n\n- Do not introduce security vulnerabilities (injection, XSS, etc.)\n- Validate user inputs at boundaries\n- Do not execute untrusted code without sandboxing\n- Respect file system permissions and access controls\n\n### High-risk actions (confirm with the user first)\n\nThere is no automatic approval UI: **ask in the conversation** (or use `AskUserQuestion`) before proceeding when an action is destructive, hard to reverse, or affects others. Examples:\n- Deleting files or branches, dropping data, `rm -rf`, overwriting uncommitted work\n- Hard-to-reverse git: force-push, `reset --hard`, rewriting published history, amending shared commits\n- Actions visible outside this machine: pushing code, opening/closing/commenting on PRs or issues, sending messages, posting to external services, changing shared CI/CD or cloud permissions\n- Broad dependency or infrastructure changes (e.g. major version bumps, lockfile rewrites) when impact is unclear\n\nDefault to explaining what you intend and getting explicit agreement unless the user already directed that exact action.\n\n## Tool hooks\n\nWhen hooks are configured (e.g. PreToolUse), a tool call may be **blocked** or its **inputs adjusted** before execution. If a tool fails with a message indicating a hook blocked or rejected the call, **do not** retry the identical tool call unchanged \u2014 read the reason, change your approach, or ask the user. Treat hook feedback as binding policy from the environment.\n\n## Interaction Style\n\n- Be helpful and proactive\n- Ask clarifying questions when instructions are ambiguous\n- Provide suggestions when you see opportunities for improvement\n- Acknowledge limitations honestly\n- Maintain a professional, friendly tone";
+
+declare function formatSDKLog(event: LogEvent): string;
+declare function createConsoleSDKLogger(): SDKLogger;
 
 /**
  * Same directory as {@link Agent} session storage: `<userBase>/.claude/sessions`.
@@ -562,6 +586,8 @@ declare function fromAsyncIterable(iterable: AsyncIterable<StreamEvent>): AgentS
 interface StreamChunkProcessorOptions {
     /** Emit `text_start` / `text_end` around assistant text deltas (Claude-style content blocks). Default true. */
     emitTextBoundaries?: boolean;
+    /** Emit `thinking_start` / `thinking_end` around assistant thinking deltas. Default true. */
+    emitThinkingBoundaries?: boolean;
 }
 /**
  * Stateful conversion from model `StreamChunk` to normalized `StreamEvent`s.
@@ -571,7 +597,9 @@ declare class StreamChunkProcessor {
     private currentToolCall;
     private lastUsage;
     private inTextBlock;
+    private inThinkingBlock;
     private readonly emitTextBoundaries;
+    private readonly emitThinkingBoundaries;
     constructor(options?: StreamChunkProcessorOptions);
     processChunk(chunk: StreamChunk): StreamEvent[];
     /** End open text block and finalize any in-progress streamed tool call. */
@@ -581,6 +609,16 @@ declare class StreamChunkProcessor {
     private safeParseJSON;
 }
 
+/**
+ * Builds the Agent-facing tool name for an MCP tool: `mcp__<serverName>__<toolName>`.
+ * Avoid `__` inside `serverName` or `toolName`; those segments are not escaped and would make parsing ambiguous.
+ */
+declare function formatMcpToolName(serverName: string, toolName: string): string;
+/**
+ * True if `name` matches the MCP-prefixed tool naming convention (at least `mcp__<server>__<tool>`).
+ */
+declare function isMcpPrefixedToolName(name: string): boolean;
+
 /**
  * 解析 SKILL.md 文件
  * 格式：
@@ -632,6 +670,8 @@ interface MCPConfigFile {
             args?: string[];
             /** 环境变量 */
             env?: Record<string, string>;
+            /** stdio 子进程工作目录 */
+            cwd?: string;
             /** URL (HTTP transport) */
             url?: string;
             /** HTTP headers */
@@ -661,4 +701,4 @@ declare function loadMCPConfig(configPath?: string, startDir?: string, userBaseP
  */
 declare function validateMCPConfig(config: MCPConfigFile): string[];
 
-export { Agent, AgentConfig, AgentResult, AgentStream, DEFAULT_SYSTEM_PROMPT, type HttpMCPConfig, JsonlStorage, MCPAdapter, MCPClient, type MCPClientConfig, type MCPConfigFile, type MCPConfigLoadResult, type MCPPrompt, type MCPResource, MCPServerConfig, type MCPTool, MemoryConfig, MemoryManager, MemoryStorage, Message, ParsedSkill, type PromptMessage, SessionInfo, SessionManager, SessionTokenUsage, SkillRegistry, type StdioMCPConfig, StorageAdapter, StorageConfig, StreamChunk, StreamChunkProcessor, type StreamChunkProcessorOptions, StreamEvent, type StreamOptions, SystemPrompt, TokenUsage, ToolDefinition, ToolRegistry, ToolResult, createAgent, createJsonlStorage, createMCPAdapter, createMCPClient, createMemoryStorage, createSessionManager, createStorage, createStream, fromAsyncIterable, getLatestSessionId, getSessionStoragePath, loadMCPConfig, parseSkillMd, validateMCPConfig };
+export { Agent, AgentConfig, AgentResult, AgentStream, DEFAULT_MAX_ITERATIONS, DEFAULT_SYSTEM_PROMPT, JsonlStorage, LogEvent, MCPAdapter, MCPClient, type MCPConfigFile, type MCPConfigLoadResult, type MCPPrompt, type MCPResource, MCPServerConfig, type MCPTool, MemoryConfig, MemoryManager, MemoryStorage, Message, ModelAdapter, PACKAGE_VERSION, ParsedSkill, type PromptMessage, SDKLogger, SessionInfo, SessionManager, SessionTokenUsage, SkillRegistry, StorageAdapter, StorageConfig, StreamChunk, StreamChunkProcessor, type StreamChunkProcessorOptions, StreamEvent, type StreamOptions, SystemPrompt, TokenUsage, ToolDefinition, ToolRegistry, ToolResult, createAgent, createConsoleSDKLogger, createJsonlStorage, createMCPAdapter, createMCPClient, createMemoryStorage, createSessionManager, createStorage, createStream, formatMcpToolName, formatSDKLog, fromAsyncIterable, getLatestSessionId, getSessionStoragePath, isMcpPrefixedToolName, loadMCPConfig, mergeMcpStdioEnv, mergeProcessEnv, parseSkillMd, validateMCPConfig };

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import './chunk-A3S3AGE3.js';
-export { Agent, DEFAULT_SYSTEM_PROMPT, JsonlStorage, MCPAdapter, MCPClient, MemoryManager, MemoryStorage, SessionManager, SkillLoader, SkillRegistry, StreamChunkProcessor, createAgent, createJsonlStorage, createMCPAdapter, createMCPClient, createMemoryStorage, createSessionManager, createSkillLoader, createSkillRegistry, createStorage, getLatestSessionId, getSessionStoragePath, loadMCPConfig, parseSkillMd, validateMCPConfig } from './chunk-Q3SOMX26.js';
-export { AnthropicAdapter, OllamaAdapter, OpenAIAdapter, createAnthropic, createModel, createOllama, createOpenAI } from './chunk-NDSL7NPN.js';
-export { DEFAULT_GREP_HEAD_LIMIT, HookManager, MAX_LINE_LENGTH, ToolRegistry, agentTool, bashTool, buildHookEnv, createAgentTool, createAskUserQuestionTool, createFunctionHook, 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-OHXW2YM6.js';
-import './chunk-WH3APNQ5.js';
+export { Agent, DEFAULT_MAX_ITERATIONS, DEFAULT_SYSTEM_PROMPT, JsonlStorage, MCPAdapter, MCPClient, MODEL_STREAM_EVENT_TYPES, MemoryManager, MemoryStorage, PACKAGE_VERSION, SessionManager, SkillLoader, SkillRegistry, StreamChunkProcessor, createAgent, createJsonlStorage, createMCPAdapter, createMCPClient, createMemoryStorage, createSessionManager, createSkillLoader, createSkillRegistry, createStorage, formatMcpToolName, getLatestSessionId, getSessionStoragePath, isMcpPrefixedToolName, isModelStreamEventType, loadMCPConfig, parseSkillMd, validateMCPConfig } from './chunk-EQ5CXH44.js';
+export { AnthropicAdapter, DEFAULT_ADAPTER_CAPABILITIES, OllamaAdapter, OpenAIAdapter, createAnthropic, createConsoleSDKLogger, createModel, createOllama, createOpenAI, formatSDKLog, mergeMcpStdioEnv, mergeProcessEnv } from './chunk-D3UZNLZO.js';
+export { DEFAULT_GREP_HEAD_LIMIT, HookManager, MAX_LINE_LENGTH, ToolRegistry, agentTool, bashTool, buildHookEnv, createAgentTool, createAskUserQuestionTool, createFunctionHook, 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, subagentRequestSchema, todoWriteTool, truncateMatchLineForDisplay, webFetchTool, webSearchTool, writeFileTool } from './chunk-MEJHTQJM.js';
+import './chunk-LOYIGOBZ.js';
 
 // src/streaming/event-emitter.ts
 var AgentStream = class _AgentStream {

package/dist/models/index.cjs

@@ -1,62 +1,66 @@
 #!/usr/bin/env node
 'use strict';
 
-var chunkX35MHWXE_cjs = require('../chunk-X35MHWXE.cjs');
-var chunkCNSGZVRN_cjs = require('../chunk-CNSGZVRN.cjs');
+var chunkNYZD3THB_cjs = require('../chunk-NYZD3THB.cjs');
+var chunkOZO7D77N_cjs = require('../chunk-OZO7D77N.cjs');
 
 
 
 Object.defineProperty(exports, "AnthropicAdapter", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.AnthropicAdapter; }
+  get: function () { return chunkNYZD3THB_cjs.AnthropicAdapter; }
+});
+Object.defineProperty(exports, "DEFAULT_ADAPTER_CAPABILITIES", {
+  enumerable: true,
+  get: function () { return chunkNYZD3THB_cjs.DEFAULT_ADAPTER_CAPABILITIES; }
 });
 Object.defineProperty(exports, "OllamaAdapter", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.OllamaAdapter; }
+  get: function () { return chunkNYZD3THB_cjs.OllamaAdapter; }
 });
 Object.defineProperty(exports, "OpenAIAdapter", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.OpenAIAdapter; }
+  get: function () { return chunkNYZD3THB_cjs.OpenAIAdapter; }
 });
 Object.defineProperty(exports, "createAnthropic", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.createAnthropic; }
+  get: function () { return chunkNYZD3THB_cjs.createAnthropic; }
 });
 Object.defineProperty(exports, "createModel", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.createModel; }
+  get: function () { return chunkNYZD3THB_cjs.createModel; }
 });
 Object.defineProperty(exports, "createOllama", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.createOllama; }
+  get: function () { return chunkNYZD3THB_cjs.createOllama; }
 });
 Object.defineProperty(exports, "createOpenAI", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.createOpenAI; }
+  get: function () { return chunkNYZD3THB_cjs.createOpenAI; }
 });
 Object.defineProperty(exports, "ollamaMessageContentToApiString", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.ollamaMessageContentToApiString; }
+  get: function () { return chunkNYZD3THB_cjs.ollamaMessageContentToApiString; }
 });
 Object.defineProperty(exports, "ollamaStreamChunksFromChatData", {
   enumerable: true,
-  get: function () { return chunkX35MHWXE_cjs.ollamaStreamChunksFromChatData; }
+  get: function () { return chunkNYZD3THB_cjs.ollamaStreamChunksFromChatData; }
 });
 Object.defineProperty(exports, "BaseModelAdapter", {
   enumerable: true,
-  get: function () { return chunkCNSGZVRN_cjs.BaseModelAdapter; }
+  get: function () { return chunkOZO7D77N_cjs.BaseModelAdapter; }
 });
 Object.defineProperty(exports, "mergeTokenUsage", {
   enumerable: true,
-  get: function () { return chunkCNSGZVRN_cjs.mergeTokenUsage; }
+  get: function () { return chunkOZO7D77N_cjs.mergeTokenUsage; }
 });
 Object.defineProperty(exports, "toolsToModelSchema", {
   enumerable: true,
-  get: function () { return chunkCNSGZVRN_cjs.toolsToModelSchema; }
+  get: function () { return chunkOZO7D77N_cjs.toolsToModelSchema; }
 });
 Object.defineProperty(exports, "zodToJsonSchema", {
   enumerable: true,
-  get: function () { return chunkCNSGZVRN_cjs.zodToJsonSchema; }
+  get: function () { return chunkOZO7D77N_cjs.zodToJsonSchema; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map