@yeaft/webchat-agent 1.0.49 → 1.0.51

package/history.js

@@ -2,6 +2,7 @@ import { homedir } from 'os';
 import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync, fstatSync } from 'fs';
 import { join } from 'path';
 import ctx from './context.js';
+import { normalizeClaudeMessage } from './sdk/message-normalize.js';
 import { getProvider, DEFAULT_PROVIDER } from './providers/index.js';
 
 // Claude 项目目录
@@ -227,7 +228,7 @@ function readTailMessages(filePath, limit) {
         const line = lines[i];
         if (!line || !line.trim()) continue;
         try {
-          const data = JSON.parse(line);
+          const data = normalizeClaudeMessage(JSON.parse(line));
           if (data.type === 'user' || data.type === 'assistant') {
             collected.push(data);
             if (collected.length >= limit) break;
@@ -241,7 +242,7 @@ function readTailMessages(filePath, limit) {
       const headLine = carry.toString('utf-8').trim();
       if (headLine) {
         try {
-          const data = JSON.parse(headLine);
+          const data = normalizeClaudeMessage(JSON.parse(headLine));
           if (data.type === 'user' || data.type === 'assistant') {
             collected.push(data);
           }
@@ -287,7 +288,7 @@ export function loadSessionHistory(workDir, claudeSessionId, limit = 500) {
 
     for (const line of lines) {
       try {
-        const data = JSON.parse(line);
+        const data = normalizeClaudeMessage(JSON.parse(line));
         if (data.type === 'user' || data.type === 'assistant') {
           messages.push(data);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.49",
+  "version": "1.0.51",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/sdk/message-normalize.js

@@ -0,0 +1,129 @@
+const TOOL_LIKE_BLOCK_TYPES = new Set([
+  'tool_use',
+  'tool_call',
+  'function_call',
+  'server_tool_use',
+  'call',
+]);
+
+/**
+ * Claude Code stream-json has changed its tool-call block spelling more than
+ * once. Normalize every known tool-like assistant content block to the
+ * Anthropic-compatible `tool_use` shape used by the rest of the app.
+ *
+ * @param {unknown} block
+ * @returns {unknown}
+ */
+export function normalizeAssistantContentBlock(block) {
+  if (!block || typeof block !== 'object') return block;
+  if (block.type === 'tool_use') return block;
+  if (!TOOL_LIKE_BLOCK_TYPES.has(block.type)) return block;
+
+  const input = normalizeToolInput(block);
+  const name = block.name
+    || block.tool_name
+    || block.toolName
+    || block.function?.name
+    || block.action?.name
+    || input?.name
+    || 'tool';
+  const id = block.id
+    || block.tool_use_id
+    || block.toolUseId
+    || block.tool_call_id
+    || block.toolCallId
+    || block.call_id
+    || block.callId
+    || stableFallbackToolId(name, block);
+
+  return {
+    type: 'tool_use',
+    id,
+    name,
+    input,
+  };
+}
+
+/**
+ * @param {unknown} content
+ * @returns {unknown}
+ */
+export function normalizeAssistantContent(content) {
+  if (!Array.isArray(content)) return content;
+  return content.map(normalizeAssistantContentBlock);
+}
+
+/**
+ * @param {unknown} message
+ * @returns {unknown}
+ */
+export function normalizeClaudeMessage(message) {
+  if (!message || typeof message !== 'object') return message;
+  if (message.type !== 'assistant' || !message.message) return message;
+  const content = message.message.content;
+  const normalized = normalizeAssistantContent(content);
+  if (normalized === content) return message;
+  return {
+    ...message,
+    message: {
+      ...message.message,
+      content: normalized,
+    },
+  };
+}
+
+/**
+ * Stream events should only emit text deltas from actual text blocks. Newer
+ * Claude Code builds may emit text-looking deltas while a tool-call block is
+ * being assembled (`call`, transient id, JSON argument text). Those bytes are
+ * transport detail, not assistant prose; the final complete assistant message
+ * carries the real tool_use block.
+ *
+ * @param {string|undefined|null} blockType
+ * @returns {boolean}
+ */
+export function shouldForwardTextDeltaForBlockType(blockType) {
+  if (!blockType) return true; // Back-compat for older CLIs without start events.
+  return blockType === 'text';
+}
+
+function stableFallbackToolId(name, block) {
+  const raw = stableStringify(block);
+  let hash = 2166136261;
+  for (let i = 0; i < raw.length; i++) {
+    hash ^= raw.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return `${name}-${hash.toString(36)}`;
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function normalizeToolInput(block) {
+  const raw = block.input
+    ?? block.arguments
+    ?? block.args
+    ?? block.parameters
+    ?? block.function?.arguments
+    ?? block.action?.arguments
+    ?? {};
+
+  if (typeof raw === 'string') {
+    const trimmed = raw.trim();
+    if (!trimmed) return {};
+    try {
+      const parsed = JSON.parse(trimmed);
+      return parsed && typeof parsed === 'object' ? parsed : { value: parsed };
+    } catch {
+      return { arguments: raw };
+    }
+  }
+  if (raw && typeof raw === 'object') return raw;
+  return {};
+}

package/sdk/query.js

@@ -7,6 +7,7 @@ import { spawn } from 'child_process';
 import { createInterface } from 'readline';
 import { Stream } from './stream.js';
 import { AbortError } from './types.js';
+import { normalizeClaudeMessage, shouldForwardTextDeltaForBlockType } from './message-normalize.js';
 import { getCleanEnv, logDebug, streamToStdin, resolveClaudeCommand } from './utils.js';
 
 
@@ -82,6 +83,7 @@ export class Query {
     // Track whether we've forwarded text deltas for the current assistant turn.
     // When true, the next complete `assistant` message's text blocks are redundant.
     let hasStreamedTextDeltas = false;
+    const streamBlockTypes = new Map();
 
     try {
       for await (const line of rl) {
@@ -114,36 +116,52 @@ export class Query {
               const event = message.event;
               if (!event) continue;
 
-              // content_block_delta with text_delta → convert to assistant message for streaming
+              if (event.type === 'content_block_start') {
+                streamBlockTypes.set(event.index, event.content_block?.type || null);
+                continue;
+              }
+              if (event.type === 'content_block_stop') {
+                streamBlockTypes.delete(event.index);
+                continue;
+              }
+              // content_block_delta with text_delta → convert to assistant message for streaming,
+              // but only while the active block is actually text. Some Claude Code builds
+              // expose tool-call assembly as text-looking deltas; forwarding those leaks
+              // raw `call`, transient ids, and JSON arguments into the chat transcript.
               if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta' && event.delta.text) {
-                hasStreamedTextDeltas = true;
-                this.inputStream.enqueue({
-                  type: 'assistant',
-                  message: {
-                    role: 'assistant',
-                    content: [{ type: 'text', text: event.delta.text }]
-                  }
-                });
+                const blockType = streamBlockTypes.get(event.index);
+                if (shouldForwardTextDeltaForBlockType(blockType)) {
+                  hasStreamedTextDeltas = true;
+                  this.inputStream.enqueue({
+                    type: 'assistant',
+                    message: {
+                      role: 'assistant',
+                      content: [{ type: 'text', text: event.delta.text }]
+                    }
+                  });
+                }
               }
-              // All other stream events (message_start, content_block_start,
-              // input_json_delta, content_block_stop, message_stop) are ignored.
-              // tool_use is handled via the complete assistant message.
+              // All other stream events (message_start, input_json_delta,
+              // message_stop) are ignored. Tool use is handled via the complete
+              // assistant message after block normalization below.
               continue;
             }
 
+            const normalizedMessage = normalizeClaudeMessage(message);
+
             // Deduplicate: when a complete assistant message arrives after we've
             // already streamed text deltas, strip the text blocks (already sent).
             // Keep tool_use blocks which are NOT sent incrementally.
-            if (message.type === 'assistant' && hasStreamedTextDeltas) {
+            if (normalizedMessage.type === 'assistant' && hasStreamedTextDeltas) {
               hasStreamedTextDeltas = false; // Reset for next assistant turn
 
-              const content = message.message?.content;
+              const content = normalizedMessage.message?.content;
               if (Array.isArray(content)) {
                 const nonTextBlocks = content.filter(b => b.type !== 'text');
                 if (nonTextBlocks.length > 0) {
                   // Forward only tool_use blocks (text already sent via deltas)
-                  message.message.content = nonTextBlocks;
-                  this.inputStream.enqueue(message);
+                  normalizedMessage.message.content = nonTextBlocks;
+                  this.inputStream.enqueue(normalizedMessage);
                 } else {
                   // Pure text message fully streamed — send finish-streaming signal
                   // so frontend clears isStreaming and typing dots can reappear
@@ -165,11 +183,12 @@ export class Query {
 
             // Reset delta tracking on non-assistant messages
             // (e.g., user, result, system — a new turn boundary)
-            if (message.type !== 'assistant') {
+            if (normalizedMessage.type !== 'assistant') {
               hasStreamedTextDeltas = false;
+              streamBlockTypes.clear();
             }
 
-            this.inputStream.enqueue(message);
+            this.inputStream.enqueue(normalizedMessage);
           } catch (e) {
             logDebug(`Non-JSON line: ${line.substring(0, 100)}`);
           }

package/yeaft/perf-trace.js

@@ -0,0 +1,74 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+const MAX_DETAIL_STRING = 512;
+
+function sanitizeString(value, max = MAX_DETAIL_STRING) {
+  if (typeof value !== 'string') return value;
+  return value.length > max ? `${value.slice(0, max)}...[truncated]` : value;
+}
+
+function sanitizeValue(value, depth = 0) {
+  if (value == null) return value;
+  if (typeof value === 'string') return sanitizeString(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) {
+    if (depth >= 4) return `[array:${value.length}]`;
+    return value.slice(0, 50).map(v => sanitizeValue(v, depth + 1));
+  }
+  if (typeof value === 'object') {
+    if (depth >= 4) return '[object]';
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (key === 'text' || key === 'prompt' || key === 'content' || key === 'data' || key === 'apiKey' || key === 'token') continue;
+      out[key] = sanitizeValue(item, depth + 1);
+    }
+    return out;
+  }
+  return String(value);
+}
+
+export function perfNowMs() {
+  return Number(process.hrtime.bigint()) / 1e6;
+}
+
+export function recordAgentPerfTrace(config, event = {}) {
+  const traceId = typeof event.traceId === 'string' && event.traceId.trim()
+    ? event.traceId.trim()
+    : (typeof event.perfTraceId === 'string' && event.perfTraceId.trim() ? event.perfTraceId.trim() : null);
+  if (!traceId) return false;
+  const yeaftDir = config?.yeaftDir;
+  if (typeof yeaftDir !== 'string' || !yeaftDir.trim()) return false;
+  const root = join(yeaftDir.trim(), 'perf-traces');
+  const day = new Date().toISOString().slice(0, 10);
+  const row = {
+    traceId,
+    source: 'agent',
+    phase: event.phase || 'unknown',
+    at: Date.now(),
+    monotonicMs: Number.isFinite(event.monotonicMs) ? event.monotonicMs : perfNowMs(),
+    durationMs: Number.isFinite(event.durationMs) ? event.durationMs : null,
+    sessionId: event.sessionId || null,
+    vpId: event.vpId || null,
+    turnId: event.turnId || null,
+    threadId: event.threadId || null,
+    messageType: event.messageType || null,
+    bytes: Number.isFinite(event.bytes) ? event.bytes : null,
+    ok: typeof event.ok === 'boolean' ? event.ok : null,
+    detail: sanitizeValue(event.detail || null),
+  };
+  try {
+    mkdirSync(root, { recursive: true });
+    appendFileSync(join(root, `${day}.jsonl`), `${JSON.stringify(row)}\n`);
+    return true;
+  } catch (err) {
+    if (process.env.YEAFT_PERF_TRACE_DEBUG === '1') {
+      console.warn('[Yeaft] perf trace write failed:', err?.message || err);
+    }
+    return false;
+  }
+}
+
+export const __perfTraceForTest = {
+  sanitizeValue,
+};

package/yeaft/web-bridge.js

@@ -72,6 +72,7 @@ import { listMcpServers, upsertMcpServer, removeMcpServer } from './config-api.j
 import { buildMcpFlattenedTools } from './tools/mcp-tools.js';
 import { getAgentRegistry, agentBelongsToScope } from './tools/agent.js';
 import { isPromptableAgentStatus } from './sub-agent/status.js';
+import { perfNowMs, recordAgentPerfTrace } from './perf-trace.js';
 
 const SKILL_COMMAND_PREFIX = 'skill:';
 
@@ -1271,6 +1272,17 @@ function getOrCreateSessionContext(sessionId, sessionHandle) {
  * @param {object} envelope — coordinator envelope `{sessionId, taskId, msg, trigger}`
  */
 function enqueueForVp(sessionId, vpId, envelope) {
+  const perfTraceId = envelope?._perfTraceId || envelope?.perfTraceId || null;
+  if (perfTraceId) {
+    recordAgentPerfTrace(ctx.CONFIG, {
+      traceId: perfTraceId,
+      phase: 'vp.enqueue',
+      sessionId,
+      vpId,
+      turnId: envelope?.msg?.id || null,
+      messageType: envelope?.trigger || 'user',
+    });
+  }
   const routePromise = routeEnvelopeToVpThread(sessionId, vpId, envelope);
   registerRoutePromise(envelope?.msg?.id, routePromise);
 }
@@ -1360,6 +1372,7 @@ function scheduleTaskResultReentry(event) {
 }
 
 async function routeEnvelopeToVpThread(sessionId, vpId, envelope) {
+  const routeStart = perfNowMs();
   const { text, prompt, promptParts } = buildVpPromptPayload(vpId, envelope);
   const runningThreads = getRunningThreads(sessionId, vpId);
   let thread = null;
@@ -1404,6 +1417,19 @@ async function routeEnvelopeToVpThread(sessionId, vpId, envelope) {
   if (!thread) return null;
   rememberThreadMessage(thread, envelope?.msg);
   const turnId = `${randomUUID().slice(0, 8)}:${vpId}`;
+  const perfTraceId = envelope?._perfTraceId || envelope?.perfTraceId || null;
+  if (perfTraceId) {
+    recordAgentPerfTrace(ctx.CONFIG, {
+      traceId: perfTraceId,
+      phase: 'vp.route_thread',
+      durationMs: perfNowMs() - routeStart,
+      sessionId,
+      vpId,
+      turnId,
+      threadId: thread.threadId,
+      detail: { related, runningThreadCount: runningThreads.length },
+    });
+  }
 
   if (related) {
     const content = promptParts || prompt;
@@ -1717,11 +1743,12 @@ function resolveGroupDefaultVpId(sessionId) {
   }
 }
 
-function sendSessionOutputFrame(data, { sessionId, chatId, vpId, turnId, threadId } = {}) {
+function sendSessionOutputFrame(data, { sessionId, chatId, vpId, turnId, threadId, perfTraceId } = {}) {
   const resolvedVpId = vpId || (sessionId ? resolveGroupDefaultVpId(sessionId) : null);
   sendToServer({
     type: 'yeaft_output',
     conversationId: yeaftConversationId,
+    ...(perfTraceId ? { perfTraceId } : {}),
     ...(sessionId ? { sessionId } : {}),
     ...(chatId ? { chatId } : {}),
     ...(resolvedVpId ? { vpId: resolvedVpId } : {}),
@@ -1763,10 +1790,11 @@ function broadcastSkillSlashCommands(sessionLike) {
 }
 
 /** Send a Yeaft Session metadata event over the legacy-compatible envelope. */
-function sendSessionEvent(event, { sessionId, chatId, vpId, turnId, threadId } = {}) {
+function sendSessionEvent(event, { sessionId, chatId, vpId, turnId, threadId, perfTraceId } = {}) {
   sendToServer({
     type: 'yeaft_output',
     conversationId: yeaftConversationId,
+    ...(perfTraceId ? { perfTraceId } : {}),
     ...(sessionId ? { sessionId } : {}),
     ...(chatId ? { chatId } : {}),
     ...(vpId ? { vpId } : {}),
@@ -3033,6 +3061,33 @@ export async function handleYeaftSessionSend(msg) {
   const sessionId = (typeof msg.sessionId === 'string' && msg.sessionId.trim())
     ? msg.sessionId.trim()
     : 'grp_default';
+  const perfTraceId = typeof msg.perfTraceId === 'string' && msg.perfTraceId.trim()
+    ? msg.perfTraceId.trim()
+    : null;
+  const perfStart = perfNowMs();
+  const tracePerf = (phase, extra = {}) => {
+    if (!perfTraceId) return;
+    recordAgentPerfTrace(ctx.CONFIG, {
+      traceId: perfTraceId,
+      phase,
+      sessionId,
+      messageType: msg.type,
+      ...extra,
+    });
+  };
+  const traceDuration = (phase, start, extra = {}) => {
+    tracePerf(phase, {
+      durationMs: perfNowMs() - start,
+      ...extra,
+    });
+  };
+  tracePerf('session_send.received', {
+    turnId: typeof msg.id === 'string' ? msg.id : null,
+    detail: {
+      mentionCount: mentions.length,
+      attachmentCount: Array.isArray(msg.files) ? msg.files.length : 0,
+    },
+  });
 
   // Entry gate: if a compact is in flight from the previous turn IN
   // THIS GROUP, wait for it to finish before reading the group's
@@ -3043,7 +3098,9 @@ export async function handleYeaftSessionSend(msg) {
   // a session has loaded (or in test paths that never call
   // `ensureSessionLoaded`) it may be unavailable; skip gracefully.
   if (session?.compactor) {
+    const compactWaitStart = perfNowMs();
     await session.compactor.awaitInFlight(sessionId);
+    traceDuration('session_send.await_compactor', compactWaitStart);
   }
 
   // yeaftDir is a hard prerequisite for both session boot and group seeding;
@@ -3059,13 +3116,16 @@ export async function handleYeaftSessionSend(msg) {
     return;
   }
 
+  const ensureSessionStart = perfNowMs();
   await ensureSessionLoaded();
+  traceDuration('session_send.ensure_session_loaded', ensureSessionStart);
 
   // Open the session. The default `grp_default` no longer self-seeds
   // here — session creation happens up-front via `handleYeaftCreateSession`,
   // so a missing dir surfaces a clear error rather than masking it.
   let sessionHandle = null;
   let sessionRoot = null;
+  const openSessionStart = perfNowMs();
   try {
     const groupYeaftDir = resolveSessionYeaftDir(yeaftDir, sessionId);
     sessionRoot = sessionsRoot(groupYeaftDir);
@@ -3085,6 +3145,8 @@ export async function handleYeaftSessionSend(msg) {
     console.warn('[Yeaft] yeaft_session_chat: session open failed', err?.message || err);
   }
 
+  traceDuration('session_send.open_session', openSessionStart, { ok: !!sessionHandle });
+
   if (!sessionHandle) {
     sendSessionOutputFrame({
       type: 'assistant',
@@ -3156,6 +3218,7 @@ export async function handleYeaftSessionSend(msg) {
   // driver receives.
   const inboundFiles = Array.isArray(msg.files) ? msg.files : [];
   let attachmentBundle = { promptAttachments: [], promptSuffix: '', promptParts: [], failed: [] };
+  const attachmentsStart = perfNowMs();
   if (inboundFiles.length > 0) {
     try {
       attachmentBundle = persistYeaftAttachments(inboundFiles, { subdir: sessionId });
@@ -3176,11 +3239,19 @@ export async function handleYeaftSessionSend(msg) {
     }, { sessionId });
   }
   const persistedAttachments = attachmentsForPersistence(attachmentBundle.promptAttachments);
+  traceDuration('session_send.attachments', attachmentsStart, {
+    detail: {
+      inputFileCount: inboundFiles.length,
+      persistedFileCount: persistedAttachments.length,
+      failedFileCount: Array.isArray(attachmentBundle.failed) ? attachmentBundle.failed.length : 0,
+    },
+  });
 
   // Ingest user text. The coordinator persists, applies mention/fanout
   // rules, and calls deliver() (== enqueueForVp) for each chosen VP —
   // which both (a) emits vp_typing_start and (b) ensures a driver runs.
   let report;
+  const ingestStart = perfNowMs();
   try {
     report = coord.ingest({
       id: typeof msg.id === 'string' && msg.id ? msg.id : undefined,
@@ -3198,6 +3269,7 @@ export async function handleYeaftSessionSend(msg) {
       // back to disk on every fan-out target. NOT persisted.
       _promptParts: attachmentBundle.promptParts,
       _promptSuffix: attachmentBundle.promptSuffix,
+      _perfTraceId: perfTraceId,
     });
   } catch (err) {
     console.warn('[Yeaft] yeaft_session_chat: coord.ingest failed', err?.message || err);
@@ -3209,6 +3281,14 @@ export async function handleYeaftSessionSend(msg) {
     return;
   }
 
+  traceDuration('session_send.coordinator_ingest', ingestStart, {
+    turnId: report?.message?.id || null,
+    detail: {
+      dispatchedCount: Array.isArray(report?.dispatched) ? report.dispatched.length : 0,
+      fallback: typeof report?.fallback === 'string' ? report.fallback : null,
+    },
+  });
+
   // Thread ownership is resolved inside enqueueForVp()/routeEnvelopeToVpThread
   // before persistence. Do not write a canonical 'main' user row here: a
   // route to an active VP may append to an existing thread, while an
@@ -3233,7 +3313,15 @@ export async function handleYeaftSessionSend(msg) {
   // Wait only for routing/classification promises spawned by this message.
   // Do not wait for every driver in the group: unrelated older threads may keep
   // running for minutes and must not hold this request lifecycle hostage.
+  const routeWaitStart = perfNowMs();
   await waitForRoutePromises(report?.message?.id);
+  traceDuration('session_send.wait_route_promises', routeWaitStart, {
+    turnId: report?.message?.id || null,
+  });
+  traceDuration('session_send.handler_total', perfStart, {
+    turnId: report?.message?.id || null,
+    ok: true,
+  });
 
   // Post-turn compaction. Fire-and-forget — does NOT block the response
   // path. The Compactor's own precheck (`shouldCompactHistory`) decides
@@ -3602,7 +3690,24 @@ async function raceWithEscalation(inner, { deadlineMs, onEscalate }) {
 async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId = 'main', thread = null, turnId, envelope: inboundEnvelope, vpAbort, baseSnapshot }) {
   if (!prompt?.trim()) return;
 
-  const envelope = { sessionId, vpId, threadId, turnId };
+  const perfTraceId = typeof inboundEnvelope?._perfTraceId === 'string' && inboundEnvelope._perfTraceId.trim()
+    ? inboundEnvelope._perfTraceId.trim()
+    : (typeof inboundEnvelope?.perfTraceId === 'string' && inboundEnvelope.perfTraceId.trim()
+      ? inboundEnvelope.perfTraceId.trim()
+      : null);
+  const envelope = { sessionId, vpId, threadId, turnId, ...(perfTraceId ? { perfTraceId } : {}) };
+  const vpTurnPerfStart = perfNowMs();
+  if (perfTraceId) {
+    recordAgentPerfTrace(ctx.CONFIG, {
+      traceId: perfTraceId,
+      phase: 'vp.turn_start',
+      sessionId,
+      vpId,
+      turnId,
+      threadId,
+      detail: { promptBytes: Buffer.byteLength(prompt || '') },
+    });
+  }
 
   // Per-message turn lifecycle: track start ts + which terminal reason
   // we'll emit. `emitVpTurnEnd` is idempotent (route_forward emits inside
@@ -3713,10 +3818,25 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
       // the second-line defense (history-compact only fires above 30K
       // tokens — small chats with many turns still bloat the messages
       // array). See `trimSnapshotForBudget` doc-block for policy.
+      const trimStart = perfNowMs();
       const trimmedMessages = trimSnapshotForBudget(baseSnapshot, {
         messageTokenBudget: session?.config?.messageTokenBudget,
         language: session?.config?.language,
       });
+      if (perfTraceId) {
+        recordAgentPerfTrace(ctx.CONFIG, {
+          traceId: perfTraceId,
+          phase: 'vp.trim_snapshot',
+          durationMs: perfNowMs() - trimStart,
+          sessionId,
+          vpId,
+          turnId,
+          threadId,
+          detail: { beforeMessages: baseSnapshot.length, afterMessages: trimmedMessages.length },
+        });
+      }
+      const engineStart = perfNowMs();
+      let firstEngineEvent = false;
       for await (const event of vpEngine.query({
         prompt,
         promptParts,
@@ -3738,9 +3858,33 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
         },
         ...queryOpts,
       })) {
+        if (perfTraceId && !firstEngineEvent) {
+          firstEngineEvent = true;
+          recordAgentPerfTrace(ctx.CONFIG, {
+            traceId: perfTraceId,
+            phase: 'vp.engine_first_event',
+            durationMs: perfNowMs() - engineStart,
+            sessionId,
+            vpId,
+            turnId,
+            threadId,
+            messageType: event?.type || null,
+          });
+        }
         resetQueryTimer();
         handleEngineEvent(event, handlerCtx);
       }
+      if (perfTraceId) {
+        recordAgentPerfTrace(ctx.CONFIG, {
+          traceId: perfTraceId,
+          phase: 'vp.engine_complete',
+          durationMs: perfNowMs() - engineStart,
+          sessionId,
+          vpId,
+          turnId,
+          threadId,
+        });
+      }
 
       flushStreamTextBatch(handlerCtx, envelope, { resetImmediate: true });
 
@@ -3750,7 +3894,24 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
       // the target VP turn; otherwise UI replay can show a trailing handoff
       // block after the target response.
       const visiblePrompts = inboundIsInternal ? appendedUserPrompts : [prompt, ...appendedUserPrompts];
+      const appendHistoryStart = perfNowMs();
       appendTurnToSessionHistory(sessionId, threadId, vpId, visiblePrompts, assistantTextParts, toolCallsAccum, toolResultsAccum, thinkingBlocksAccum, { turnId });
+      if (perfTraceId) {
+        recordAgentPerfTrace(ctx.CONFIG, {
+          traceId: perfTraceId,
+          phase: 'vp.append_history',
+          durationMs: perfNowMs() - appendHistoryStart,
+          sessionId,
+          vpId,
+          turnId,
+          threadId,
+          detail: {
+            assistantBytes: Buffer.byteLength(assistantTextParts.join('')),
+            toolCallCount: toolCallsAccum.length,
+            toolResultCount: toolResultsAccum.length,
+          },
+        });
+      }
 
       sendSessionOutputFrame({
         type: 'assistant',
@@ -3780,6 +3941,19 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
       return;
     }
 
+    if (perfTraceId) {
+      recordAgentPerfTrace(ctx.CONFIG, {
+        traceId: perfTraceId,
+        phase: 'vp.turn_error',
+        durationMs: perfNowMs() - vpTurnPerfStart,
+        sessionId,
+        vpId,
+        turnId,
+        threadId,
+        ok: false,
+        detail: { message: err?.message || String(err) },
+      });
+    }
     console.error('[Yeaft] query error:', err);
     turnEndReason = 'errored';
     turnEndDetail = { message: err?.message || String(err) };
@@ -3858,6 +4032,19 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
       thread.status = 'idle';
       thread.updatedAt = Date.now();
     }
+    if (perfTraceId) {
+      recordAgentPerfTrace(ctx.CONFIG, {
+        traceId: perfTraceId,
+        phase: 'vp.turn_total',
+        durationMs: perfNowMs() - vpTurnPerfStart,
+        sessionId,
+        vpId,
+        turnId,
+        threadId,
+        ok: turnEndReason !== 'errored',
+        detail: { reason: turnEndReason },
+      });
+    }
   }
 }