@yeaft/webchat-agent 1.0.48 → 1.0.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.48",
+  "version": "1.0.50",
   "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/yeaft/llm/adapter.js

@@ -117,6 +117,117 @@ export class LLMAbortError extends Error {
   }
 }
 
+/**
+ * Default cap on a single un-terminated SSE line. A well-formed SSE stream
+ * terminates every `data:` line with `\n`, so the live buffer never exceeds
+ * one event. A malfunctioning gateway can instead emit a multi-megabyte run
+ * with no newline; without a cap, the buffer grows unbounded and (before the
+ * incremental scan below) the parse went quadratic, freezing the event loop
+ * long enough to starve the WS heartbeat and drop the agent offline. 64 MiB
+ * is far above any legitimate single SSE event yet bounds the damage.
+ */
+export const DEFAULT_SSE_MAX_LINE_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Incremental, O(n) line splitter for SSE byte streams.
+ *
+ * The previous per-adapter pattern was `buffer += chunk; lines =
+ * buffer.split('\n'); buffer = lines.pop()`. When a single line spans many
+ * chunks (no `\n` yet), each chunk re-scanned and re-split the entire growing
+ * buffer — O(n²) total, which on a multi-MiB un-terminated line blocks the
+ * main thread for tens of seconds to minutes (measured: ~35 s at 40 MiB),
+ * freezing every event-loop task including the heartbeat `setInterval` and the
+ * `ws.on('pong')` handler. The agent then sees "No pong" and terminates its
+ * own healthy connection.
+ *
+ * This buffer scans only each newly-arrived chunk for `\n` and holds the
+ * still-incomplete trailing line as an array of fragments (joined only when a
+ * newline finally completes it), so total work is linear in bytes received
+ * regardless of how a line is chunked. It also enforces `maxLineBytes`: a
+ * single line that exceeds the cap with no terminator is treated as a
+ * malformed stream — `push()` throws a retryable LLMServerError (which the
+ * adapter's stream loop propagates through classifyFetchError) rather than
+ * accumulating without bound.
+ *
+ * Note: the cap is measured in JS string `.length` (UTF-16 code units), not
+ * exact UTF-8 bytes. It is a coarse upper-bound guard against unbounded
+ * growth, not a precise byte accountant.
+ */
+export class SseLineBuffer {
+  /** @param {{ maxLineBytes?: number }} [opts] */
+  constructor({ maxLineBytes = DEFAULT_SSE_MAX_LINE_BYTES } = {}) {
+    this.maxLineBytes = Number.isFinite(maxLineBytes) && maxLineBytes > 0
+      ? Math.floor(maxLineBytes)
+      : DEFAULT_SSE_MAX_LINE_BYTES;
+    /**
+     * Fragments of the current (incomplete) line, in arrival order. Kept as an
+     * array — NOT a concatenated string — because `string += chunk` reallocates
+     * and copies the whole growing tail every call, which is itself O(n²) on a
+     * long un-terminated line even with an incremental newline scan. Pushing a
+     * fragment is O(1); we only `join` when a newline actually completes a line.
+     * @type {string[]}
+     */
+    this._frags = [];
+    /** Running byte length of `_frags` — avoids re-summing to enforce the cap. */
+    this._pendingLen = 0;
+  }
+
+  /**
+   * Append a chunk and return every newly-completed line (newline stripped),
+   * in order. The trailing incomplete line stays buffered for the next call.
+   * Lines may be empty strings (SSE uses blank lines as event separators);
+   * callers filter as needed.
+   *
+   * @param {string} chunk
+   * @returns {string[]}
+   * @throws {LLMServerError} when an un-terminated line exceeds `maxLineBytes`
+   */
+  push(chunk) {
+    if (!chunk) return [];
+    const lines = [];
+    let start = 0;
+    // Scan only THIS chunk for newlines. Bytes before the first newline finish
+    // the buffered partial line; bytes between newlines are whole lines; bytes
+    // after the last newline become the new partial. Work is linear in chunk
+    // length, and the buffered tail is never concatenated until a newline lands.
+    let nl;
+    while ((nl = chunk.indexOf('\n', start)) !== -1) {
+      const segment = chunk.slice(start, nl);
+      if (this._frags.length > 0) {
+        this._frags.push(segment);
+        lines.push(this._frags.join(''));
+        this._frags = [];
+        this._pendingLen = 0;
+      } else {
+        lines.push(segment);
+      }
+      start = nl + 1;
+    }
+    // Trailing fragment after the last newline (or the whole chunk if none):
+    // buffer it as an O(1) push rather than a string concat.
+    if (start < chunk.length) {
+      const tail = start === 0 ? chunk : chunk.slice(start);
+      this._frags.push(tail);
+      this._pendingLen += tail.length;
+      if (this._pendingLen > this.maxLineBytes) {
+        // LLMServerError is retryable by class (engine.js retries on
+        // `instanceof LLMServerError`), matching the sibling throws in the
+        // adapters — no `.retryable` flag needed on the throw path.
+        throw new LLMServerError(
+          `SSE line exceeded ${this.maxLineBytes} bytes without a newline — treating as malformed stream`,
+          0,
+        );
+      }
+    }
+    return lines;
+  }
+
+  /** The unconsumed trailing partial line (no newline yet). */
+  get pending() {
+    return this._frags.length === 1 ? this._frags[0] : this._frags.join('');
+  }
+}
+
 /**
  * Read one chunk from a Fetch stream with a silence timeout. This is not a
  * total request deadline: every received chunk gets a fresh budget. A caller

package/yeaft/llm/anthropic.js

@@ -18,6 +18,7 @@ import {
   readStreamChunkWithIdleTimeout,
   redactRawRequest,
   safeHeaders,
+  SseLineBuffer,
 } from './adapter.js';
 import {
   normalizeEffort,
@@ -302,7 +303,12 @@ export class AnthropicAdapter extends LLMAdapter {
     // Parse SSE stream
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
-    let buffer = '';
+    // Incremental O(n) line splitter (see SseLineBuffer): the old
+    // `buffer += chunk; buffer.split('\n')` pattern went quadratic on a
+    // multi-MiB un-terminated line and froze the event loop long enough to
+    // starve the WS heartbeat. The buffer also caps a single newline-less
+    // line and throws a retryable error on a malformed stream.
+    const sseLines = new SseLineBuffer();
     // task-327d: index-keyed per-block state. Anthropic streams content
     // blocks sequentially today, but the protocol exposes `event.index`
     // precisely because that's not guaranteed. Dispatch in
@@ -333,10 +339,8 @@ export class AnthropicAdapter extends LLMAdapter {
         if (done) break;
 
         const chunkText = decoder.decode(value, { stream: true });
-        buffer += chunkText;
         rawSseBodyChunks.push(chunkText);
-        const lines = buffer.split('\n');
-        buffer = lines.pop() || ''; // Keep incomplete line
+        const lines = sseLines.push(chunkText);
 
         for (const line of lines) {
           if (!line.startsWith('data: ')) continue;

package/yeaft/llm/openai-responses.js

@@ -37,6 +37,7 @@ import {
   readStreamChunkWithIdleTimeout,
   redactRawRequest,
   safeHeaders,
+  SseLineBuffer,
 } from './adapter.js';
 import {
   normalizeEffort,
@@ -315,7 +316,12 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
 
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
-    let buffer = '';
+    // Incremental O(n) line splitter (see SseLineBuffer): the old
+    // `buffer += chunk; buffer.split('\n')` pattern went quadratic on a
+    // multi-MiB un-terminated line and froze the event loop long enough to
+    // starve the WS heartbeat. The buffer also caps a single newline-less
+    // line and throws a retryable error on a malformed stream.
+    const sseLines = new SseLineBuffer();
 
     /** Accumulate tool call arguments by output_index.
      *  Value: { callId, name, arguments } */
@@ -342,12 +348,11 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
         });
         if (done) break;
         const chunkText = decoder.decode(value, { stream: true });
-        buffer += chunkText;
         rawSseBodyChunks.push(chunkText);
 
-        // SSE events are separated by blank lines; split on \n
-        const lines = buffer.split('\n');
-        buffer = lines.pop() || '';
+        // SSE events are separated by blank lines; SseLineBuffer yields each
+        // completed line (newline stripped) in O(n) total.
+        const lines = sseLines.push(chunkText);
 
         for (const rawLine of lines) {
           const line = rawLine.trimEnd();

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 },
+      });
+    }
   }
 }