@ai-setting/roy-agent-cli 1.7.19 → 1.7.21

package/dist/bin/roy-agent.js

@@ -360,6 +360,97 @@ var init_markdown_renderer = __esm(() => {
   ], MarkdownRenderer.prototype, "push", null);
 });
 
+// src/services/stdout-batcher.ts
+function createStdoutBatcher(options = {}) {
+  const flushIntervalMs = options.flushIntervalMs ?? 16;
+  const maxBufferBytes = options.maxBufferBytes ?? 4096;
+  const writeFn = options.writeFn ?? ((chunk) => {
+    process.stdout.write(chunk);
+    return true;
+  });
+  const onFlush = options.onFlush;
+  let buffer = "";
+  let queuedWrites = 0;
+  let timer = null;
+  let totalBatches = 0;
+  let totalWrites = 0;
+  let totalBytes = 0;
+  let lastBatchWrites = 0;
+  function performFlush() {
+    if (buffer.length === 0)
+      return;
+    const chunk = buffer;
+    buffer = "";
+    lastBatchWrites = queuedWrites;
+    queuedWrites = 0;
+    totalBatches += 1;
+    totalBytes += chunk.length;
+    writeFn(chunk);
+    if (onFlush) {
+      onFlush({
+        writesInLastBatch: lastBatchWrites,
+        totalBatches,
+        totalBytes
+      });
+    }
+  }
+  function scheduleFlush() {
+    if (timer !== null)
+      return;
+    timer = setTimeout(() => {
+      timer = null;
+      performFlush();
+    }, flushIntervalMs);
+  }
+  function maybeForceFlush() {
+    if (buffer.length >= maxBufferBytes) {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      performFlush();
+    }
+  }
+  function write(chunk) {
+    if (chunk.length === 0)
+      return;
+    buffer += chunk;
+    queuedWrites += 1;
+    totalWrites += 1;
+    scheduleFlush();
+    maybeForceFlush();
+  }
+  function flushNow() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    performFlush();
+  }
+  function cancel() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    buffer = "";
+    queuedWrites = 0;
+  }
+  function getStats() {
+    return {
+      batches: totalBatches,
+      queuedWrites: totalWrites,
+      totalBytes,
+      writesInLastBatch: lastBatchWrites
+    };
+  }
+  return {
+    write,
+    flushNow,
+    cancel,
+    getStats
+  };
+}
+
 // src/services/stream-output.service.ts
 var exports_stream_output_service = {};
 __export(exports_stream_output_service, {
@@ -370,14 +461,26 @@ __export(exports_stream_output_service, {
   COLORS: () => COLORS
 });
 import chalk2 from "chalk";
-import { createLogger as createLogger2, TracedAs as TracedAs2 } from "@ai-setting/roy-agent-core";
+import {
+  createLogger as createLogger2,
+  TracedAs as TracedAs2,
+  wrapFunction
+} from "@ai-setting/roy-agent-core";
+function isStdoutBatchEnabled() {
+  const v = process.env.ROY_AGENT_BATCH_STDOUT;
+  if (v === undefined)
+    return true;
+  if (v === "0" || v === "false" || v === "no")
+    return false;
+  return true;
+}
 function resetStreamAbort() {
   streamAbortSignal.aborted = false;
 }
 function abortStream() {
   streamAbortSignal.aborted = true;
 }
-var logger2, COLORS, streamAbortSignal, StreamOutputService;
+var logger2, COLORS, emitBatchFlushSpanImpl = (stats) => {}, emitBatchFlushSpan, emitSilentModeSkippedSpanImpl = (textLength) => {}, emitSilentModeSkippedSpan, streamAbortSignal, StreamOutputService;
 var init_stream_output_service = __esm(() => {
   init_markdown_renderer();
   logger2 = createLogger2("stream-output");
@@ -397,6 +500,28 @@ var init_stream_output_service = __esm(() => {
     error: chalk2.red,
     progress: chalk2.dim
   };
+  emitBatchFlushSpan = wrapFunction(emitBatchFlushSpanImpl, "cli.stream-output.writeStdout-batched", {
+    recordParams: true,
+    recordResult: false,
+    log: false,
+    paramFilter: (args) => {
+      const s = args[0] ?? {};
+      return {
+        writesInLastBatch: s.writesInLastBatch ?? 0,
+        totalBatches: s.batches ?? 0,
+        totalBytes: s.totalBytes ?? 0
+      };
+    }
+  });
+  emitSilentModeSkippedSpan = wrapFunction(emitSilentModeSkippedSpanImpl, "stream-output.silent-mode-skipped", {
+    recordParams: true,
+    recordResult: false,
+    log: false,
+    paramFilter: (args) => ({
+      "text.length": typeof args[0] === "number" ? args[0] : 0,
+      reason: "silent=true (Ink mode)"
+    })
+  });
   streamAbortSignal = {
     aborted: false
   };
@@ -415,6 +540,7 @@ var init_stream_output_service = __esm(() => {
     reasoningClosedByText = false;
     chunkCallback = undefined;
     silent = false;
+    stdoutBatcher = null;
     constructor(options = {}) {
       this.options = options;
       this.silent = options.silent ?? false;
@@ -439,9 +565,33 @@ var init_stream_output_service = __esm(() => {
       }
     }
     writeStdout(text) {
-      if (this.silent)
+      if (this.silent) {
+        emitSilentModeSkippedSpan(text.length);
         return;
-      process.stdout.write(text);
+      }
+      if (!isStdoutBatchEnabled()) {
+        process.stdout.write(text);
+        return;
+      }
+      if (this.stdoutBatcher === null) {
+        this.stdoutBatcher = createStdoutBatcher({
+          flushIntervalMs: 16,
+          onFlush: (stats) => {
+            emitBatchFlushSpan(stats);
+          }
+        });
+      }
+      this.stdoutBatcher.write(text);
+    }
+    flushStdout() {
+      if (this.stdoutBatcher !== null) {
+        this.stdoutBatcher.flushNow();
+      }
+    }
+    cancelStdout() {
+      if (this.stdoutBatcher !== null) {
+        this.stdoutBatcher.cancel();
+      }
     }
     logStdout(message) {
       if (this.silent)
@@ -686,8 +836,60 @@ ${COLORS.system("[已中断]")}
       this.reasoningStarted = false;
       this.reasoningClosedByText = false;
       this.thinkingPrinted = false;
+      this.flushStdout();
     }
   };
+  __legacyDecorateClassTS([
+    TracedAs2("cli.stream-output.writeStdout", {
+      recordParams: true,
+      recordResult: false,
+      log: false,
+      paramFilter: (args) => ({
+        "text.length": typeof args[0] === "string" ? args[0].length : 0,
+        "text.head": typeof args[0] === "string" ? args[0].slice(0, 32) : "",
+        "text.tail": typeof args[0] === "string" ? args[0].slice(-32) : "",
+        "batch.enabled": isStdoutBatchEnabled() ? 1 : 0
+      })
+    }),
+    __legacyMetadataTS("design:type", Function),
+    __legacyMetadataTS("design:paramtypes", [
+      String
+    ]),
+    __legacyMetadataTS("design:returntype", undefined)
+  ], StreamOutputService.prototype, "writeStdout", null);
+  __legacyDecorateClassTS([
+    TracedAs2("stream.handle-event", {
+      recordParams: true,
+      recordResult: false,
+      paramFilter: (args) => {
+        const e = args[0] ?? {};
+        const payload = e.payload ?? {};
+        return {
+          "event.type": e.type ?? "unknown",
+          "event.payload.kind": payload && typeof payload === "object" ? Object.keys(payload).join(",") : ""
+        };
+      }
+    }),
+    __legacyMetadataTS("design:type", Function),
+    __legacyMetadataTS("design:paramtypes", [
+      typeof EnvEvent === "undefined" ? Object : EnvEvent
+    ]),
+    __legacyMetadataTS("design:returntype", undefined)
+  ], StreamOutputService.prototype, "handleEvent", null);
+  __legacyDecorateClassTS([
+    TracedAs2("stream.handle-start", {
+      recordParams: true,
+      recordResult: false,
+      paramFilter: (args) => ({
+        model: args[0]?.metadata?.model ?? ""
+      })
+    }),
+    __legacyMetadataTS("design:type", Function),
+    __legacyMetadataTS("design:paramtypes", [
+      Object
+    ]),
+    __legacyMetadataTS("design:returntype", undefined)
+  ], StreamOutputService.prototype, "handleStart", null);
   __legacyDecorateClassTS([
     TracedAs2("stream.handle-text", {
       recordParams: true,
@@ -703,6 +905,102 @@ ${COLORS.system("[已中断]")}
     ]),
     __legacyMetadataTS("design:returntype", undefined)
   ], StreamOutputService.prototype, "handleText", null);
+  __legacyDecorateClassTS([
+    TracedAs2("stream.handle-reasoning", {
+      recordParams: true,
+      recordResult: false,
+      paramFilter: (args) => ({
+        "delta.length": args[0]?.delta?.length ?? 0,
+        "content.length": args[0]?.content?.length ?? 0,
+        phase: args[0]?.phase ?? ""
+      })
+    }),
+    __legacyMetadataTS("design:type", Function),
+    __legacyMetadataTS("design:paramtypes", [
+      Object
+    ]),
+    __legacyMetadataTS("design:returntype", undefined)
+  ], StreamOutputService.prototype, "handleReasoning", null);
+  __legacyDecorateClassTS([
+    TracedAs2("stream.handle-tool-call", {
+      recordParams: true,
+      recordResult: false,
+      log: true,
+      paramFilter: (args) => {
+        const p = args[0] ?? {};
+        return {
+          "tool.name": p.name ?? "unknown",
+          "tool.id": p.id ?? "",
+          "tool.args.keys": p.arguments ? Object.keys(p.arguments).join(",") : ""
+        };
+      }
+    }),
+    __legacyMetadataTS("design:type", Function),
+    __legacyMetadataTS("design:paramtypes", [
+      Object
+    ]),
+    __legacyMetadataTS("design:returntype", undefined)
+  ], StreamOutputService.prototype, "handleToolCall", null);
+  __legacyDecorateClassTS([
+    TracedAs2("stream.handle-tool-result", {
+      recordParams: true,
+      recordResult: false,
+      log: true,
+      paramFilter: (args) => {
+        const p = args[0] ?? {};
+        const result = p.result?.output ?? p.result?.error;
+        return {
+          "tool.name": p.name ?? "unknown",
+          "tool.result.kind": result !== undefined ? typeof result : "none",
+          "tool.result.preview": typeof result === "string" ? result.substring(0, 80) : typeof result === "object" && result !== null ? JSON.stringify(result).substring(0, 80) : ""
+        };
+      }
+    }),
+    __legacyMetadataTS("design:type", Function),
+    __legacyMetadataTS("design:paramtypes", [
+      Object
+    ]),
+    __legacyMetadataTS("design:returntype", undefined)
+  ], StreamOutputService.prototype, "handleToolResult", null);
+  __legacyDecorateClassTS([
+    TracedAs2("stream.handle-tool-error", {
+      recordParams: true,
+      recordResult: false,
+      log: true,
+      paramFilter: (args) => {
+        const p = args[0] ?? {};
+        return {
+          "tool.name": p.toolName ?? "unknown",
+          "tool.error.preview": typeof p.error === "string" ? p.error.substring(0, 120) : ""
+        };
+      }
+    }),
+    __legacyMetadataTS("design:type", Function),
+    __legacyMetadataTS("design:paramtypes", [
+      Object
+    ]),
+    __legacyMetadataTS("design:returntype", undefined)
+  ], StreamOutputService.prototype, "handleToolError", null);
+  __legacyDecorateClassTS([
+    TracedAs2("stream.handle-completed", {
+      recordParams: true,
+      recordResult: false,
+      paramFilter: (args) => {
+        const meta = args[0]?.metadata;
+        return {
+          model: meta?.model ?? "",
+          "usage.promptTokens": meta?.usage?.promptTokens ?? 0,
+          "usage.completionTokens": meta?.usage?.completionTokens ?? 0,
+          "usage.totalTokens": meta?.usage?.totalTokens ?? 0
+        };
+      }
+    }),
+    __legacyMetadataTS("design:type", Function),
+    __legacyMetadataTS("design:paramtypes", [
+      Object
+    ]),
+    __legacyMetadataTS("design:returntype", undefined)
+  ], StreamOutputService.prototype, "handleCompleted", null);
 });
 
 // src/commands/ui/mascot/glasses-girl.ts
@@ -1091,6 +1389,7 @@ var init_slash_command_popup = __esm(() => {
 // src/render/markdown.ts
 import { Marked } from "marked";
 import { highlight } from "cli-highlight";
+import { wrapFunction as wrapFunction2 } from "@ai-setting/roy-agent-core";
 function setMarkdownEnabled(enabled) {
   markdownEnabled = enabled;
 }
@@ -1333,7 +1632,50 @@ function wrapLine(line, width) {
   return out.join(`
 `);
 }
-function renderMarkdown(text, options = {}) {
+function cacheLookup(key) {
+  for (let i = 0;i < renderCache.length; i++) {
+    if (renderCache[i].key === key) {
+      const entry = renderCache[i];
+      if (i > 0) {
+        renderCache.splice(i, 1);
+        renderCache.unshift(entry);
+      }
+      return entry.value;
+    }
+  }
+  return;
+}
+function cacheInsert(key, value, text, width) {
+  if (renderCache.length >= MAX_CACHE_ENTRIES) {
+    renderCache.pop();
+  }
+  renderCache.unshift({ key, value, text, width });
+  renderCacheStats.size = renderCache.length;
+}
+function findPrefixCacheEntry(text, width) {
+  let best;
+  let bestLen = -1;
+  for (let i = 0;i < renderCache.length; i++) {
+    const e = renderCache[i];
+    if (e.width !== width)
+      continue;
+    if (e.text.length === 0)
+      continue;
+    if (text.startsWith(e.text) && e.text.length > bestLen) {
+      best = e;
+      bestLen = e.text.length;
+    }
+  }
+  return best;
+}
+function isSuffixSafeToLexIndependently(suffix) {
+  if (suffix.length === 0)
+    return true;
+  if (suffix.charCodeAt(0) !== 10)
+    return true;
+  return false;
+}
+function renderMarkdownImpl(text, options = {}) {
   const width = options.width ?? 80;
   if (!markdownEnabled) {
     return wrapLine(text, width);
@@ -1341,6 +1683,28 @@ function renderMarkdown(text, options = {}) {
   if (!text || text.trim() === "") {
     return "";
   }
+  const key = text + "\x00" + width;
+  const cached = cacheLookup(key);
+  if (cached !== undefined) {
+    renderCacheStats.hits++;
+    renderCacheStats.cachedHits++;
+    return cached;
+  }
+  const prefixEntry = findPrefixCacheEntry(text, width);
+  if (prefixEntry !== undefined) {
+    const suffix = text.slice(prefixEntry.text.length);
+    if (isSuffixSafeToLexIndependently(suffix)) {
+      const suffixRender = renderMarkdownImpl(suffix, { width });
+      const combined = prefixEntry.value + suffixRender;
+      cacheInsert(key, combined, text, width);
+      renderCacheStats.hits++;
+      renderCacheStats.prefixHits++;
+      renderCacheStats.partialParses++;
+      return combined;
+    }
+  }
+  renderCacheStats.misses++;
+  renderCacheStats.partialParses++;
   let tokens;
   try {
     tokens = marked.lexer(text);
@@ -1354,9 +1718,11 @@ function renderMarkdown(text, options = {}) {
       lines.push(block);
     }
   }
-  return lines.join(`
+  const result = lines.join(`
 
 `);
+  cacheInsert(key, result, text, width);
+  return result;
 }
 function truncateForTerminal(text, maxLines) {
   if (maxLines <= 0) {
@@ -1452,7 +1818,7 @@ function tailTruncateToRows(line, rows, width) {
   const tail = segments.join("");
   return tail + ANSI2.reset;
 }
-var ANSI2, DEFAULT_THEME, markdownEnabled = true, marked, ANSI_CSI_RE;
+var ANSI2, DEFAULT_THEME, markdownEnabled = true, marked, MAX_CACHE_ENTRIES = 32, renderCache, renderCacheStats, renderMarkdown, ANSI_CSI_RE;
 var init_markdown = __esm(() => {
   ANSI2 = {
     reset: "\x1B[0m",
@@ -1494,6 +1860,32 @@ var init_markdown = __esm(() => {
     breaks: false,
     pedantic: false
   });
+  renderCache = [];
+  renderCacheStats = {
+    hits: 0,
+    prefixHits: 0,
+    misses: 0,
+    partialParses: 0,
+    cachedHits: 0,
+    size: 0
+  };
+  renderMarkdown = wrapFunction2(renderMarkdownImpl, "markdown.render", {
+    recordParams: true,
+    recordResult: true,
+    paramFilter: (args) => ({
+      "input.length": typeof args[0] === "string" ? args[0].length : 0,
+      "options.width": typeof args[1]?.width === "number" ? args[1].width : 0
+    }),
+    resultFilter: (result) => ({
+      "output.length": typeof result === "string" ? result.length : 0,
+      "cache.hits": renderCacheStats.hits,
+      "cache.prefixHits": renderCacheStats.prefixHits,
+      "cache.misses": renderCacheStats.misses,
+      "cache.partialParses": renderCacheStats.partialParses,
+      "cache.size": renderCacheStats.size
+    }),
+    log: false
+  });
   ANSI_CSI_RE = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
 });
 
@@ -9461,7 +9853,7 @@ class CliQuietModeService {
 // package.json
 var package_default = {
   name: "@ai-setting/roy-agent-cli",
-  version: "1.7.19",
+  version: "1.7.21",
   type: "module",
   description: "CLI for roy-agent - Non-interactive command execution",
   main: "./dist/index.js",
@@ -10616,6 +11008,21 @@ function finalizeActStdout(args) {
   output.log(result);
 }
 
+// src/commands/shared/debug-trace.ts
+function printTraceIdAfterResponse(traceId, options) {
+  const enabled = typeof options === "boolean" ? options : options.enabled;
+  if (!enabled)
+    return;
+  const writer = typeof options === "object" && options.write ? options.write : (chunk) => process.stderr.write(chunk);
+  writer(`[Trace] ${traceId}
+`);
+  if (typeof options === "object" && typeof options.tuiSink === "function") {
+    try {
+      options.tuiSink(traceId);
+    } catch (_tuiErr) {}
+  }
+}
+
 // src/commands/act.ts
 function detectWorkspaceRoot(cwd = process.cwd(), runGit = execFileSync) {
   try {
@@ -10683,6 +11090,10 @@ function createActCommand(externalEnvService) {
       describe: "附加图片到消息（可多次传入；支持本地路径 / http(s) URL / data:base64）",
       type: "array",
       string: true
+    }).option("debug-on", {
+      describe: "调试模式：响应结束后输出 [Trace] <traceId>（stderr），便于追踪调用 trace",
+      type: "boolean",
+      default: false
     }),
     async handler(args) {
       const quiet = args.quiet ?? true;
@@ -10919,9 +11330,6 @@ function createActCommand(externalEnvService) {
           }
         });
         const traceId = rootSpan.spanContext.traceId;
-        if (!quiet) {
-          output.info(`[Trace] ${traceId}`);
-        }
         provider.setGlobalContext(rootSpan.spanContext);
         const contextHandler = new ContextHandlerService(env, sessionComponent, { maxRetries: 1, autoCompact: true });
         const context = {
@@ -10956,6 +11364,7 @@ function createActCommand(externalEnvService) {
           streamService,
           output
         });
+        printTraceIdAfterResponse(traceId, args.debugOn ?? false);
         if (!quiet) {
           if (isWorkflowPausedActResult(result)) {
             output.warn("工作流已暂停，等待用户输入（见上方 resume 提示）");
@@ -11274,6 +11683,35 @@ class QueryExecutor {
     }
   }
 }
+__legacyDecorateClassTS([
+  TracedAs4("cli.query-executor.setChunkCallback", {
+    recordParams: true,
+    recordResult: false,
+    log: true,
+    paramFilter: (args) => ({
+      "cb.isFunction": typeof args[0] === "function"
+    })
+  }),
+  __legacyMetadataTS("design:type", Function),
+  __legacyMetadataTS("design:paramtypes", [
+    typeof StreamChunkCallback === "undefined" ? Object : StreamChunkCallback
+  ]),
+  __legacyMetadataTS("design:returntype", undefined)
+], QueryExecutor.prototype, "setChunkCallback", null);
+__legacyDecorateClassTS([
+  TracedAs4("cli.query-executor.handleEvent", {
+    recordParams: true,
+    recordResult: false,
+    paramFilter: (args) => ({
+      "event.type": args[0]?.type ?? "unknown"
+    })
+  }),
+  __legacyMetadataTS("design:type", Function),
+  __legacyMetadataTS("design:paramtypes", [
+    Object
+  ]),
+  __legacyMetadataTS("design:returntype", undefined)
+], QueryExecutor.prototype, "handleEvent", null);
 __legacyDecorateClassTS([
   TracedAs4("cli.query-executor.execute", { recordParams: true, log: true }),
   __legacyMetadataTS("design:type", Function),
@@ -11700,6 +12138,16 @@ class EventHandler {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 }
+__legacyDecorateClassTS([
+  TracedAs5("cli.event-handler.start", {
+    recordParams: false,
+    recordResult: false,
+    log: true
+  }),
+  __legacyMetadataTS("design:type", Function),
+  __legacyMetadataTS("design:paramtypes", []),
+  __legacyMetadataTS("design:returntype", Function)
+], EventHandler.prototype, "start", null);
 __legacyDecorateClassTS([
   TracedAs5("cli.event-handler.handleEvent", { recordParams: true }),
   __legacyMetadataTS("design:type", Function),
@@ -11708,6 +12156,16 @@ __legacyDecorateClassTS([
   ]),
   __legacyMetadataTS("design:returntype", undefined)
 ], EventHandler.prototype, "handleEvent", null);
+__legacyDecorateClassTS([
+  TracedAs5("cli.event-handler.processQueue", {
+    recordParams: false,
+    recordResult: false,
+    log: true
+  }),
+  __legacyMetadataTS("design:type", Function),
+  __legacyMetadataTS("design:paramtypes", []),
+  __legacyMetadataTS("design:returntype", typeof Promise === "undefined" ? Object : Promise)
+], EventHandler.prototype, "processQueue", null);
 
 // src/commands/shared/esc-active-descendant.ts
 function hasActiveDescendants(env, parentSessionId) {
@@ -12654,8 +13112,23 @@ ${COLORS.system("[没有正在执行的请求]")}`);
         onSubmit: async (input) => {
           this.isExecuting = true;
           inkApiRef?.setMode("executing");
+          const inkTracerProvider = getTracerProvider3();
+          const inkTracer = inkTracerProvider.getTracer("roy-tracer");
+          const inkExistingContext = inkTracerProvider.getGlobalContext();
+          let inkRootSpan;
+          let inkTurnTraceId;
+          if (inkExistingContext) {
+            inkRootSpan = inkTracer.startSpan("interactive.execute", {
+              parent: inkExistingContext
+            });
+            inkTurnTraceId = inkExistingContext.traceId;
+          } else {
+            inkRootSpan = inkTracer.startSpan("interactive.execute");
+            inkTurnTraceId = inkRootSpan.spanContext.traceId;
+            inkTracerProvider.setGlobalContext(inkRootSpan.spanContext);
+          }
           try {
-            await this.options.onExecute(input);
+            await this.options.onExecute(input, inkTurnTraceId, undefined);
             inkApiRef?.setMode("ready");
             if (this.options.onAfterExecute) {
               try {
@@ -12670,6 +13143,26 @@ ${COLORS.system("[没有正在执行的请求]")}`);
             inkApiRef?.appendMessage({ role: "system", content: `[Error] ${msg}` });
             throw err;
           } finally {
+            try {
+              printTraceIdAfterResponse(inkTurnTraceId, {
+                enabled: this.options.debugOn ?? false,
+                tuiSink: (traceId) => {
+                  inkApiRef?.appendMessage({
+                    role: "system",
+                    content: `\uD83D\uDD0D [Trace] ${traceId}`
+                  });
+                }
+              });
+            } catch (traceErr) {
+              logger5.warn("printTraceIdAfterResponse failed (ink path)", {
+                error: String(traceErr)
+              });
+            }
+            try {
+              inkRootSpan.end();
+            } catch (spanErr) {
+              logger5.warn("inkRootSpan.end failed", { error: String(spanErr) });
+            }
             this.isExecuting = false;
           }
         },
@@ -12939,7 +13432,6 @@ ${COLORS.system("[通知2] ❯ " + message.replace(/\n/g, `
       traceId = rootSpan.spanContext.traceId;
       provider.setGlobalContext(rootSpan.spanContext);
     }
-    console.log(`${COLORS.system("[Trace] " + traceId)}`);
     console.log(`${COLORS.progress("[thinking...]")}`);
     try {
       await this.options.onExecute(message, traceId, agentContext);
@@ -12962,6 +13454,7 @@ ${COLORS.error("❌ 执行失败: " + error)}
       }
     } finally {
       rootSpan.end();
+      printTraceIdAfterResponse(traceId, this.options.debugOn ?? false);
       if (existingContext) {
         provider.setGlobalContext(existingContext);
       } else {
@@ -13302,6 +13795,10 @@ function createInteractiveCommand(externalEnvService) {
       describe: "Default agent 名字（默认 Roy，可被覆盖）",
       type: "string",
       default: "Roy"
+    }).option("debug-on", {
+      describe: "调试模式：每次 turn 结束后输出 [Trace] <traceId>（stderr），便于追踪调用 trace",
+      type: "boolean",
+      default: false
     }),
     async handler(args) {
       CliQuietModeService.getInstance().setQuiet(true);
@@ -13468,6 +13965,7 @@ function createInteractiveCommand(externalEnvService) {
           model: args.model,
           version: getPackageVersion(),
           useInk,
+          debugOn: args.debugOn ?? false,
           onExecute: async (message, traceId, agentContext) => {
             resetStreamAbort();
             const preloadedPrompts = eventSourceSystemPrompts;
@@ -13642,15 +14140,16 @@ function createInteractiveCommand(externalEnvService) {
 var InteractiveCommand = createInteractiveCommand();
 
 // src/commands/run.ts
-import React6 from "react";
+import React8 from "react";
 import { render } from "ink";
 
 // src/RunTui.tsx
-import { useState as useState6, useCallback as useCallback4, useRef as useRef2, useEffect as useEffect5 } from "react";
-import { Box as Box6, Text as Text8, useApp as useApp2 } from "ink";
+import { useState as useState6, useCallback as useCallback4, useRef as useRef5, useEffect as useEffect7, useMemo as useMemo3 } from "react";
+import { Box as Box7, Text as Text9, useApp as useApp2 } from "ink";
 
 // src/tui/App.tsx
 init_Markdown();
+import React4, { useEffect as useEffect4, useRef as useRef2 } from "react";
 import { Box as Box4, Static as Static2, Text as Text6 } from "ink";
 
 // src/tui/Spinner.tsx
@@ -13689,12 +14188,45 @@ var Spinner = ({
 // src/tui/App.tsx
 init_StatusBar();
 init_theme();
+import { wrapFunction as wrapFunction3 } from "@ai-setting/roy-agent-core";
 import { jsxDEV as jsxDEV6 } from "react/jsx-dev-runtime";
 var ROLE_PREFIX = {
   user: "\uD83D\uDC64 You",
   assistant: "\uD83E\uDD16 Agent",
   tool: "\uD83D\uDD27 Tool"
 };
+var emitAppRenderSpanImpl = (snapshot) => {};
+var emitAppRenderSpan = wrapFunction3(emitAppRenderSpanImpl, "tui.app.render", {
+  recordParams: true,
+  recordResult: false,
+  log: true,
+  paramFilter: (args) => {
+    const s = args[0] ?? {};
+    return {
+      renderCount: s.renderCount ?? 0,
+      historyLength: s.historyLength ?? 0,
+      status: s.status ?? "unknown"
+    };
+  }
+});
+var emitRenderScheduledSpanImpl = (parentRenderCount) => {};
+var emitRenderScheduledSpan = wrapFunction3(emitRenderScheduledSpanImpl, "tui.app.render-scheduled", {
+  recordParams: true,
+  recordResult: false,
+  log: false,
+  paramFilter: (args) => ({
+    parentRenderCount: args[0] ?? 0
+  })
+});
+var emitRenderThrottledSpanImpl = (parentRenderCount) => {};
+var emitRenderThrottledSpan = wrapFunction3(emitRenderThrottledSpanImpl, "tui.app.render-throttled", {
+  recordParams: true,
+  recordResult: false,
+  log: false,
+  paramFilter: (args) => ({
+    parentRenderCount: args[0] ?? 0
+  })
+});
 var RoleLabel = ({ role }) => {
   const theme = getTheme();
   const roleColor = role === "user" ? theme.user : role === "assistant" ? theme.assistant : theme.tool;
@@ -13762,10 +14294,18 @@ var App = ({
   status,
   model,
   workdir,
-  streamingText,
   tokenCount
 }) => {
   const theme = getTheme();
+  const renderCountRef = useRef2(0);
+  renderCountRef.current += 1;
+  useEffect4(() => {
+    emitAppRenderSpan({
+      renderCount: renderCountRef.current,
+      historyLength: history.length,
+      status
+    });
+  });
   return /* @__PURE__ */ jsxDEV6(Box4, {
     flexDirection: "column",
     minHeight: 20,
@@ -13799,21 +14339,7 @@ var App = ({
           label: "Agent is thinking..."
         }, undefined, false, undefined, this)
       }, undefined, false, undefined, this) : null,
-      status === "streaming" && streamingText ? /* @__PURE__ */ jsxDEV6(Box4, {
-        flexDirection: "column",
-        marginBottom: 1,
-        children: [
-          /* @__PURE__ */ jsxDEV6(RoleLabel, {
-            role: "assistant"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsxDEV6(Box4, {
-            marginLeft: 2,
-            children: /* @__PURE__ */ jsxDEV6(Markdown, {
-              text: streamingText
-            }, undefined, false, undefined, this)
-          }, undefined, false, undefined, this)
-        ]
-      }, undefined, true, undefined, this) : status === "streaming" ? /* @__PURE__ */ jsxDEV6(Box4, {
+      status === "streaming" ? /* @__PURE__ */ jsxDEV6(Box4, {
         marginBottom: 1,
         children: /* @__PURE__ */ jsxDEV6(Spinner, {
           label: "Generating response..."
@@ -13830,15 +14356,144 @@ var App = ({
     ]
   }, undefined, true, undefined, this);
 };
+function areAppPropsEqual(prev, next) {
+  if (prev.status !== next.status)
+    return false;
+  if (prev.model !== next.model)
+    return false;
+  if (prev.workdir !== next.workdir)
+    return false;
+  if (prev.tokenCount !== next.tokenCount)
+    return false;
+  if (prev.history !== next.history)
+    return false;
+  return true;
+}
+var parentRenderCountRef = { current: 0 };
+var AppThrottledImpl = (props) => {
+  parentRenderCountRef.current += 1;
+  emitRenderScheduledSpan(parentRenderCountRef.current);
+  return /* @__PURE__ */ jsxDEV6(App, {
+    ...props
+  }, undefined, false, undefined, this);
+};
+var AppThrottled = React4.memo(AppThrottledImpl, areAppPropsEqual);
+AppThrottled.displayName = "App(throttled)";
+var lastMemoResult = null;
+var instrumentedAreEqual = (prev, next) => {
+  const equal = areAppPropsEqual(prev, next);
+  if (equal && lastMemoResult !== true) {
+    emitRenderThrottledSpan(parentRenderCountRef.current);
+  }
+  lastMemoResult = equal;
+  return equal;
+};
+var AppMemo = React4.memo(AppThrottledImpl, instrumentedAreEqual);
+AppMemo.displayName = "App(memo-throttled)";
+// src/tui/StreamingOverlay.tsx
+init_Markdown();
+import { useEffect as useEffect5, useRef as useRef3 } from "react";
+import { Box as Box5, Text as Text7 } from "ink";
+import { wrapFunction as wrapFunction4 } from "@ai-setting/roy-agent-core";
+import { jsxDEV as jsxDEV7 } from "react/jsx-dev-runtime";
+var emitOverlayRenderSpanImpl = (snapshot) => {};
+var emitOverlayRenderSpan = wrapFunction4(emitOverlayRenderSpanImpl, "streaming-overlay.render", {
+  recordParams: true,
+  recordResult: false,
+  log: false,
+  paramFilter: (args) => {
+    const s = args[0] ?? {};
+    return {
+      renderCount: s.renderCount ?? 0,
+      streamingTextLength: s.streamingTextLength ?? 0,
+      status: s.status ?? "unknown"
+    };
+  }
+});
+var emitOverlayMarkdownSpanImpl = (snapshot) => {};
+var emitOverlayMarkdownSpan = wrapFunction4(emitOverlayMarkdownSpanImpl, "streaming-overlay.markdown-render", {
+  recordParams: true,
+  recordResult: false,
+  log: false,
+  paramFilter: (args) => {
+    const s = args[0] ?? {};
+    return {
+      inputLength: s.inputLength ?? 0,
+      renderCount: s.renderCount ?? 0
+    };
+  }
+});
+var StreamingOverlay = ({
+  streamingText,
+  status,
+  markdownEnabled: markdownEnabled2,
+  width
+}) => {
+  const renderCountRef = useRef3(0);
+  renderCountRef.current += 1;
+  useEffect5(() => {
+    emitOverlayRenderSpan({
+      renderCount: renderCountRef.current,
+      streamingTextLength: streamingText.length,
+      status
+    });
+  });
+  if (status === "thinking") {
+    return /* @__PURE__ */ jsxDEV7(Box5, {
+      marginBottom: 1,
+      children: /* @__PURE__ */ jsxDEV7(Text7, {
+        dimColor: true,
+        children: "\uD83E\uDD14 thinking..."
+      }, undefined, false, undefined, this)
+    }, undefined, false, undefined, this);
+  }
+  if (status === "idle") {
+    return null;
+  }
+  if (!streamingText) {
+    return /* @__PURE__ */ jsxDEV7(Box5, {
+      marginBottom: 1,
+      children: /* @__PURE__ */ jsxDEV7(Text7, {
+        dimColor: true,
+        children: "⏳ generating response..."
+      }, undefined, false, undefined, this)
+    }, undefined, false, undefined, this);
+  }
+  const effectiveWidth = width ?? process.stdout.columns ?? 80;
+  emitOverlayMarkdownSpan({
+    inputLength: streamingText.length,
+    renderCount: renderCountRef.current
+  });
+  return /* @__PURE__ */ jsxDEV7(Box5, {
+    flexDirection: "column",
+    marginBottom: 1,
+    children: [
+      /* @__PURE__ */ jsxDEV7(Text7, {
+        bold: true,
+        color: "cyan",
+        children: "\uD83E\uDD16 Agent"
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV7(Box5, {
+        marginLeft: 2,
+        children: markdownEnabled2 ? /* @__PURE__ */ jsxDEV7(Markdown, {
+          text: streamingText,
+          width: effectiveWidth
+        }, undefined, false, undefined, this) : /* @__PURE__ */ jsxDEV7(Text7, {
+          children: streamingText
+        }, undefined, false, undefined, this)
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+};
 
 // src/tui/index.ts
 init_Markdown();
 init_StatusBar();
 
 // src/tui/TextInput.tsx
-import { useEffect as useEffect4, useState as useState4 } from "react";
-import { Box as Box5, Text as Text7, useInput as useInput3 } from "ink";
-import { jsxDEV as jsxDEV7 } from "react/jsx-dev-runtime";
+import { useEffect as useEffect6, useState as useState4 } from "react";
+import { Box as Box6, Text as Text8, useInput as useInput3 } from "ink";
+import { jsxDEV as jsxDEV8 } from "react/jsx-dev-runtime";
 var TextInput = ({
   label,
   prefix,
@@ -13850,7 +14505,7 @@ var TextInput = ({
   const [value, setValue] = useState4("");
   const [historyIndex, setHistoryIndex] = useState4(-1);
   const [draft, setDraft] = useState4("");
-  useEffect4(() => {
+  useEffect6(() => {
     setHistoryIndex(-1);
   }, [history.length]);
   useInput3((input, key) => {
@@ -13904,9 +14559,9 @@ var TextInput = ({
       setValue((v) => v + input);
     }
   });
-  return /* @__PURE__ */ jsxDEV7(Box5, {
+  return /* @__PURE__ */ jsxDEV8(Box6, {
     children: [
-      /* @__PURE__ */ jsxDEV7(Text7, {
+      /* @__PURE__ */ jsxDEV8(Text8, {
         bold: true,
         color: "green",
         children: [
@@ -13914,21 +14569,21 @@ var TextInput = ({
           " "
         ]
       }, undefined, true, undefined, this),
-      /* @__PURE__ */ jsxDEV7(Text7, {
+      /* @__PURE__ */ jsxDEV8(Text8, {
         bold: true,
         children: [
           label,
           ": "
         ]
       }, undefined, true, undefined, this),
-      /* @__PURE__ */ jsxDEV7(Text7, {
+      /* @__PURE__ */ jsxDEV8(Text8, {
         children: value
       }, undefined, false, undefined, this),
-      !value && placeholder ? /* @__PURE__ */ jsxDEV7(Text7, {
+      !value && placeholder ? /* @__PURE__ */ jsxDEV8(Text8, {
         dimColor: true,
         children: placeholder
       }, undefined, false, undefined, this) : null,
-      historyIndex !== -1 ? /* @__PURE__ */ jsxDEV7(Text7, {
+      historyIndex !== -1 ? /* @__PURE__ */ jsxDEV8(Text8, {
         dimColor: true,
         children: "  (history)"
       }, undefined, false, undefined, this) : null
@@ -13941,36 +14596,98 @@ init_theme();
 init_welcome_card2();
 
 // src/tui/use-streaming-accumulator.ts
-import { useCallback as useCallback3, useState as useState5 } from "react";
+import { useCallback as useCallback3, useRef as useRef4, useState as useState5 } from "react";
+import { wrapFunction as wrapFunction5 } from "@ai-setting/roy-agent-core";
 function useStreamingAccumulator() {
   const [status, setStatus] = useState5("idle");
   const [streamingText, setStreamingText] = useState5("");
-  const start = useCallback3(() => {
+  const appendCountRef = useRef4(0);
+  const pendingBufferRef = useRef4("");
+  const flushScheduledRef = useRef4(false);
+  const flushBuffer = useCallback3(() => {
+    flushScheduledRef.current = false;
+    const buf = pendingBufferRef.current;
+    if (buf.length === 0)
+      return;
+    pendingBufferRef.current = "";
+    setStreamingText((prev) => prev + buf);
+  }, []);
+  const lastStatusRef = useRef4("idle");
+  const startImpl = useCallback3(() => {
     setStreamingText("");
     setStatus("thinking");
+    lastStatusRef.current = "thinking";
+    appendCountRef.current = 0;
   }, []);
-  const append = useCallback3((chunk) => {
-    setStatus("streaming");
-    setStreamingText((prev) => prev + chunk);
-  }, []);
-  const finish = useCallback3(() => {
-    setStatus("idle");
+  const appendImpl = useCallback3((chunk) => {
+    pendingBufferRef.current += chunk;
+    if (!flushScheduledRef.current) {
+      flushScheduledRef.current = true;
+      queueMicrotask(flushBuffer);
+    }
+    if (lastStatusRef.current !== "streaming") {
+      setStatus("streaming");
+      lastStatusRef.current = "streaming";
+    }
+    appendCountRef.current += 1;
+  }, [flushBuffer]);
+  const finishImpl = useCallback3(() => {
+    if (pendingBufferRef.current.length > 0) {
+      flushBuffer();
+    }
     let snapshot = "";
     setStreamingText((prev) => {
       snapshot = prev;
       return "";
     });
-    return snapshot;
-  }, []);
-  const fail = useCallback3((_err) => {
     setStatus("idle");
+    lastStatusRef.current = "idle";
+    return snapshot;
+  }, [flushBuffer]);
+  const failImpl = useCallback3((_err) => {
+    if (pendingBufferRef.current.length > 0) {
+      flushBuffer();
+    }
     let snapshot = "";
     setStreamingText((prev) => {
       snapshot = prev;
       return "";
     });
+    setStatus("idle");
+    lastStatusRef.current = "idle";
     return snapshot;
-  }, []);
+  }, [flushBuffer]);
+  const start = wrapFunction5(startImpl, "streaming.start", {
+    recordParams: false,
+    recordResult: false,
+    log: true
+  });
+  const append = wrapFunction5(appendImpl, "streaming.append", {
+    recordParams: true,
+    recordResult: false,
+    log: true,
+    paramFilter: (args) => ({
+      "chunk.length": typeof args[0] === "string" ? args[0].length : 0,
+      "chunk.head": typeof args[0] === "string" ? args[0].slice(0, 32) : "",
+      "chunk.tail": typeof args[0] === "string" ? args[0].slice(-32) : ""
+    })
+  });
+  const finish = wrapFunction5(finishImpl, "streaming.finish", {
+    recordParams: false,
+    recordResult: true,
+    log: true,
+    resultFilter: (result) => ({
+      "snapshot.length": typeof result === "string" ? result.length : 0
+    })
+  });
+  const fail = wrapFunction5(failImpl, "streaming.fail", {
+    recordParams: true,
+    recordResult: false,
+    log: true,
+    paramFilter: (args) => ({
+      "err.message": args[0] instanceof Error ? args[0].message : String(args[0])
+    })
+  });
   return { status, streamingText, start, append, finish, fail };
 }
 
@@ -14050,7 +14767,8 @@ function dispatchSlashCommand(raw, ctx) {
 }
 
 // src/RunTui.tsx
-import { jsxDEV as jsxDEV8 } from "react/jsx-dev-runtime";
+import { wrapFunction as wrapFunction6 } from "@ai-setting/roy-agent-core";
+import { jsxDEV as jsxDEV9 } from "react/jsx-dev-runtime";
 var RunScreen = ({
   handleQuery,
   streamHandleQuery,
@@ -14068,17 +14786,17 @@ var RunScreen = ({
   const stream = useStreamingAccumulator();
   const status = stream.status;
   const { exit } = useApp2();
-  const userTurnCountRef = useRef2(0);
-  const assistantTurnCountRef = useRef2(0);
-  const isProcessingRef = useRef2(0);
-  const executeQueryRef = useRef2(null);
-  const historyIdRef = useRef2(0);
+  const userTurnCountRef = useRef5(0);
+  const assistantTurnCountRef = useRef5(0);
+  const isProcessingRef = useRef5(0);
+  const executeQueryRef = useRef5(null);
+  const historyIdRef = useRef5(0);
   const width = process.stdout.columns ?? 80;
   const doExit = useCallback4(() => {
     onExit?.();
     exit();
   }, [onExit, exit]);
-  const executeQuery = useCallback4(async (message) => {
+  const executeQueryImpl = useCallback4(async (message) => {
     isProcessingRef.current += 1;
     stream.start();
     try {
@@ -14110,13 +14828,24 @@ var RunScreen = ({
       isProcessingRef.current -= 1;
     }
   }, [handleQuery, markdownEnabled2, maxLines, stream, streamHandleQuery, width]);
-  useEffect5(() => {
+  const executeQuery = useMemo3(() => wrapFunction6(executeQueryImpl, "tui.run-tui.executeQuery", {
+    recordParams: true,
+    recordResult: false,
+    log: true,
+    paramFilter: (args) => ({
+      "message.length": typeof args[0] === "string" ? args[0].length : 0,
+      "message.head": typeof args[0] === "string" ? args[0].slice(0, 60) : "",
+      "isProcessingRef.before": (isProcessingRef.current ?? 0) + 1,
+      streaming: !!streamHandleQuery
+    })
+  }), [executeQueryImpl, streamHandleQuery]);
+  useEffect7(() => {
     executeQueryRef.current = executeQuery;
   }, [executeQuery]);
-  useEffect5(() => {
+  useEffect7(() => {
     if (!onRegisterHandlers)
       return;
-    const handleNotification = async (message, _envEvent) => {
+    const handleNotificationImpl = async (message, _envEvent) => {
       const notifId = `h${++historyIdRef.current}`;
       setHistory((h) => [
         ...h,
@@ -14126,10 +14855,31 @@ var RunScreen = ({
         await executeQueryRef.current(message);
       }
     };
+    const handleNotification = wrapFunction6(handleNotificationImpl, "tui.run-tui.handleNotification", {
+      recordParams: true,
+      recordResult: false,
+      log: true,
+      paramFilter: (args) => ({
+        "message.length": typeof args[0] === "string" ? args[0].length : 0,
+        "message.head": typeof args[0] === "string" ? args[0].slice(0, 60) : "",
+        isProcessingRef: isProcessingRef.current ?? 0
+      })
+    });
     const isIdle = () => {
       return isProcessingRef.current === 0;
     };
-    onRegisterHandlers({ onNotification: handleNotification, isIdle });
+    const appendTraceId = (traceId) => {
+      const traceIdItemId = `h${++historyIdRef.current}`;
+      setHistory((h) => [
+        ...h,
+        { role: "tool", content: `\uD83D\uDD0D [Trace] ${traceId}`, id: traceIdItemId }
+      ]);
+    };
+    onRegisterHandlers({
+      onNotification: handleNotification,
+      isIdle,
+      appendTraceId
+    });
   }, [onRegisterHandlers]);
   const handleSubmit = useCallback4(async (raw) => {
     const trimmed = raw.trim();
@@ -14217,19 +14967,24 @@ var RunScreen = ({
   const handleCancel = useCallback4(() => {
     doExit();
   }, [doExit]);
-  return /* @__PURE__ */ jsxDEV8(Box6, {
+  return /* @__PURE__ */ jsxDEV9(Box7, {
     flexDirection: "column",
     children: [
-      /* @__PURE__ */ jsxDEV8(App, {
+      /* @__PURE__ */ jsxDEV9(AppMemo, {
         history,
         status,
         model,
-        workdir,
-        streamingText: stream.streamingText
+        workdir
       }, undefined, false, undefined, this),
-      status === "idle" ? /* @__PURE__ */ jsxDEV8(Box6, {
+      status !== "idle" ? /* @__PURE__ */ jsxDEV9(StreamingOverlay, {
+        streamingText: stream.streamingText,
+        status,
+        markdownEnabled: markdownEnabled2,
+        width
+      }, undefined, false, undefined, this) : null,
+      status === "idle" ? /* @__PURE__ */ jsxDEV9(Box7, {
         marginTop: 1,
-        children: /* @__PURE__ */ jsxDEV8(TextInput, {
+        children: /* @__PURE__ */ jsxDEV9(TextInput, {
           label: "You",
           prefix: "\uD83D\uDC64",
           placeholder: 'Type a message, "/help", or "exit"',
@@ -14238,9 +14993,9 @@ var RunScreen = ({
           history: userHistory
         }, undefined, false, undefined, this)
       }, undefined, false, undefined, this) : null,
-      errorMessage ? /* @__PURE__ */ jsxDEV8(Box6, {
+      errorMessage ? /* @__PURE__ */ jsxDEV9(Box7, {
         marginTop: 1,
-        children: /* @__PURE__ */ jsxDEV8(Text8, {
+        children: /* @__PURE__ */ jsxDEV9(Text9, {
           color: "red",
           children: [
             "⚠ ",
@@ -14338,7 +15093,11 @@ async function shutdownRunSteps(deps) {
 }
 
 // src/commands/run.ts
-async function loadHandleQuery(options, hooks) {
+import {
+  wrapFunction as wrapFunction7,
+  getTracerProvider as getTracerProvider4
+} from "@ai-setting/roy-agent-core";
+async function loadHandleQueryImpl(options, hooks) {
   const quiet = CliQuietModeService.getInstance().isQuiet();
   const output = new OutputService2;
   output.configure({ quiet });
@@ -14403,7 +15162,7 @@ async function loadHandleQuery(options, hooks) {
   }
   const llmComponent = envService.getLLM();
   queryExecutor.initStreamOutput(llmComponent ?? null);
-  const handleQuery = async (message) => {
+  const handleQueryImpl = async (message) => {
     const mergedContext = {
       ...agentContext,
       model: options.model,
@@ -14420,6 +15179,14 @@ async function loadHandleQuery(options, hooks) {
     }, undefined, mergedContext);
     return String(result ?? "");
   };
+  const handleQuery = wrapFunction7(handleQueryImpl, "cli.run.handleQuery", {
+    recordParams: true,
+    recordResult: false,
+    log: true,
+    paramFilter: (args) => ({
+      "message.length": typeof args[0] === "string" ? args[0].length : 0
+    })
+  });
   const taskEventHandler = new TaskEventHandler({
     env,
     enabled: true
@@ -14451,17 +15218,80 @@ async function loadHandleQuery(options, hooks) {
     sessionManager
   };
 }
-function createStreamHandleQuery(queryExecutor, sessionId, options, agentContext, eventSourceSystemPrompt) {
-  return async (message, onChunk) => {
-    queryExecutor.setChunkCallback((event) => {
+var loadHandleQuery = wrapFunction7(loadHandleQueryImpl, "cli.run.loadHandleQuery", {
+  recordParams: true,
+  recordResult: false,
+  log: true,
+  paramFilter: (args) => {
+    const opts = args[0] ?? {};
+    return {
+      "options.model": opts.model ?? "",
+      "options.workdir": opts.workdir ?? "",
+      "options.session": opts.session ?? "",
+      "options.eventSource": Array.isArray(opts.eventSource) ? opts.eventSource.join(",") : opts.eventSource ?? "",
+      "has.onNotification": !!args[1]?.onNotification
+    };
+  }
+});
+function createStreamHandleQuery(queryExecutor, sessionId, options, agentContext, eventSourceSystemPrompt, onTraceId) {
+  const innerStreamHandler = async (message, onChunk) => {
+    const onChunkInstrumented = wrapFunction7((chunk) => {
+      onChunk(chunk);
+    }, "cli.run.chunkCallbackImpl.onChunk-called", {
+      recordParams: true,
+      recordResult: false,
+      log: false,
+      paramFilter: (args) => ({
+        "chunk.length": typeof args[0] === "string" ? args[0].length : 0,
+        "chunk.head": typeof args[0] === "string" ? args[0].slice(0, 32) : ""
+      })
+    });
+    const chunkCallbackImpl = (event) => {
       if (event.type === "llm.text") {
         if (event.delta) {
-          onChunk(event.delta);
+          onChunkInstrumented(event.delta);
         } else if (event.content) {
-          onChunk(event.content);
+          onChunkInstrumented(event.content);
         }
+        return;
       }
-    });
+      if (event.type === "tool.call") {
+        const toolName = event.toolName || "unknown";
+        const toolId = event.toolId || "";
+        onChunkInstrumented(`
+\uD83D\uDD27 tool: ${toolName} (${toolId})
+`);
+        return;
+      }
+      if (event.type === "tool.result") {
+        onChunkInstrumented(`
+✓ done
+`);
+        return;
+      }
+      if (event.type === "tool.error") {
+        const msg = event.toolError || "error";
+        onChunkInstrumented(`
+✗ ${msg}
+`);
+        return;
+      }
+    };
+    queryExecutor.setChunkCallback(wrapFunction7(chunkCallbackImpl, "cli.run.chunkCallback", {
+      recordParams: true,
+      recordResult: false,
+      log: true,
+      paramFilter: (args) => {
+        const e = args[0] ?? {};
+        return {
+          "event.type": e.type ?? "unknown",
+          "event.delta.length": typeof e.delta === "string" ? e.delta.length : 0,
+          "event.content.length": typeof e.content === "string" ? e.content.length : 0,
+          "event.toolName": e.toolName ?? "",
+          "event.toolId": e.toolId ?? ""
+        };
+      }
+    }));
     const mergedContext = {
       ...agentContext,
       model: options.model,
@@ -14471,13 +15301,37 @@ function createStreamHandleQuery(queryExecutor, sessionId, options, agentContext
         defaultAgentName: options.defaultAgentName
       }
     };
-    const result = await queryExecutor.execute(message, sessionId, {
-      showReasoning: options.reasoning ?? true,
-      showToolCalls: options.toolCalls ?? true,
-      showToolResults: options.toolResults ?? false
-    }, undefined, mergedContext);
+    const turnSpan = getTracerProvider4().getTracer("roy-tracer").startSpan("cli.run.turn");
+    const turnTraceId = turnSpan.spanContext.traceId;
+    let result;
+    try {
+      result = await queryExecutor.execute(message, sessionId, {
+        showReasoning: options.reasoning ?? true,
+        showToolCalls: options.toolCalls ?? true,
+        showToolResults: options.toolResults ?? false
+      }, undefined, mergedContext);
+      turnSpan.end(result);
+    } catch (error) {
+      turnSpan.setAttribute("error", String(error));
+      turnSpan.end(undefined, error instanceof Error ? error : new Error(String(error)));
+      throw error;
+    } finally {
+      try {
+        onTraceId?.(turnTraceId);
+      } catch (cbErr) {
+        console.warn(`[Trace] sink failed: ${cbErr instanceof Error ? cbErr.message : String(cbErr)}`);
+      }
+    }
     return String(result ?? "");
   };
+  return wrapFunction7(innerStreamHandler, "cli.run.createStreamHandleQuery", {
+    recordParams: true,
+    recordResult: false,
+    log: true,
+    paramFilter: (args) => ({
+      "message.length": typeof args[0] === "string" ? args[0].length : 0
+    })
+  });
 }
 function createRunCommand() {
   return {
@@ -14550,6 +15404,10 @@ function createRunCommand() {
       type: "string",
       describe: "Default agent 名字（默认 Roy，可被覆盖）",
       default: "Roy"
+    }).option("debug-on", {
+      type: "boolean",
+      describe: "调试模式：每次 turn 结束后输出 [Trace] <traceId>（stderr），便于追踪调用 trace",
+      default: false
     }),
     handler: async (argv) => {
       if (argv.markdown === false) {
@@ -14591,10 +15449,17 @@ function createRunCommand() {
           logger: undefined
         });
       });
-      const streamHandleQuery = createStreamHandleQuery(queryExecutor, sessionId, argv, agentContext, eventSourceSystemPrompt);
+      const debugOn = argv.debugOn ?? false;
+      let appendTraceIdTui;
+      const streamHandleQuery = createStreamHandleQuery(queryExecutor, sessionId, argv, agentContext, eventSourceSystemPrompt, (traceId) => {
+        printTraceIdAfterResponse(traceId, {
+          enabled: debugOn,
+          tuiSink: appendTraceIdTui
+        });
+      });
       const stopEventHandler = eventHandler.start();
       const stopTaskEventHandler = taskEventHandler.start();
-      const { waitUntilExit } = render(React6.createElement(RunTui_default, {
+      const { waitUntilExit } = render(React8.createElement(RunTui_default, {
         handleQuery,
         streamHandleQuery,
         model: argv.model,
@@ -14604,6 +15469,7 @@ function createRunCommand() {
         onRegisterHandlers: (handlers) => {
           runState.onNotification = handlers.onNotification;
           runState.isIdle = handlers.isIdle;
+          appendTraceIdTui = handlers.appendTraceId;
         },
         onExit: () => {}
       }), { exitOnCtrlC: true });
@@ -14631,14 +15497,14 @@ function createRunCommand() {
 var RunCommand = createRunCommand();
 
 // src/commands/chat.ts
-import React8 from "react";
+import React10 from "react";
 import { render as render2 } from "ink";
 
 // src/ChatTui.tsx
-import { useEffect as useEffect6, useRef as useRef3, useState as useState7 } from "react";
-import { Box as Box7, useApp as useApp3 } from "ink";
+import { useEffect as useEffect8, useRef as useRef6, useState as useState7 } from "react";
+import { Box as Box8, useApp as useApp3 } from "ink";
 init_markdown();
-import { jsxDEV as jsxDEV9 } from "react/jsx-dev-runtime";
+import { jsxDEV as jsxDEV10 } from "react/jsx-dev-runtime";
 var ChatScreen = ({
   handleQuery,
   streamHandleQuery,
@@ -14651,11 +15517,11 @@ var ChatScreen = ({
   const [history, setHistory] = useState7([
     { role: "user", content: message, id: "h-init-1" }
   ]);
-  const historyIdRef = useRef3(1);
+  const historyIdRef = useRef6(1);
   const stream = useStreamingAccumulator();
   const { exit } = useApp3();
   const width = process.stdout.columns ?? 80;
-  useEffect6(() => {
+  useEffect8(() => {
     let cancelled = false;
     stream.start();
     (async () => {
@@ -14694,16 +15560,23 @@ var ChatScreen = ({
       cancelled = true;
     };
   }, [handleQuery, streamHandleQuery, message, maxLines, markdownEnabled2, exit, width, stream]);
-  return /* @__PURE__ */ jsxDEV9(Box7, {
+  return /* @__PURE__ */ jsxDEV10(Box8, {
     flexDirection: "column",
-    children: /* @__PURE__ */ jsxDEV9(App, {
-      history,
-      status: stream.status,
-      model,
-      workdir,
-      streamingText: stream.streamingText
-    }, undefined, false, undefined, this)
-  }, undefined, false, undefined, this);
+    children: [
+      /* @__PURE__ */ jsxDEV10(AppMemo, {
+        history,
+        status: stream.status,
+        model,
+        workdir
+      }, undefined, false, undefined, this),
+      stream.status !== "idle" ? /* @__PURE__ */ jsxDEV10(StreamingOverlay, {
+        streamingText: stream.streamingText,
+        status: stream.status,
+        markdownEnabled: markdownEnabled2,
+        width
+      }, undefined, false, undefined, this) : null
+    ]
+  }, undefined, true, undefined, this);
 };
 var ChatTui_default = ChatScreen;
 
@@ -14782,7 +15655,7 @@ function createChatCommand() {
       }
       const maxLines = Number.parseInt(argv.maxLines ?? "500", 10);
       const handleQuery = await loadHandleQuery2(argv);
-      const { waitUntilExit } = render2(React8.createElement(ChatTui_default, {
+      const { waitUntilExit } = render2(React10.createElement(ChatTui_default, {
         handleQuery,
         message: argv.message,
         model: argv.model,
@@ -23739,7 +24612,7 @@ var WorkflowAddCommand = {
           process.exit(1);
         }
         if (!agentComponent.getAgent("workflow-extract")) {
-          output.error("Built-in 'workflow-extract' agent is not available. ");
+          output.error("Built-in 'workflow-extract' agent is not available. This usually means the environment was not fully initialized.");
           process.exit(1);
         }
         const prompt = `## 任务
@@ -24153,9 +25026,9 @@ import chalk73 from "chalk";
 import fs5 from "fs";
 import path8 from "path";
 import { createRunWorkflowTool } from "@ai-setting/roy-agent-core/env/workflow/tools";
-import { getTracerProvider as getTracerProvider4, propagation, wrapFunction } from "@ai-setting/roy-agent-core";
+import { getTracerProvider as getTracerProvider5, propagation, wrapFunction as wrapFunction8 } from "@ai-setting/roy-agent-core";
 import { isValidSessionId } from "@ai-setting/roy-agent-core/env/session";
-var runWorkflow = wrapFunction(async function runWorkflowImpl(args) {
+var runWorkflow = wrapFunction8(async function runWorkflowImpl(args) {
   const output = new OutputService2;
   const envService = new EnvironmentService(output);
   const traceparent = process.env.TRACEPARENT;
@@ -24175,7 +25048,7 @@ var runWorkflow = wrapFunction(async function runWorkflowImpl(args) {
   output.info(`[OTel Trace] TRACEPARENT=${traceparent || "none"}, traceId=${traceId}, parentSpanId=${parentSpanId}`);
   let workflowSpan = undefined;
   try {
-    const provider = getTracerProvider4();
+    const provider = getTracerProvider5();
     await provider.initialize();
     const tracer = provider.getTracer("roy-tracer");
     const restoredContext = tracer.getCurrentContext();
@@ -24432,8 +25305,8 @@ var WorkflowRunCommand = {
 // src/commands/workflow/commands/stop.ts
 import chalk74 from "chalk";
 import { createWorkflowRunStopTool } from "@ai-setting/roy-agent-core/env/workflow/tools";
-import { wrapFunction as wrapFunction2 } from "@ai-setting/roy-agent-core";
-var stopWorkflow = wrapFunction2(async function stopWorkflowImpl(args) {
+import { wrapFunction as wrapFunction9 } from "@ai-setting/roy-agent-core";
+var stopWorkflow = wrapFunction9(async function stopWorkflowImpl(args) {
   const output = new OutputService2;
   const envService = new EnvironmentService(output);
   try {
@@ -25088,7 +25961,7 @@ Error: ${error.message}`));
 
 // src/commands/workflow/commands/search.ts
 import chalk78 from "chalk";
-import { wrapFunction as wrapFunction3 } from "@ai-setting/roy-agent-core";
+import { wrapFunction as wrapFunction10 } from "@ai-setting/roy-agent-core";
 var WorkflowSearchCommand = {
   command: "search",
   describe: "Search workflows by keyword and/or tags (multiple tags use AND filter). v2: returns available_tags.",
@@ -25263,14 +26136,14 @@ var _runWorkflowSearchImpl = async function(opts) {
     }
   }
 };
-var runWorkflowSearch = wrapFunction3(_runWorkflowSearchImpl, "workflow.cli.search", {
+var runWorkflowSearch = wrapFunction10(_runWorkflowSearchImpl, "workflow.cli.search", {
   recordParams: true,
   recordResult: false,
   log: false
 });
 
 // src/commands/workflow/commands/tag.ts
-import { wrapFunction as wrapFunction4 } from "@ai-setting/roy-agent-core";
+import { wrapFunction as wrapFunction11 } from "@ai-setting/roy-agent-core";
 import chalk79 from "chalk";
 var WorkflowTagListCommand = {
   command: "list",
@@ -25470,12 +26343,12 @@ function formatDate2(iso) {
     return iso;
   }
 }
-var runWorkflowTagList = wrapFunction4(_runWorkflowTagListImpl, "workflow.cli.tag.list", {
+var runWorkflowTagList = wrapFunction11(_runWorkflowTagListImpl, "workflow.cli.tag.list", {
   recordParams: true,
   recordResult: false,
   log: false
 });
-var runWorkflowTagGet = wrapFunction4(_runWorkflowTagGetImpl, "workflow.cli.tag.get", {
+var runWorkflowTagGet = wrapFunction11(_runWorkflowTagGetImpl, "workflow.cli.tag.get", {
   recordParams: true,
   recordResult: false,
   log: false