@ddlqhd/agent-sdk 0.1.0 → 0.2.0

package/dist/{chunk-Q3SOMX26.js → chunk-EQ5CXH44.js}

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-import { ToolRegistry, createAgentTool, HookManager, getAllBuiltinTools, getEnvironmentInfo, formatEnvironmentSection } from './chunk-OHXW2YM6.js';
-import { promises, existsSync, readFileSync } from 'fs';
-import { join, resolve } from 'path';
+import { createModel, emitSDKLog, mergeMcpStdioEnv } from './chunk-D3UZNLZO.js';
+import { ToolRegistry, createAgentTool, HookManager, getAllBuiltinTools, getEnvironmentInfo, formatEnvironmentSection } from './chunk-MEJHTQJM.js';
+import { readFileSync, promises, existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { randomUUID } from 'crypto';
 import { homedir } from 'os';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -11,6 +13,28 @@ import { z } from 'zod';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 
+var pkgDir = dirname(fileURLToPath(import.meta.url));
+var pkgPath = join(pkgDir, "..", "package.json");
+var PACKAGE_VERSION = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+
+// src/core/types.ts
+var MODEL_STREAM_EVENT_TYPES = [
+  "text_start",
+  "text_delta",
+  "text_end",
+  "tool_call_start",
+  "tool_call_delta",
+  "tool_call",
+  "tool_call_end",
+  "thinking_start",
+  "thinking",
+  "thinking_end",
+  "model_usage"
+];
+var MODEL_STREAM_EVENT_TYPE_SET = new Set(MODEL_STREAM_EVENT_TYPES);
+function isModelStreamEventType(type) {
+  return MODEL_STREAM_EVENT_TYPE_SET.has(type);
+}
 var JsonlStorage = class {
   basePath;
   constructor(config = {}) {
@@ -413,6 +437,7 @@ When to use tools:
 - **Glob** to find paths by pattern \u2014 not \`find\` or \`ls\` for discovery
 - **Grep** to search file contents \u2014 not \`grep\` or \`rg\` in the shell (built-in line-by-line regex search; correct integration)
 - **WebFetch** / **WebSearch** when the task needs HTTP or web search (when configured)
+- **TodoWrite** for structured multi-step task lists (see **Task Management with Todo List** below)
 
 Reserve **Bash** for real shell needs: \`git\`, package managers, build commands, compilers, and other operations that require a shell or are not covered above.
 
@@ -433,7 +458,7 @@ Skills are instruction guides for specialized tasks. When activated, you receive
 
 ## Task Execution Principles
 
-1. **Plan First for Complex Tasks**: For multi-step tasks, you MUST call \`TaskCreate\` BEFORE any other tool. Do NOT skip this step.
+1. **Plan First for Complex Tasks**: For multi-step tasks, you MUST call \`TodoWrite\` BEFORE any other tool. Do NOT skip this step.
 2. **Be Direct**: Go straight to the point. Try the simplest approach first.
 3. **Be Concise**: If you can say it in one sentence, don't use three.
 4. **Read Before Modify**: Always understand existing code before changing it.
@@ -443,17 +468,17 @@ Skills are instruction guides for specialized tasks. When activated, you receive
 
 ## Task Management with Todo List
 
-**MANDATORY**: For multi-step tasks, call \`TaskCreate\` FIRST.
+**MANDATORY**: For multi-step tasks, call \`TodoWrite\` FIRST.
 
 **Workflow:**
-1. Receive complex task -> call \`TaskCreate\` immediately
-2. Start first task (in_progress) -> complete -> mark completed
-3. Move to next task -> repeat
-4. Cancel tasks that become irrelevant
+1. Receive complex task -> call \`TodoWrite\` immediately
+2. Mark tasks \`in_progress\` / \`completed\` as you work; several items may be \`in_progress\` at once when work is parallel
+3. **Replan freely:** if the plan was wrong or incomplete, call \`TodoWrite\` again with a revised full list (add, remove, reorder, or rewrite steps)
+4. **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
 
 **Example:**
 User: "Open Google, search X, summarize results, open first link, extract info"
--> Multi-step task detected -> call \`TaskCreate\` FIRST, then execute.
+-> Multi-step task detected -> call \`TodoWrite\` FIRST, then execute.
 
 ## Output Format
 
@@ -554,8 +579,16 @@ ${combinedContent}
     };
   }
 };
-function isStdioConfig(config) {
-  return "command" in config;
+
+// src/mcp/mcp-tool-name.ts
+function formatMcpToolName(serverName, toolName) {
+  return `mcp__${serverName}__${toolName}`;
+}
+function isMcpPrefixedToolName(name) {
+  if (!name.startsWith("mcp__")) {
+    return false;
+  }
+  return name.slice("mcp__".length).includes("__");
 }
 var MCPClient = class {
   client;
@@ -567,16 +600,24 @@ var MCPClient = class {
   constructor(config) {
     this._name = config.name;
     this.client = new Client(
-      { name: "agent-sdk-client", version: "0.1.0" },
+      { name: "agent-sdk-client", version: PACKAGE_VERSION },
       { capabilities: {} }
     );
-    if (isStdioConfig(config)) {
+    if (config.transport === "stdio") {
+      if (!config.command) {
+        throw new Error(`MCP server "${config.name}": stdio transport requires command`);
+      }
+      const cwd = (config.cwd ?? "").trim();
       this.transport = new StdioClientTransport({
         command: config.command,
         args: config.args,
-        env: config.env
+        env: config.env,
+        ...cwd !== "" ? { cwd } : {}
       });
     } else {
+      if (!config.url) {
+        throw new Error(`MCP server "${config.name}": http transport requires url`);
+      }
       this.transport = new StreamableHTTPClientTransport(
         new URL(config.url),
         { requestInit: { headers: config.headers } }
@@ -685,7 +726,7 @@ var MCPClient = class {
   }
   toToolDefinitions() {
     return this._tools.map((tool) => ({
-      name: `mcp_${this._name}__${tool.name}`,
+      name: formatMcpToolName(this._name, tool.name),
       description: tool.description || `MCP tool: ${tool.name}`,
       parameters: this.convertSchema(tool.inputSchema),
       handler: async (args) => this.callTool(tool.name, args),
@@ -695,7 +736,7 @@ var MCPClient = class {
   }
   convertSchema(schema) {
     if (!schema || !schema.properties) {
-      return z.object({}).passthrough();
+      return z.looseObject({});
     }
     const shape = {};
     for (const [key, value] of Object.entries(schema.properties)) {
@@ -716,7 +757,7 @@ var MCPClient = class {
           zodField = z.array(z.any());
           break;
         case "object":
-          zodField = z.object({}).passthrough();
+          zodField = z.looseObject({});
           break;
         default:
           zodField = z.any();
@@ -760,7 +801,7 @@ var MCPAdapter = class {
     await client.connect();
     this.clients.set(config.name, client);
     for (const tool of client.tools) {
-      const fullName = `mcp_${config.name}__${tool.name}`;
+      const fullName = formatMcpToolName(config.name, tool.name);
       this.toolMap.set(fullName, { client, toolName: tool.name });
     }
   }
@@ -1312,9 +1353,12 @@ var StreamChunkProcessor = class {
   currentToolCall = null;
   lastUsage;
   inTextBlock = false;
+  inThinkingBlock = false;
   emitTextBoundaries;
+  emitThinkingBoundaries;
   constructor(options) {
     this.emitTextBoundaries = options?.emitTextBoundaries ?? true;
+    this.emitThinkingBoundaries = options?.emitThinkingBoundaries ?? true;
   }
   processChunk(chunk) {
     const events = [];
@@ -1324,8 +1368,15 @@ var StreamChunkProcessor = class {
         this.inTextBlock = false;
       }
     };
+    const endThinkingBlockIfNeeded = () => {
+      if (this.emitThinkingBoundaries && this.inThinkingBlock) {
+        events.push({ type: "thinking_end" });
+        this.inThinkingBlock = false;
+      }
+    };
     switch (chunk.type) {
       case "text":
+        endThinkingBlockIfNeeded();
         if (chunk.content) {
           if (this.emitTextBoundaries && !this.inTextBlock) {
             events.push({ type: "text_start" });
@@ -1335,6 +1386,7 @@ var StreamChunkProcessor = class {
         }
         break;
       case "tool_call_start":
+        endThinkingBlockIfNeeded();
         endTextBlockIfNeeded();
         if (this.currentToolCall) {
           events.push(...this.finalizeStreamingToolCall());
@@ -1380,6 +1432,7 @@ var StreamChunkProcessor = class {
         }
         break;
       case "tool_call": {
+        endThinkingBlockIfNeeded();
         endTextBlockIfNeeded();
         if (!chunk.toolCall) break;
         const tc = chunk.toolCall;
@@ -1398,6 +1451,7 @@ var StreamChunkProcessor = class {
         break;
       }
       case "tool_call_end":
+        endThinkingBlockIfNeeded();
         endTextBlockIfNeeded();
         if (this.currentToolCall) {
           events.push(...this.finalizeStreamingToolCall());
@@ -1405,6 +1459,16 @@ var StreamChunkProcessor = class {
         break;
       case "thinking":
         endTextBlockIfNeeded();
+        if (this.emitThinkingBoundaries) {
+          const opensBlock = !this.inThinkingBlock && (chunk.content !== void 0 || chunk.signature !== void 0);
+          if (opensBlock) {
+            events.push({
+              type: "thinking_start",
+              ...chunk.signature !== void 0 ? { signature: chunk.signature } : {}
+            });
+            this.inThinkingBlock = true;
+          }
+        }
         if (chunk.content !== void 0) {
           events.push({
             type: "thinking",
@@ -1413,7 +1477,12 @@ var StreamChunkProcessor = class {
           });
         }
         break;
+      case "thinking_block_end":
+        endThinkingBlockIfNeeded();
+        endTextBlockIfNeeded();
+        break;
       case "error":
+        endThinkingBlockIfNeeded();
         endTextBlockIfNeeded();
         if (chunk.error) {
           events.push({
@@ -1441,6 +1510,10 @@ var StreamChunkProcessor = class {
   /** End open text block and finalize any in-progress streamed tool call. */
   flush() {
     const events = [];
+    if (this.emitThinkingBoundaries && this.inThinkingBlock) {
+      events.push({ type: "thinking_end" });
+      this.inThinkingBlock = false;
+    }
     if (this.emitTextBoundaries && this.inTextBlock) {
       events.push({ type: "text_end" });
       this.inTextBlock = false;
@@ -1585,11 +1658,52 @@ var SummarizationCompressor = class {
     this.options = options;
   }
   name = "summarization";
+  getSessionId() {
+    return this.options.sessionIdProvider?.() ?? this.options.sessionId;
+  }
   async compress(messages, targetTokens) {
+    const startedAt = Date.now();
     const preserveRecent = this.options.preserveRecent ?? 6;
+    const sessionId = this.getSessionId();
+    emitSDKLog({
+      logger: this.options.logger,
+      logLevel: this.options.logLevel,
+      level: "info",
+      event: {
+        component: "memory",
+        event: "context.compress.start",
+        message: "Starting context compression",
+        operation: "compress",
+        sessionId,
+        metadata: {
+          compressor: this.name,
+          messageCount: messages.length,
+          targetTokens,
+          preserveRecent
+        }
+      }
+    });
     const systemMessages = messages.filter((m) => m.role === "system");
     const nonSystemMessages = messages.filter((m) => m.role !== "system");
     if (nonSystemMessages.length <= preserveRecent) {
+      emitSDKLog({
+        logger: this.options.logger,
+        logLevel: this.options.logLevel,
+        level: "debug",
+        event: {
+          component: "memory",
+          event: "context.compress.skipped",
+          message: "Skipped compression because there are not enough messages",
+          operation: "compress",
+          sessionId,
+          durationMs: Date.now() - startedAt,
+          metadata: {
+            compressor: this.name,
+            messageCount: messages.length,
+            preserveRecent
+          }
+        }
+      });
       return messages;
     }
     const recentMessages = nonSystemMessages.slice(-preserveRecent);
@@ -1599,21 +1713,68 @@ var SummarizationCompressor = class {
       this.options.maxSummaryTokens ?? 4e3,
       Math.floor(targetTokens * 0.3)
     );
-    const summaryResponse = await this.model.complete({
-      messages: [
-        { role: "system", content: summaryPrompt },
-        ...messagesToSummarize
-      ],
-      maxTokens
-    });
-    return [
-      ...systemMessages,
-      {
-        role: "system",
-        content: this.wrapSummary(summaryResponse.content)
-      },
-      ...recentMessages
-    ];
+    try {
+      const summaryResponse = await this.model.complete({
+        messages: [
+          { role: "system", content: summaryPrompt },
+          ...messagesToSummarize
+        ],
+        maxTokens,
+        logger: this.options.logger,
+        logLevel: this.options.logLevel,
+        redaction: this.options.redaction,
+        sessionId
+      });
+      const compressedMessages = [
+        ...systemMessages,
+        {
+          role: "system",
+          content: this.wrapSummary(summaryResponse.content)
+        },
+        ...recentMessages
+      ];
+      emitSDKLog({
+        logger: this.options.logger,
+        logLevel: this.options.logLevel,
+        level: "info",
+        event: {
+          component: "memory",
+          event: "context.compress.end",
+          message: "Context compression completed",
+          operation: "compress",
+          sessionId,
+          durationMs: Date.now() - startedAt,
+          metadata: {
+            compressor: this.name,
+            originalMessageCount: messages.length,
+            compressedMessageCount: compressedMessages.length
+          }
+        }
+      });
+      return compressedMessages;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      emitSDKLog({
+        logger: this.options.logger,
+        logLevel: this.options.logLevel,
+        level: "error",
+        event: {
+          component: "memory",
+          event: "context.compress.error",
+          message: "Context compression failed",
+          operation: "compress",
+          sessionId,
+          durationMs: Date.now() - startedAt,
+          errorName: err.name,
+          errorMessage: err.message,
+          metadata: {
+            compressor: this.name,
+            messageCount: messages.length
+          }
+        }
+      });
+      throw err;
+    }
   }
   /**
    * 构建默认摘要提示 (借鉴 Opencode 模板)
@@ -1799,21 +1960,7 @@ var ContextManager = class {
 };
 
 // src/core/agent.ts
-function toMCPClientConfig(config) {
-  if (config.transport === "http") {
-    return {
-      name: config.name,
-      url: config.url,
-      headers: config.headers
-    };
-  }
-  return {
-    name: config.name,
-    command: config.command,
-    args: config.args,
-    env: config.env
-  };
-}
+var DEFAULT_MAX_ITERATIONS = 400;
 var Agent = class _Agent {
   config;
   toolRegistry;
@@ -1831,22 +1978,39 @@ var Agent = class _Agent {
   // inputTokens/outputTokens: 累计消耗
   // totalTokens: 累计总消耗 (inputTokens + outputTokens)
   sessionUsage = _Agent.createEmptySessionUsage();
+  static resolveModel(config) {
+    if (config.model) {
+      if (config.modelConfig) {
+        throw new Error("AgentConfig: pass only one of `model` or `modelConfig`");
+      }
+      return config.model;
+    }
+    if (config.modelConfig) {
+      return createModel(config.modelConfig, config.env);
+    }
+    throw new Error("AgentConfig: `model` or `modelConfig` is required");
+  }
   constructor(config) {
+    const resolvedModel = _Agent.resolveModel(config);
     this.config = {
-      maxIterations: 200,
+      maxIterations: DEFAULT_MAX_ITERATIONS,
       streaming: true,
-      ...config
+      ...config,
+      model: resolvedModel,
+      modelConfig: void 0
     };
+    this.config.maxIterations = this.config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
     this.skillRegistry = createSkillRegistry({
-      cwd: config.cwd,
-      userBasePath: config.userBasePath
+      cwd: this.config.cwd,
+      userBasePath: this.config.userBasePath
     });
     this.toolRegistry = new ToolRegistry({
       executionPolicy: {
         disallowedTools: this.config.disallowedTools,
         allowedTools: this.config.allowedTools,
         canUseTool: this.config.canUseTool
-      }
+      },
+      hookObserver: this.config.callbacks?.lifecycle?.hooks
     });
     this.registerInitialTools();
     const subagentEnabled = this.config.subagent?.enabled !== false;
@@ -1860,23 +2024,40 @@ var Agent = class _Agent {
     } else if (this.toolRegistry.has("Agent")) {
       this.toolRegistry.unregister("Agent");
     }
-    if (config.hookManager) {
-      this.toolRegistry.setHookManager(config.hookManager);
-    } else if (config.hookConfigDir !== void 0) {
+    if (this.config.hookManager) {
+      this.toolRegistry.setHookManager(this.config.hookManager);
+    } else if (this.config.hookConfigDir !== void 0) {
       const hm = HookManager.create();
       this.toolRegistry.setHookManager(hm);
-      this.hookDiscoverPromise = hm.discoverAndLoad(config.hookConfigDir);
+      this.hookDiscoverPromise = hm.discoverAndLoad(this.config.hookConfigDir);
     }
     this.sessionManager = new SessionManager({
-      type: config.storage?.type || "jsonl",
-      basePath: getSessionStoragePath(config.userBasePath)
+      type: this.config.storage?.type || "jsonl",
+      basePath: getSessionStoragePath(this.config.userBasePath)
     });
-    if (config.contextManagement !== false) {
-      const cmConfig = config.contextManagement === true ? {} : config.contextManagement ?? {};
-      this.contextManager = new ContextManager(config.model, cmConfig);
+    if (this.config.contextManagement !== false) {
+      const cmConfig = this.config.contextManagement === true ? {} : this.config.contextManagement ?? {};
+      const compressor = cmConfig.compressor ?? new SummarizationCompressor(this.config.model, {
+        logger: this.config.logger,
+        logLevel: this.config.logLevel,
+        redaction: this.config.redaction,
+        sessionIdProvider: () => this.sessionManager.sessionId ?? void 0
+      });
+      this.contextManager = new ContextManager(this.config.model, {
+        ...cmConfig,
+        compressor
+      });
     }
     this.initPromise = this.initializeAsync();
   }
+  log(level, event) {
+    emitSDKLog({
+      logger: this.config.logger,
+      logLevel: this.config.logLevel,
+      level,
+      event
+    });
+  }
   /**
    * 注册内置 + 自定义工具，或仅 {@link AgentConfig.exclusiveTools}。
    */
@@ -1921,7 +2102,14 @@ var Agent = class _Agent {
         await this.initializeMCP(this.config.mcpServers);
       }
     } catch (err) {
-      console.error("Failed to initialize:", err);
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.log("error", {
+        component: "agent",
+        event: "agent.initialize.error",
+        message: "Failed to initialize agent resources",
+        errorName: error.name,
+        errorMessage: error.message
+      });
     }
   }
   /**
@@ -1940,7 +2128,17 @@ var Agent = class _Agent {
       try {
         await this.connectMCP(serverConfig);
       } catch (err) {
-        console.error(`Failed to connect MCP server "${serverConfig.name}":`, err);
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.log("error", {
+          component: "tooling",
+          event: "mcp.connect.error",
+          message: `Failed to connect MCP server "${serverConfig.name}"`,
+          errorName: error.name,
+          errorMessage: error.message,
+          metadata: {
+            serverName: serverConfig.name
+          }
+        });
       }
     }
   }
@@ -1952,6 +2150,74 @@ var Agent = class _Agent {
       sessionId: this.sessionManager.sessionId ?? void 0
     };
   }
+  baseRunContext() {
+    return {
+      sessionId: this.sessionManager.sessionId ?? void 0,
+      cwd: this.config.cwd
+    };
+  }
+  /**
+   * 分发流式事件到 `callbacks.onEvent` 与 `lifecycle.onModelEvent` / `onModelUsage`。
+   */
+  emitStreamEvent(event) {
+    try {
+      this.config.callbacks?.onEvent?.(event);
+      const lifecycle = this.config.callbacks?.lifecycle;
+      if (lifecycle?.onModelEvent && isModelStreamEventType(event.type)) {
+        lifecycle.onModelEvent(event);
+      }
+      if (event.type === "model_usage" && lifecycle?.onModelUsage) {
+        lifecycle.onModelUsage({
+          ...this.baseRunContext(),
+          usage: event.usage,
+          iteration: event.iteration,
+          phase: event.phase
+        });
+      }
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      this.emitAgentError(e, { phase: "lifecycle_callback" });
+    }
+  }
+  /** 标注、触发观察回调并返回供 `yield` 的事件 */
+  streamOut(event, iteration) {
+    const out = iteration !== void 0 ? this.annotateStreamEvent(event, iteration) : this.annotateStreamEvent(event);
+    this.emitStreamEvent(out);
+    return out;
+  }
+  emitAgentError(error, ctx) {
+    try {
+      this.config.callbacks?.lifecycle?.onAgentError?.(error, ctx);
+      this.config.callbacks?.onError?.(error, ctx);
+    } catch (err) {
+      this.log("error", {
+        component: "agent",
+        event: "agent.callback.error",
+        message: "Agent error callback threw",
+        errorName: err instanceof Error ? err.name : "Error",
+        errorMessage: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  safeLifecycleVoid(fn) {
+    try {
+      fn();
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      this.emitAgentError(e, { phase: "lifecycle_callback" });
+    }
+  }
+  emitRunEnd(args) {
+    this.safeLifecycleVoid(() => {
+      this.config.callbacks?.lifecycle?.onRunEnd?.({
+        ...this.baseRunContext(),
+        reason: args.reason,
+        iterations: args.iterations,
+        usage: args.usage,
+        error: args.error
+      });
+    });
+  }
   static createEmptySessionUsage() {
     return {
       contextTokens: 0,
@@ -2013,20 +2279,45 @@ ${content}`;
       }
       try {
         this.messages = await this.sessionManager.resumeSession(options.sessionId);
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onSessionResume?.({
+            sessionId: options.sessionId,
+            messageCount: this.messages.length
+          });
+        });
       } catch {
         this.sessionManager.createSession(options.sessionId);
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onSessionCreate?.({
+            sessionId: this.sessionManager.sessionId ?? void 0
+          });
+        });
       }
     } else if (!this.sessionManager.sessionId) {
       this.resetSessionState();
       this.sessionManager.createSession();
+      this.safeLifecycleVoid(() => {
+        this.config.callbacks?.lifecycle?.onSessionCreate?.({
+          sessionId: this.sessionManager.sessionId ?? void 0
+        });
+      });
     }
     if (this.messages.length === 0) {
+      const usedRuntimePrompt = options?.systemPrompt !== void 0;
       const systemPrompt = this.buildSystemPrompt(
         options?.systemPrompt || this.config.systemPrompt
       );
-      this.messages.push({
+      const sysMsg = {
         role: "system",
         content: systemPrompt
+      };
+      this.messages.push(sysMsg);
+      this.safeLifecycleVoid(() => {
+        this.config.callbacks?.lifecycle?.onSystemMessage?.(
+          sysMsg,
+          usedRuntimePrompt ? "runtime_prompt" : "default_prompt",
+          this.baseRunContext()
+        );
       });
     }
     if (this.config.memory !== false) {
@@ -2035,9 +2326,13 @@ ${content}`;
         const memoryManager = new MemoryManager(this.config.cwd, this.config.memoryConfig, this.config.userBasePath);
         const memoryContent = memoryManager.loadMemory();
         if (memoryContent) {
-          this.messages.push({
+          const memMsg = {
             role: "system",
             content: memoryContent
+          };
+          this.messages.push(memMsg);
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onSystemMessage?.(memMsg, "memory", this.baseRunContext());
           });
         }
       }
@@ -2047,21 +2342,60 @@ ${content}`;
     if (processed.invoked) {
       processedInput = processed.prompt;
     }
-    this.messages.push({
+    const userMsg = {
       role: "user",
       content: processedInput
+    };
+    this.messages.push(userMsg);
+    this.safeLifecycleVoid(() => {
+      this.config.callbacks?.lifecycle?.onUserMessage?.(
+        userMsg,
+        processed.invoked ? "processed_input" : "raw_input",
+        this.baseRunContext()
+      );
     });
-    yield this.annotateStreamEvent({ type: "start", timestamp: Date.now() });
+    this.log("info", {
+      component: "agent",
+      event: "agent.run.start",
+      message: "Starting agent turn",
+      sessionId: this.sessionManager.sessionId ?? void 0,
+      metadata: {
+        inputLength: input.length,
+        processedInputLength: processedInput.length,
+        includeRawStreamEvents: options?.includeRawStreamEvents === true
+      }
+    });
+    this.safeLifecycleVoid(() => {
+      this.config.callbacks?.lifecycle?.onRunStart?.({
+        ...this.baseRunContext(),
+        inputLength: input.length,
+        processedInputLength: processedInput.length,
+        resumeSessionId: options?.sessionId
+      });
+    });
+    yield this.streamOut({ type: "start", timestamp: Date.now() });
     try {
-      const maxIterations = this.config.maxIterations || 10;
+      const maxIterations = Math.max(1, this.config.maxIterations ?? DEFAULT_MAX_ITERATIONS);
       let totalUsage = {
         promptTokens: 0,
         completionTokens: 0,
         totalTokens: 0
       };
-      for (let iteration = 0; iteration < maxIterations; iteration++) {
+      let iteration = 0;
+      for (; iteration < maxIterations; iteration++) {
         if (signal?.aborted) {
-          yield this.annotateStreamEvent(
+          this.log("info", {
+            component: "agent",
+            event: "agent.run.aborted",
+            message: "Agent turn aborted before model request",
+            sessionId: this.sessionManager.sessionId ?? void 0,
+            iteration
+          });
+          this.emitRunEnd({ reason: "aborted", iterations: iteration, usage: totalUsage });
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onRunAbort?.({ ...this.baseRunContext(), iteration });
+          });
+          yield this.streamOut(
             {
               type: "end",
               usage: totalUsage,
@@ -2072,17 +2406,60 @@ ${content}`;
           );
           return;
         }
+        this.log("debug", {
+          component: "agent",
+          event: "agent.iteration.start",
+          message: "Starting agent iteration",
+          sessionId: this.sessionManager.sessionId ?? void 0,
+          iteration,
+          metadata: {
+            messageCount: this.messages.length,
+            toolCount: this.toolRegistry.getAll().length
+          }
+        });
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onIterationStart?.({
+            ...this.baseRunContext(),
+            iteration,
+            messageCount: this.messages.length,
+            toolCount: this.toolRegistry.getAll().length
+          });
+        });
         const contextEvents = await this.checkContextCompression();
         for (const event of contextEvents) {
-          yield this.annotateStreamEvent(event, iteration);
+          if (event.type === "context_compressed") {
+            this.safeLifecycleVoid(() => {
+              this.config.callbacks?.lifecycle?.onContextCompressed?.({
+                ...this.baseRunContext(),
+                iteration,
+                stats: event.stats
+              });
+            });
+          }
+          yield this.streamOut(event, iteration);
         }
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onModelRequestStart?.({
+            ...this.baseRunContext(),
+            iteration,
+            messageCount: this.messages.length,
+            toolCount: this.toolRegistry.getAll().length,
+            temperature: this.config.temperature,
+            maxTokens: this.config.maxTokens,
+            includeRawStreamEvents: options?.includeRawStreamEvents
+          });
+        });
         const modelParams = {
           messages: this.messages,
           tools: this.toolRegistry.getAll(),
           temperature: this.config.temperature,
           maxTokens: this.config.maxTokens,
           signal,
-          includeRawStreamEvents: options?.includeRawStreamEvents
+          includeRawStreamEvents: options?.includeRawStreamEvents,
+          sessionId: this.sessionManager.sessionId ?? void 0,
+          logger: this.config.logger,
+          logLevel: this.config.logLevel,
+          redaction: this.config.redaction
         };
         const stream = this.config.model.stream(modelParams);
         let hasToolCalls = false;
@@ -2125,7 +2502,7 @@ ${content}`;
         for await (const chunk of stream) {
           if (signal?.aborted) {
             for (const event of chunkProcessor.flush()) {
-              const out = this.annotateStreamEvent(event, iteration);
+              const out = this.streamOut(event, iteration);
               yield out;
               applyStreamOut(out);
             }
@@ -2141,13 +2518,37 @@ ${content}`;
                 ];
               }
               this.messages.push(assistantMessage2);
+              this.safeLifecycleVoid(() => {
+                this.config.callbacks?.lifecycle?.onAssistantMessage?.(assistantMessage2, {
+                  ...this.baseRunContext(),
+                  iteration
+                });
+              });
             }
-            this.messages.push({
+            const interruptMsg = {
               role: "user",
               content: "[User interrupted the response]"
+            };
+            this.messages.push(interruptMsg);
+            this.safeLifecycleVoid(() => {
+              this.config.callbacks?.lifecycle?.onUserMessage?.(
+                interruptMsg,
+                "interruption_marker",
+                this.baseRunContext()
+              );
             });
             await this.sessionManager.saveMessages(this.messages);
-            yield this.annotateStreamEvent(
+            this.safeLifecycleVoid(() => {
+              this.config.callbacks?.lifecycle?.onMessagePersist?.({
+                ...this.baseRunContext(),
+                messageCount: this.messages.length
+              });
+            });
+            this.emitRunEnd({ reason: "aborted", iterations: iteration + 1, usage: totalUsage });
+            this.safeLifecycleVoid(() => {
+              this.config.callbacks?.lifecycle?.onRunAbort?.({ ...this.baseRunContext(), iteration });
+            });
+            yield this.streamOut(
               {
                 type: "end",
                 usage: totalUsage,
@@ -2161,9 +2562,18 @@ ${content}`;
           }
           const events = chunkProcessor.processChunk(chunk);
           for (const event of events) {
-            const out = this.annotateStreamEvent(event, iteration);
+            const out = this.streamOut(event, iteration);
             yield out;
             applyStreamOut(out);
+            if (out.type === "end" && out.reason === "error" && out.error) {
+              this.emitAgentError(out.error, { phase: "model", iteration });
+              this.safeLifecycleVoid(() => {
+                this.config.callbacks?.lifecycle?.onModelRequestError?.(out.error, {
+                  phase: "model",
+                  iteration
+                });
+              });
+            }
             if (out.type === "end" && out.reason === "error") {
               fatalModelError = true;
               break;
@@ -2177,10 +2587,13 @@ ${content}`;
           return;
         }
         for (const event of chunkProcessor.flush()) {
-          const out = this.annotateStreamEvent(event, iteration);
+          const out = this.streamOut(event, iteration);
           yield out;
           applyStreamOut(out);
         }
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onModelRequestEnd?.({ ...this.baseRunContext(), iteration });
+        });
         const assistantMessage = {
           role: "assistant",
           content: assistantContent
@@ -2202,13 +2615,36 @@ ${content}`;
           assistantMessage.toolCalls = toolCalls;
         }
         this.messages.push(assistantMessage);
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onAssistantMessage?.(assistantMessage, {
+            ...this.baseRunContext(),
+            iteration
+          });
+        });
         if (!hasToolCalls) {
+          this.log("debug", {
+            component: "agent",
+            event: "agent.iteration.end",
+            message: "Iteration completed without tool calls",
+            sessionId: this.sessionManager.sessionId ?? void 0,
+            iteration,
+            metadata: {
+              assistantContentLength: assistantContent.length
+            }
+          });
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onIterationEnd?.({
+              ...this.baseRunContext(),
+              iteration,
+              hadToolCalls: false
+            });
+          });
           break;
         }
-        const toolResults = await this.executeTools(toolCalls);
+        const toolResults = await this.executeTools(toolCalls, iteration);
         for (const result of toolResults) {
           if (result.isError && result.error) {
-            yield this.annotateStreamEvent(
+            yield this.streamOut(
               {
                 type: "tool_error",
                 toolCallId: result.toolCallId,
@@ -2217,7 +2653,7 @@ ${content}`;
               iteration
             );
           }
-          yield this.annotateStreamEvent(
+          yield this.streamOut(
             {
               type: "tool_result",
               toolCallId: result.toolCallId,
@@ -2225,38 +2661,110 @@ ${content}`;
             },
             iteration
           );
-          this.messages.push({
+          const toolMsg = {
             role: "tool",
             toolCallId: result.toolCallId,
             content: result.content
+          };
+          this.messages.push(toolMsg);
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onToolMessage?.(toolMsg, {
+              ...this.baseRunContext(),
+              iteration,
+              toolCallId: result.toolCallId
+            });
           });
         }
+        this.log("debug", {
+          component: "agent",
+          event: "agent.iteration.end",
+          message: "Iteration completed with tool calls",
+          sessionId: this.sessionManager.sessionId ?? void 0,
+          iteration,
+          metadata: {
+            toolCallCount: toolCalls.length,
+            toolResultCount: toolResults.length
+          }
+        });
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onIterationEnd?.({
+            ...this.baseRunContext(),
+            iteration,
+            hadToolCalls: true
+          });
+        });
       }
       await this.sessionManager.saveMessages(this.messages);
-      yield this.annotateStreamEvent({
+      this.safeLifecycleVoid(() => {
+        this.config.callbacks?.lifecycle?.onMessagePersist?.({
+          ...this.baseRunContext(),
+          messageCount: this.messages.length
+        });
+      });
+      const finishedByIterationCap = iteration >= maxIterations;
+      const sessionIterations = finishedByIterationCap ? maxIterations : iteration + 1;
+      yield this.streamOut({
         type: "session_summary",
         usage: totalUsage,
-        iterations: Math.min(maxIterations, this.messages.length)
+        iterations: sessionIterations
       });
-      yield this.annotateStreamEvent({
+      this.emitRunEnd({
+        reason: finishedByIterationCap ? "max_iterations" : "complete",
+        iterations: sessionIterations,
+        usage: totalUsage
+      });
+      yield this.streamOut({
         type: "end",
         timestamp: Date.now(),
-        reason: "complete"
+        reason: finishedByIterationCap ? "max_iterations" : "complete"
+      });
+      this.log("info", {
+        component: "agent",
+        event: "agent.run.end",
+        message: finishedByIterationCap ? "Agent turn stopped at max iterations" : "Agent turn completed",
+        sessionId: this.sessionManager.sessionId ?? void 0,
+        metadata: {
+          iterations: sessionIterations,
+          promptTokens: totalUsage.promptTokens,
+          completionTokens: totalUsage.completionTokens,
+          totalTokens: totalUsage.totalTokens
+        }
       });
     } catch (error) {
       if (error.name === "AbortError") {
-        yield this.annotateStreamEvent({
+        this.log("info", {
+          component: "agent",
+          event: "agent.run.aborted",
+          message: "Agent turn aborted",
+          sessionId: this.sessionManager.sessionId ?? void 0
+        });
+        this.emitRunEnd({ reason: "aborted", iterations: 0 });
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onRunAbort?.({ ...this.baseRunContext() });
+        });
+        yield this.streamOut({
           type: "end",
           timestamp: Date.now(),
           reason: "aborted"
         });
         return;
       }
-      yield this.annotateStreamEvent({
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.log("error", {
+        component: "agent",
+        event: "agent.run.error",
+        message: "Agent turn failed",
+        sessionId: this.sessionManager.sessionId ?? void 0,
+        errorName: err.name,
+        errorMessage: err.message
+      });
+      this.emitAgentError(err, { phase: "run" });
+      this.emitRunEnd({ reason: "error", iterations: 0, error: err });
+      yield this.streamOut({
         type: "end",
         timestamp: Date.now(),
         reason: "error",
-        error
+        error: err
       });
     }
   }
@@ -2348,6 +2856,12 @@ ${content}`;
   getSkillRegistry() {
     return this.skillRegistry;
   }
+  /**
+   * 解析后的模型适配器（`modelConfig` 已在构造时合并 `env` 并实例化）。
+   */
+  getModel() {
+    return this.config.model;
+  }
   /**
    * 处理用户输入，检测并处理 skill 调用
    * @param input 用户输入
@@ -2433,10 +2947,16 @@ ARGUMENTS: ${args}`;
     if (!this.mcpAdapter) {
       this.mcpAdapter = new MCPAdapter();
     }
-    await this.mcpAdapter.addServer(toMCPClientConfig(config));
+    const resolved = config.transport === "stdio" ? {
+      ...config,
+      env: mergeMcpStdioEnv(this.config.env, config.env),
+      cwd: (config.cwd ?? "").trim() || (this.config.cwd || process.cwd())
+    } : config;
+    await this.mcpAdapter.addServer(resolved);
     const mcpTools = this.mcpAdapter.getToolDefinitions();
+    const serverPrefix = formatMcpToolName(config.name, "");
     for (const tool of mcpTools) {
-      if (!tool.name.startsWith(`mcp_${config.name}__`)) {
+      if (!tool.name.startsWith(serverPrefix)) {
         continue;
       }
       if (this.toolRegistry.isDisallowed(tool.name)) {
@@ -2452,7 +2972,7 @@ ARGUMENTS: ${args}`;
     if (!this.mcpAdapter) return;
     const tools = this.toolRegistry.getAll();
     for (const tool of tools) {
-      if (tool.name.startsWith(`mcp_${name}__`)) {
+      if (tool.name.startsWith(formatMcpToolName(name, ""))) {
         this.toolRegistry.unregister(tool.name);
       }
     }
@@ -2465,7 +2985,7 @@ ARGUMENTS: ${args}`;
     if (!this.mcpAdapter) return;
     const tools = this.toolRegistry.getAll();
     for (const tool of tools) {
-      if (tool.name.startsWith("mcp_") && tool.name.includes("__")) {
+      if (isMcpPrefixedToolName(tool.name)) {
         this.toolRegistry.unregister(tool.name);
       }
     }
@@ -2638,7 +3158,10 @@ ${additionalContent}`;
     const normalizedType = request.subagent_type ?? "general-purpose";
     const requestedTimeout = request.timeout_ms ?? subagentConfig.timeoutMs;
     const timeoutMs = Math.min(requestedTimeout, subagentConfig.timeoutMs);
-    const maxIterations = Math.max(1, request.max_iterations ?? this.config.maxIterations ?? 50);
+    const maxIterations = Math.max(
+      1,
+      request.max_iterations ?? this.config.maxIterations ?? DEFAULT_MAX_ITERATIONS
+    );
     const resolved = this.resolveSubagentTools(request);
     if (!resolved.tools) {
       return {
@@ -2710,21 +3233,158 @@ ${additionalContent}`;
   /**
    * 执行工具调用
    */
-  async executeTools(toolCalls) {
+  async executeTools(toolCalls, iteration) {
     const results = await Promise.all(
       toolCalls.map(async (tc) => {
-        const result = await this.toolRegistry.execute(tc.name, tc.arguments, {
-          toolCallId: tc.id,
-          projectDir: this.config.cwd || process.cwd(),
-          agentDepth: this.agentDepth
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onToolCallPlanned?.(tc, {
+            ...this.baseRunContext(),
+            iteration
+          });
         });
-        const isError = Boolean(result.isError);
-        return {
-          toolCallId: tc.id,
-          content: isError ? `Error: ${result.content}` : result.content,
-          isError,
-          error: isError ? new Error(result.content) : void 0
-        };
+        const startedAt = Date.now();
+        this.safeLifecycleVoid(() => {
+          this.config.callbacks?.lifecycle?.onToolExecutionStart?.({
+            ...this.baseRunContext(),
+            iteration,
+            toolCallId: tc.id,
+            toolName: tc.name,
+            arguments: tc.arguments,
+            projectDir: this.config.cwd || process.cwd(),
+            agentDepth: this.agentDepth
+          });
+        });
+        this.log("info", {
+          component: "tooling",
+          event: "tool.call.start",
+          message: "Executing tool call",
+          sessionId: this.sessionManager.sessionId ?? void 0,
+          toolName: tc.name,
+          toolCallId: tc.id
+        });
+        try {
+          const result = await this.toolRegistry.execute(tc.name, tc.arguments, {
+            toolCallId: tc.id,
+            projectDir: this.config.cwd || process.cwd(),
+            agentDepth: this.agentDepth
+          });
+          const durationMs = Date.now() - startedAt;
+          const isError = Boolean(result.isError);
+          const error = isError ? new Error(result.content) : void 0;
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onToolExecutionEnd?.({
+              ...this.baseRunContext(),
+              iteration,
+              toolCallId: tc.id,
+              toolName: tc.name,
+              arguments: tc.arguments,
+              projectDir: this.config.cwd || process.cwd(),
+              agentDepth: this.agentDepth,
+              durationMs,
+              isError,
+              executionError: void 0
+            });
+          });
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onToolResult?.({
+              ...this.baseRunContext(),
+              iteration,
+              toolCallId: tc.id,
+              toolName: tc.name,
+              arguments: tc.arguments,
+              projectDir: this.config.cwd || process.cwd(),
+              agentDepth: this.agentDepth,
+              durationMs,
+              isError,
+              result
+            });
+          });
+          this.log(isError ? "warn" : "info", {
+            component: "tooling",
+            event: isError ? "tool.call.error" : "tool.call.end",
+            message: isError ? "Tool call returned an error" : "Tool call completed",
+            sessionId: this.sessionManager.sessionId ?? void 0,
+            toolName: tc.name,
+            toolCallId: tc.id,
+            durationMs,
+            ...error ? {
+              errorName: error.name,
+              errorMessage: error.message
+            } : {},
+            metadata: {
+              resultLength: result.content.length
+            }
+          });
+          return {
+            toolCallId: tc.id,
+            content: isError ? `Error: ${result.content}` : result.content,
+            isError,
+            error
+          };
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          const durationMs = Date.now() - startedAt;
+          const synthetic = { content: err.message, isError: true };
+          this.emitAgentError(err, {
+            phase: "tool",
+            toolName: tc.name,
+            toolCallId: tc.id,
+            iteration
+          });
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onToolExecutionError?.(err, {
+              phase: "tool",
+              toolName: tc.name,
+              toolCallId: tc.id,
+              iteration
+            });
+          });
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onToolExecutionEnd?.({
+              ...this.baseRunContext(),
+              iteration,
+              toolCallId: tc.id,
+              toolName: tc.name,
+              arguments: tc.arguments,
+              projectDir: this.config.cwd || process.cwd(),
+              agentDepth: this.agentDepth,
+              durationMs,
+              isError: true,
+              executionError: err
+            });
+          });
+          this.safeLifecycleVoid(() => {
+            this.config.callbacks?.lifecycle?.onToolResult?.({
+              ...this.baseRunContext(),
+              iteration,
+              toolCallId: tc.id,
+              toolName: tc.name,
+              arguments: tc.arguments,
+              projectDir: this.config.cwd || process.cwd(),
+              agentDepth: this.agentDepth,
+              durationMs,
+              isError: true,
+              result: synthetic
+            });
+          });
+          this.log("error", {
+            component: "tooling",
+            event: "tool.call.error",
+            message: "Tool call threw an exception",
+            sessionId: this.sessionManager.sessionId ?? void 0,
+            toolName: tc.name,
+            toolCallId: tc.id,
+            durationMs,
+            errorName: err.name,
+            errorMessage: err.message
+          });
+          return {
+            toolCallId: tc.id,
+            content: `Error: ${err.message}`,
+            isError: true,
+            error: err
+          };
+        }
       })
     );
     return results;
@@ -2768,7 +3428,8 @@ function transformConfig(config) {
       ...transport === "stdio" ? {
         command: serverConfig.command,
         args: serverConfig.args,
-        env: serverConfig.env
+        env: serverConfig.env,
+        cwd: serverConfig.cwd
       } : {
         url: serverConfig.url,
         headers: serverConfig.headers
@@ -2849,6 +3510,6 @@ function validateMCPConfig(config) {
   return errors;
 }
 
-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 };
-//# sourceMappingURL=chunk-Q3SOMX26.js.map
-//# sourceMappingURL=chunk-Q3SOMX26.js.map
+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 };
+//# sourceMappingURL=chunk-EQ5CXH44.js.map
+//# sourceMappingURL=chunk-EQ5CXH44.js.map