@yeaft/webchat-agent 1.0.52 → 1.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.52",
+  "version": "1.0.54",
   "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/engine.js

@@ -34,6 +34,7 @@ import { readSummary as readScopeSummary } from './memory/store.js';
 import { runAdjust } from './memory/adjust.js';
 import { isVpSeedBackfillStub } from './memory/seed-backfill.js';
 import { runStopHooks } from './stop-hooks.js';
+import { perfNowMs, recordAgentPerfTrace } from './perf-trace.js';
 // Default thread marker for legacy / non-group flows. Group VP runtime may
 // pass a real threadId per (sessionId, vpId, threadId) engine instance.
 const MAIN_THREAD_ID = 'main';
@@ -1720,6 +1721,22 @@ export class Engine {
     const runtimeThreadId = (typeof threadId === 'string' && threadId.trim())
       ? threadId.trim()
       : MAIN_THREAD_ID;
+    const perfTraceId = typeof inboundEnvelope?._perfTraceId === 'string' && inboundEnvelope._perfTraceId.trim()
+      ? inboundEnvelope._perfTraceId.trim()
+      : (typeof inboundEnvelope?.perfTraceId === 'string' && inboundEnvelope.perfTraceId.trim() ? inboundEnvelope.perfTraceId.trim() : null);
+    const traceRequest = (phase, extra = {}) => {
+      if (!perfTraceId) return;
+      recordAgentPerfTrace(this.#config, {
+        traceId: perfTraceId,
+        phase,
+        sessionId: runtimeSessionId || null,
+        vpId: this.#vpId || senderVpId || null,
+        turnId: vpTurnId || null,
+        threadId: runtimeThreadId,
+        messageType: 'llm_request',
+        ...extra,
+      });
+    };
 
     // ─── Pre-query: FTS5 Memory Recall + AMS snapshot ─────
     // Memory has a SINGLE render outlet now (DESIGN-PROMPT §3 ③):
@@ -2088,6 +2105,16 @@ export class Engine {
       });
 
       const startTime = Date.now();
+      const requestPerfStart = perfNowMs();
+      let firstEventTraced = false;
+      traceRequest('llm.request_start', {
+        detail: {
+          model: currentModel,
+          loop: turnNumber,
+          messageCount: conversationMessages.length,
+          toolDefCount: toolDefs.length,
+        },
+      });
       let ttfbMs = null;  // Time to first token
       let responseText = '';
       const toolCalls = [];
@@ -2288,6 +2315,13 @@ export class Engine {
           if (signal?.aborted) {
             throw new LLMAbortError();
           }
+          if (!firstEventTraced) {
+            firstEventTraced = true;
+            traceRequest('llm.first_event', {
+              durationMs: perfNowMs() - requestPerfStart,
+              detail: { eventType: event.type, model: currentModel },
+            });
+          }
           switch (event.type) {
             case 'text_delta':
               if (ttfbMs === null) ttfbMs = Date.now() - startTime;
@@ -2360,6 +2394,16 @@ export class Engine {
             }
           }
         }
+        traceRequest('llm.request_complete', {
+          durationMs: perfNowMs() - requestPerfStart,
+          ok: true,
+          detail: {
+            model: currentModel,
+            stopReason,
+            inputTokens: totalUsage.inputTokens,
+            outputTokens: totalUsage.outputTokens,
+          },
+        });
         // Stream completed without throwing — reset the retry counter so
         // the next turn starts with a clean budget. In-band adapter errors
         // are converted to throws above so they share the real error path.
@@ -2402,6 +2446,16 @@ export class Engine {
           || err?.name === 'LLMAbortError'
           || (signal?.aborted && /abort/i.test(err?.message || ''));
         if (earlyIsAbort || signal?.aborted) {
+          traceRequest('llm.request_abort', {
+            durationMs: perfNowMs() - requestPerfStart,
+            ok: false,
+            detail: {
+              model: currentModel,
+              abortReason: this.#abortReason || 'external',
+              errorName: err?.name || null,
+              signalAborted: !!signal?.aborted,
+            },
+          });
           endAttemptTrace('aborted');
           yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber, threadId };
           yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId };
@@ -2418,6 +2472,18 @@ export class Engine {
           }
         }
 
+        traceRequest('llm.request_error', {
+          durationMs: perfNowMs() - requestPerfStart,
+          ok: false,
+          detail: {
+            model: currentModel,
+            errorName: err?.name || null,
+            statusCode: err?.statusCode ?? null,
+            retryable: err instanceof LLMRateLimitError || err instanceof LLMServerError,
+            message: String(err?.message || '').slice(0, 200),
+          },
+        });
+
         const earlyIsRateLimit = err instanceof LLMRateLimitError;
         const earlyIsTransient = err instanceof LLMServerError;
         if (earlyIsRateLimit || earlyIsTransient) {

package/yeaft/perf-trace.js

@@ -1,7 +1,32 @@
-import { appendFileSync, mkdirSync } from 'fs';
+import { appendFileSync, mkdirSync, readdirSync, rmSync } from 'fs';
 import { join } from 'path';
 
 const MAX_DETAIL_STRING = 512;
+const DEFAULT_RETENTION_DAYS = 3;
+let lastCleanupDay = null;
+
+function retentionDays() {
+  const raw = Number(process.env.PERF_TRACE_RETENTION_DAYS || process.env.YEAFT_PERF_TRACE_RETENTION_DAYS || DEFAULT_RETENTION_DAYS);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_RETENTION_DAYS;
+}
+
+function cleanupOldTraceFiles(root) {
+  const day = new Date().toISOString().slice(0, 10);
+  if (lastCleanupDay === day) return;
+  lastCleanupDay = day;
+  const keepMs = retentionDays() * 24 * 60 * 60 * 1000;
+  const cutoff = Date.now() - keepMs;
+  try {
+    for (const file of readdirSync(root)) {
+      const match = file.match(/^(\d{4}-\d{2}-\d{2})\.jsonl$/);
+      if (!match) continue;
+      const ts = Date.parse(`${match[1]}T00:00:00.000Z`);
+      if (Number.isFinite(ts) && ts < cutoff) rmSync(join(root, file), { force: true });
+    }
+  } catch {
+    // best-effort; trace writes must never break the agent
+  }
+}
 
 function sanitizeString(value, max = MAX_DETAIL_STRING) {
   if (typeof value !== 'string') return value;
@@ -59,6 +84,7 @@ export function recordAgentPerfTrace(config, event = {}) {
   };
   try {
     mkdirSync(root, { recursive: true });
+    cleanupOldTraceFiles(root);
     appendFileSync(join(root, `${day}.jsonl`), `${JSON.stringify(row)}\n`);
     return true;
   } catch (err) {
@@ -71,4 +97,5 @@ export function recordAgentPerfTrace(config, event = {}) {
 
 export const __perfTraceForTest = {
   sanitizeValue,
+  cleanupOldTraceFiles,
 };

package/yeaft/prompts.js

@@ -26,7 +26,6 @@ import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { getRuntimePlatformInfo, renderRuntimePlatformPrompt } from './runtime-platform.js';
-import { DEFAULT_VPS } from './vp/seed-defaults.js';
 
 // ─── Template Loading (one-time at startup) ──────────────────────
 
@@ -463,50 +462,17 @@ function selectVpPersonaName(vpPersona, effectiveLang) {
   return typeof vpPersona.displayName === 'string' ? vpPersona.displayName.trim() : '';
 }
 
-function normalizePersonaBodyForMatch(value) {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-function selectMigratedStockPersonaBody(vpPersona, body, effectiveLang) {
-  const vpId = typeof vpPersona?.vpId === 'string' ? vpPersona.vpId.trim() : '';
-  const persistedBody = normalizePersonaBodyForMatch(body);
-  if (!vpId || !persistedBody) return null;
-
-  const stock = DEFAULT_VPS.find(vp => vp.vpId === vpId);
-  if (!stock) return null;
-
-  const acceptedBodies = [
-    stock.legacyPersonaEn,
-    stock.legacyPersona,
-    stock.personaEn,
-    ...(Array.isArray(stock.legacyPersonas) ? stock.legacyPersonas : []),
-  ]
-    .map(normalizePersonaBodyForMatch)
-    .filter(Boolean);
-
-  if (!acceptedBodies.includes(persistedBody)) return null;
-  const selected = effectiveLang === 'zh' ? stock.personaZh : stock.personaEn;
-  return normalizePersonaBodyForMatch(selected) || null;
-}
-
 function selectVpPersonaBody(vpPersona, effectiveLang) {
   const body = typeof vpPersona.persona === 'string' ? vpPersona.persona.trim() : '';
 
-  // role.md persona is the canonical soul. Exact stock legacy bodies are mapped
-  // to the current authored source so old seeded role.md files do not leak
-  // bilingual/English souls into localized system prompts before top-up runs.
-  if (body) {
-    const migratedStockBody = selectMigratedStockPersonaBody(vpPersona, body, effectiveLang);
-    if (migratedStockBody) return migratedStockBody;
-
-    if (body.includes('<!-- lang:')) {
-      const selected = extractExactLangSection(body, effectiveLang);
-      return selected !== null ? selected : body;
-    }
-    return body;
+  // role.md is the canonical soul source. Stock legacy migration belongs in
+  // seed-topup, not in prompt rendering; prompt rendering should only select
+  // authored language sections when they are present.
+  if (body && body.includes('<!-- lang:')) {
+    const selected = extractExactLangSection(body, effectiveLang);
+    return selected !== null ? selected : body;
   }
-
-  return '';
+  return body;
 }
 
 

package/yeaft/vp/seed-topup.js

@@ -9,24 +9,30 @@
  * (b) a forced overwrite that would clobber their hand edits.
  *
  * This module runs on every agent start alongside `seedDefaultVps` and does
- * two minimal, additive things:
+ * three safe stock-maintenance things:
  *
  *   1. **Top-up missing stock VPs**. If a vpId from `DEFAULT_VPS` is not
  *      on disk, `createVp()` it. This keeps product-owned defaults such as
  *      Omni and the expanded role roster visible in session/member pickers.
  *
- *   2. **Backfill the `area` frontmatter line** on existing seeded VPs whose
- *      role.md predates the area field. The body is left BYTE-IDENTICAL —
- *      we splice a single `area: <bucket>` line into the YAML frontmatter
- *      and write nothing else. If the user has authored their own `area`,
- *      we keep theirs.
+ *   2. **Backfill missing stock frontmatter** (`area`, `nameZh`, `roleZh`) on
+ *      existing seeded VPs whose role.md predates those fields. The persona body
+ *      is left BYTE-IDENTICAL for these metadata backfills. If the user has
+ *      authored their own value, we keep theirs.
+ *
+ *   3. **Migrate exact historical stock bodies to canonical localized bodies**.
+ *      This is intentionally a write-time migration, not a prompt-rendering
+ *      fallback: once top-up sees an old shipped Omni/Linus/etc. body, role.md is
+ *      rewritten to the current `<!-- lang:en -->` / `<!-- lang:zh -->` stock
+ *      persona. User-edited bodies are not touched.
  *
  * Hard rules:
- *   - **Never** overwrite a VP that is on disk. The user might have edited
- *     persona/role/traits; that is their truth, not ours.
- *   - **Keep stock defaults available.** If a shipped stock VP is missing,
- *     recreate it, but never overwrite an on-disk VP. The session/member picker
- *     depends on these product-owned defaults being present.
+ *   - **Never** overwrite a user-edited VP. A persona body is only rewritten when
+ *     it exactly matches a historical body shipped by us.
+ *   - **Keep stock defaults canonical and available.** If a shipped stock VP is
+ *     missing, recreate it. If it exists with an old exact stock body, rewrite
+ *     that body to the current canonical localized body. The session/member
+ *     picker depends on these product-owned defaults being present and current.
  *   - Best-effort: any failure is logged, never thrown.
  *
  * Pre-ledger deletion caveat: on the very first top-up against an existing
@@ -47,8 +53,9 @@
  *     }
  *   }
  *
- * The hash is reserved for future "the default persona changed; offer the
- * user a migration" semantics. We do not auto-upgrade today.
+ * The hash tracks the canonical stock persona currently written by top-up. Exact
+ * historical stock bodies are auto-migrated to this canonical localized body;
+ * user-edited bodies are deliberately left alone.
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'fs';
@@ -231,7 +238,7 @@ function replaceRoleBody(source, body) {
   return `${match[1]}${String(body || '').trim()}\n`;
 }
 
-function backfillLocalizedPersonaBody(source, vp) {
+export function backfillLocalizedPersonaBody(source, vp) {
   const body = roleBodyOf(source).trim();
   const nextBody = typeof vp.persona === 'string' ? vp.persona.trim() : '';
   if (!body || !nextBody || body === nextBody) return null;
@@ -301,9 +308,9 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
     const inLedger = Object.prototype.hasOwnProperty.call(versions.seeded, vpId);
 
     if (onDisk) {
-      // Already there — never overwrite. Possibly backfill `area` /
-      // `nameZh`. Each backfill is independent: a role.md with `area`
-      // already set but no `nameZh` should still get `nameZh`.
+      // Already there — preserve user-authored content, but keep shipped stock
+      // defaults canonical. Metadata backfills only add missing frontmatter;
+      // persona migration only rewrites exact historical stock bodies.
       skippedExisting.push(vpId);
       let currentSrc = null;
       const rolePath = join(libDir, vpId, 'role.md');
@@ -388,6 +395,7 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
             if (patched != null && patched !== src) {
               writeFileSync(rolePath, patched, 'utf-8');
               currentSrc = patched;
+              versions.seeded[vpId] = personaHash(vp.persona);
               personaBackfilled.push(vpId);
             }
           }

package/yeaft/web-bridge.js

@@ -861,11 +861,12 @@ function projectVisibleHistoryChunkMessages(messages = []) {
     }));
 }
 
-function emitHistoryChunk({ sessionId, messages, mode = 'older', oldestSeq = null, hasMore = false, latestSeq = null, afterSeq = null, turns = null }) {
+function emitHistoryChunk({ sessionId, messages, mode = 'older', oldestSeq = null, hasMore = false, latestSeq = null, afterSeq = null, turns = null, perfTraceId = null }) {
   const projectedMessages = projectVisibleHistoryChunkMessages(messages);
   sendToServer({
     type: 'yeaft_history_chunk',
     conversationId: yeaftConversationId,
+    ...(perfTraceId ? { perfTraceId } : {}),
     sessionId,
     mode,
     messages: projectedMessages,
@@ -921,7 +922,7 @@ function emitLegacyHistoryOutputFrames(replayEntries) {
   }
 }
 
-function emitVisibleHistoryReplay({ store, sessionId, limit, beforeSeq = null, mode = 'recent' }) {
+function emitVisibleHistoryReplay({ store, sessionId, limit, beforeSeq = null, mode = 'recent', perfTraceId = null }) {
   const visiblePage = sessionId
     ? loadVisibleGroupHistoryPage(store, sessionId, limit, beforeSeq)
     : { messages: limit > 0 ? (store.loadRecent?.(limit) || []) : [], oldestSeq: null, hasMore: false };
@@ -943,6 +944,7 @@ function emitVisibleHistoryReplay({ store, sessionId, limit, beforeSeq = null, m
       hasMore: visiblePage.hasMore,
       latestSeq: Number.isFinite(latestSeq) ? latestSeq : null,
       turns: limit,
+      perfTraceId,
     });
     sendSessionEvent({
       type: 'history_loaded',
@@ -952,7 +954,7 @@ function emitVisibleHistoryReplay({ store, sessionId, limit, beforeSeq = null, m
       hasMore: visiblePage.hasMore,
       oldestSeq: visiblePage.oldestSeq,
       latestSeq: Number.isFinite(latestSeq) ? latestSeq : null,
-    });
+    }, perfTraceId ? { sessionId, perfTraceId } : undefined);
     return;
   }
 
@@ -969,7 +971,7 @@ function emitVisibleHistoryReplay({ store, sessionId, limit, beforeSeq = null, m
     hasMore: visiblePage.hasMore,
     oldestSeq: visiblePage.oldestSeq,
     latestSeq: Number.isFinite(latestSeq) ? latestSeq : null,
-  });
+  }, perfTraceId ? { sessionId, perfTraceId } : undefined);
 }
 
 /**
@@ -5041,6 +5043,27 @@ export function handleYeaftModelSwitch(msg) {
  */
 export async function handleYeaftLoadHistory(msg) {
   const sessionId = (msg && typeof msg.sessionId === 'string' && msg.sessionId) || null;
+  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 || 'yeaft_load_history',
+      ...extra,
+    });
+  };
+  const traceDuration = (phase, start, extra = {}) => tracePerf(phase, { durationMs: perfNowMs() - start, ...extra });
+  tracePerf('history.received', {
+    detail: {
+      limit: Number.isFinite(msg?.limit) ? msg.limit : null,
+      afterSeq: Number.isFinite(msg?.afterSeq) ? msg.afterSeq : null,
+      metadataOnly: !!(msg && Number.isFinite(msg.limit) && msg.limit <= 0),
+      sessionLoaded: !!session,
+    },
+  });
   const metadataOnly = msg && Number.isFinite(msg.limit) && msg.limit <= 0;
   // `lim` is now expressed in TURNS, not raw messages. `loadRecent` and
   // `loadRecentBySession` use turn-based slicing so the cut never lands
@@ -5063,14 +5086,19 @@ export async function handleYeaftLoadHistory(msg) {
       afterSeq = session.conversationStore.getMessageSeqById(afterMessageId);
     }
     if (sessionId && afterSeq !== null && typeof session.conversationStore.loadAfterSeqByGroup === 'function') {
+      const loadStart = perfNowMs();
       const delta = session.conversationStore.loadAfterSeqByGroup(sessionId, afterSeq);
+      traceDuration('history.store_load_delta', loadStart, { detail: { count: delta.messages?.length || 0, afterSeq } });
+      const emitStart = perfNowMs();
       const projectedMessages = emitHistoryChunk({
         sessionId,
         messages: delta.messages,
         mode: 'delta',
         latestSeq: delta.latestSeq,
         afterSeq,
+        perfTraceId,
       });
+      traceDuration('history.emit_chunk', emitStart, { detail: { mode: 'delta', count: projectedMessages.length } });
       sendSessionEvent({
         type: 'history_loaded',
         mode: 'delta',
@@ -5078,7 +5106,7 @@ export async function handleYeaftLoadHistory(msg) {
         sessionId,
         latestSeq: delta.latestSeq,
         afterSeq,
-      });
+      }, perfTraceId ? { sessionId, perfTraceId } : undefined);
       return;
     }
 
@@ -5087,9 +5115,11 @@ export async function handleYeaftLoadHistory(msg) {
     // opening a group can paint the latest messages quickly; older rows are
     // paged via `yeaft_load_more_history` when the user scrolls upward.
     const limit = (typeof msg.limit === 'number') ? msg.limit : 10;
+    const loadStart = perfNowMs();
     const visiblePage = sessionId
       ? loadVisibleGroupHistoryPage(session.conversationStore, sessionId, limit)
       : { messages: limit > 0 ? pickRecent(session.conversationStore, limit) : [], oldestSeq: null, hasMore: false };
+    traceDuration('history.store_load_recent', loadStart, { detail: { rawCount: visiblePage.messages?.length || 0, limit } });
     // Legacy compact.md is a non-group fallback only. For group replay, reading
     // it makes every group show "has compact" once any legacy/non-scoped compact
     // exists, even when this group has no scoped summary.
@@ -5107,6 +5137,7 @@ export async function handleYeaftLoadHistory(msg) {
     }
 
     if (sessionId) {
+      const emitStart = perfNowMs();
       emitHistoryChunk({
         sessionId,
         messages: replayEntries,
@@ -5115,7 +5146,9 @@ export async function handleYeaftLoadHistory(msg) {
         hasMore: visiblePage.hasMore,
         latestSeq,
         turns: limit,
+        perfTraceId,
       });
+      traceDuration('history.emit_chunk', emitStart, { detail: { mode: 'recent', count: replayEntries.length } });
     } else {
       emitLegacyHistoryOutputFrames(replayEntries);
     }
@@ -5152,7 +5185,7 @@ export async function handleYeaftLoadHistory(msg) {
       hasMore,
       oldestSeq,
       latestSeq,
-    });
+    }, perfTraceId ? { sessionId, perfTraceId } : undefined);
   };
 
   if (!session) {
@@ -5166,34 +5199,45 @@ export async function handleYeaftLoadHistory(msg) {
     // skill scans, memory index sync). The conversation markdown store is the
     // source of truth and can be opened cheaply, so replay the visible message
     // window immediately, then finish loadSession below for actual turns.
+    const coldStoreStart = perfNowMs();
     const coldStore = new ConversationStore(yeaftDir);
+    traceDuration('history.cold_store_open', coldStoreStart);
     if (sessionId && (afterSeqRaw !== null || afterMessageId)) {
       let afterSeq = afterSeqRaw;
       if (afterSeq === null && afterMessageId && typeof coldStore.getMessageSeqById === 'function') {
         afterSeq = coldStore.getMessageSeqById(afterMessageId);
       }
+      const loadStart = perfNowMs();
       const delta = afterSeq !== null && typeof coldStore.loadAfterSeqByGroup === 'function'
         ? coldStore.loadAfterSeqByGroup(sessionId, afterSeq)
         : { messages: [], latestSeq: null };
+      traceDuration('history.store_load_delta', loadStart, { detail: { count: delta.messages?.length || 0, afterSeq, cold: true } });
+      const emitStart = perfNowMs();
       const projectedMessages = emitHistoryChunk({
         sessionId,
         messages: delta.messages,
         mode: 'delta',
         latestSeq: delta.latestSeq,
         afterSeq,
+        perfTraceId,
       });
-      sendSessionEvent({ type: 'history_loaded', mode: 'delta', count: projectedMessages.length, sessionId, latestSeq: delta.latestSeq, afterSeq });
+      traceDuration('history.emit_chunk', emitStart, { detail: { mode: 'delta', count: projectedMessages.length, cold: true } });
+      sendSessionEvent({ type: 'history_loaded', mode: 'delta', count: projectedMessages.length, sessionId, latestSeq: delta.latestSeq, afterSeq }, perfTraceId ? { sessionId, perfTraceId } : undefined);
     } else if (!metadataOnly) {
-      emitVisibleHistoryReplay({ store: coldStore, sessionId, limit, mode: 'recent' });
+      const replayStart = perfNowMs();
+      emitVisibleHistoryReplay({ store: coldStore, sessionId, limit, mode: 'recent', perfTraceId });
+      traceDuration('history.cold_replay', replayStart, { detail: { mode: 'recent', limit } });
     }
     historyAlreadyReplayed = true;
 
+    const bootStart = perfNowMs();
     session = await loadSession({
       dir: yeaftDir,
       skipMCP: false,
       skipSkills: false,
       serverMode: true,
     });
+    traceDuration('history.load_session_runtime', bootStart);
     installYeaftRuntimeBridge(session);
 
     // Per-group history hydrates lazily via getOrCreateSessionHistory.
@@ -5201,9 +5245,15 @@ export async function handleYeaftLoadHistory(msg) {
     // group's tape so the next user message sees on-disk state. When
     // it doesn't (legacy callers), do nothing — the per-group lazy
     // hydration handles it.
-    if (sessionId) setGroupHistory(sessionId, hydrateGroupHistory(sessionId));
+    if (sessionId) {
+      const hydrateStart = perfNowMs();
+      setGroupHistory(sessionId, hydrateGroupHistory(sessionId));
+      traceDuration('history.hydrate_group_history', hydrateStart);
+    }
   } else {
+    const replayStart = perfNowMs();
     replayHistoryFromStore();
+    traceDuration('history.replay_from_store', replayStart);
     historyAlreadyReplayed = true;
   }
 
@@ -5211,7 +5261,9 @@ export async function handleYeaftLoadHistory(msg) {
     // Re-entering an existing session with a (possibly new) group filter:
     // re-seed THIS group's history from disk so it doesn't carry stale
     // in-memory state into the next turn's context.
+    const hydrateStart = perfNowMs();
     setGroupHistory(sessionId, hydrateGroupHistory(sessionId));
+    traceDuration('history.hydrate_group_history_final', hydrateStart);
   }
 
   // Always replay session_ready so refresh / reconnect rebuilds UI state, but
@@ -5220,9 +5272,15 @@ export async function handleYeaftLoadHistory(msg) {
   // tick so the browser can paint messages before VP/session/dream snapshots.
   scheduleYeaftLoadHistoryMetadataReplay(sessionId);
 
-  if (historyAlreadyReplayed) return;
+  if (historyAlreadyReplayed) {
+    traceDuration('history.handler_total', perfStart, { ok: true });
+    return;
+  }
 
+  const replayStart = perfNowMs();
   replayHistoryFromStore();
+  traceDuration('history.replay_from_store', replayStart);
+  traceDuration('history.handler_total', perfStart, { ok: true });
 }
 
 /**
@@ -5240,8 +5298,17 @@ export async function handleYeaftLoadHistory(msg) {
  */
 export async function handleYeaftLoadMoreHistory(msg) {
   const sessionId = (msg && typeof msg.sessionId === 'string' && msg.sessionId) || null;
+  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 || 'yeaft_load_more_history', ...extra });
+  };
+  const traceDuration = (phase, start, extra = {}) => tracePerf(phase, { durationMs: perfNowMs() - start, ...extra });
+  tracePerf('history_more.received');
   if (!session || !sessionId) {
-    emitHistoryChunk({ sessionId, messages: [], mode: 'older', oldestSeq: null, hasMore: false });
+    emitHistoryChunk({ sessionId, messages: [], mode: 'older', oldestSeq: null, hasMore: false, perfTraceId });
+    traceDuration('history_more.handler_total', perfStart, { ok: false, detail: { missingSession: !session, missingSessionId: !sessionId } });
     return;
   }
 
@@ -5250,16 +5317,20 @@ export async function handleYeaftLoadMoreHistory(msg) {
 
   let result;
   try {
+    const loadStart = perfNowMs();
     result = loadVisibleGroupHistoryPage(session.conversationStore, sessionId, turns, beforeSeq);
+    traceDuration('history_more.store_load', loadStart, { detail: { count: result.messages?.length || 0, beforeSeq, turns } });
   } catch (err) {
     console.error('[Yeaft] loadOlderBySession failed:', err.message);
     result = { messages: [], oldestSeq: null, hasMore: false };
+    tracePerf('history_more.store_error', { ok: false, detail: { errorName: err?.name || null, errorMessage: err?.message || String(err) } });
   }
 
   // Wire shape mirrors handleYeaftLoadHistory's projection: only visible
   // user / assistant text rows. Internal reflection/system-only rows stay
   // server-side, and stable ids + speaker attribution ride with each row
   // so older-history prepend renders exactly like refresh replay.
+  const emitStart = perfNowMs();
   emitHistoryChunk({
     sessionId,
     messages: result.messages || [],
@@ -5267,7 +5338,10 @@ export async function handleYeaftLoadMoreHistory(msg) {
     oldestSeq: result.oldestSeq,
     hasMore: !!result.hasMore,
     turns,
+    perfTraceId,
   });
+  traceDuration('history_more.emit_chunk', emitStart, { detail: { count: result.messages?.length || 0 } });
+  traceDuration('history_more.handler_total', perfStart, { ok: true });
 }
 
 /**