@yeaft/webchat-agent 1.0.177 → 1.0.180

package/yeaft/tools/grep.js

@@ -8,12 +8,21 @@
 import { defineTool } from './types.js';
 import { spawn } from 'child_process';
 import { readdir, readFile, stat } from 'fs/promises';
+import { StringDecoder } from 'string_decoder';
 import { existsSync } from 'fs';
 import { resolve, join, relative, extname } from 'path';
 
 /** Max output lines. */
 const MAX_LINES = 250;
 
+/** Hard cap before Grep output reaches history, debug events, or WebSocket. */
+const MAX_OUTPUT_BYTES = 512 * 1024;
+const OUTPUT_TRUNCATED_MARKER = '\n\n[Output truncated]';
+const MAX_CAPTURE_BYTES = MAX_OUTPUT_BYTES - Buffer.byteLength(OUTPUT_TRUNCATED_MARKER, 'utf8');
+
+/** Keep one pathological source line from consuming the whole output budget. */
+const MAX_LINE_BYTES = 16 * 1024;
+
 /** Binary extensions to skip. */
 const BINARY_EXTS = new Set([
   '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp',
@@ -25,6 +34,77 @@ const BINARY_EXTS = new Set([
   '.sqlite', '.db',
 ]);
 
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+
+function decodeTextFile(buffer) {
+  // Extension lists are only a fast path. Generated artifacts and renamed
+  // binaries commonly have no useful extension, especially on Windows.
+  if (buffer.includes(0)) return null;
+  try { return utf8Decoder.decode(buffer); } catch { return null; }
+}
+
+function truncateUtf8(text, maxBytes) {
+  if (maxBytes <= 0) return '';
+  const buffer = Buffer.from(text, 'utf8');
+  if (buffer.length <= maxBytes) return text;
+  return new StringDecoder('utf8').write(buffer.subarray(0, maxBytes));
+}
+
+function boundToolOutput(text) {
+  if (Buffer.byteLength(text, 'utf8') <= MAX_OUTPUT_BYTES) return text;
+  return truncateUtf8(text, MAX_CAPTURE_BYTES) + OUTPUT_TRUNCATED_MARKER;
+}
+
+function formatGrepError(message) {
+  const errorMessage = `Grep failed: ${message}`;
+  const serialized = JSON.stringify({ error: errorMessage });
+  if (Buffer.byteLength(serialized, 'utf8') <= MAX_OUTPUT_BYTES) return serialized;
+
+  const markerBytes = Buffer.byteLength(OUTPUT_TRUNCATED_MARKER, 'utf8');
+  let low = 0;
+  let high = Math.max(0, Buffer.byteLength(errorMessage, 'utf8') - markerBytes);
+  let result = JSON.stringify({ error: OUTPUT_TRUNCATED_MARKER });
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    const candidate = JSON.stringify({
+      error: truncateUtf8(errorMessage, mid) + OUTPUT_TRUNCATED_MARKER,
+    });
+    if (Buffer.byteLength(candidate, 'utf8') <= MAX_OUTPUT_BYTES) {
+      result = candidate;
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  return result;
+}
+
+function createOutputCollector(maxBytes = MAX_OUTPUT_BYTES) {
+  const parts = [];
+  const contentBytes = Math.max(0, maxBytes - Buffer.byteLength(OUTPUT_TRUNCATED_MARKER, 'utf8'));
+  let bytes = 0;
+  let truncated = false;
+  return {
+    add(value) {
+      if (truncated) return false;
+      const normalized = String(value).replace(/\r/g, '');
+      const line = truncateUtf8(normalized, MAX_LINE_BYTES);
+      const lineWasTruncated = Buffer.byteLength(normalized, 'utf8') > Buffer.byteLength(line, 'utf8');
+      const separator = parts.length > 0 ? '\n' : '';
+      const remaining = contentBytes - bytes - Buffer.byteLength(separator, 'utf8');
+      if (remaining <= 0) { truncated = true; return false; }
+      const bounded = truncateUtf8(line, remaining);
+      parts.push(separator + bounded);
+      bytes += Buffer.byteLength(separator + bounded, 'utf8');
+      if (lineWasTruncated || bounded !== line) truncated = true;
+      return !truncated;
+    },
+    toString() { return parts.join('') + (truncated ? OUTPUT_TRUNCATED_MARKER : ''); },
+  };
+}
+
 /**
  * Check if ripgrep is available.
  */
@@ -39,7 +119,7 @@ function hasRipgrep() {
 /**
  * Run ripgrep and return results.
  */
-function runRipgrep(pattern, searchPath, options) {
+export function runRipgrep(pattern, searchPath, options, spawnProcess = spawn) {
   return new Promise((resolve, reject) => {
     const args = [
       pattern,
@@ -60,44 +140,72 @@ function runRipgrep(pattern, searchPath, options) {
     if (options.multiline) args.push('-U', '--multiline-dotall');
     args.push('--max-count', String(options.maxResults || 500));
 
-    const proc = spawn('rg', args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout.on('data', (chunk) => {
-      stdout += chunk.toString();
-      // Truncate early if way too large
-      if (stdout.length > 512 * 1024) {
+    const proc = spawnProcess('rg', args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let capturedBytes = 0;
+    let truncatedStream = null;
+    let settled = false;
+
+    function capture(streamName, chunk, chunks) {
+      if (truncatedStream) return;
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remaining = MAX_CAPTURE_BYTES - capturedBytes;
+      if (buffer.length > remaining) {
+        if (remaining > 0) chunks.push(buffer.subarray(0, remaining));
+        capturedBytes = MAX_CAPTURE_BYTES;
+        truncatedStream = streamName;
         try { proc.kill(); } catch {}
+        return;
       }
-    });
-    proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+      chunks.push(buffer);
+      capturedBytes += buffer.length;
+    }
+
+    function decodeCaptured(chunks, wasTruncated) {
+      // Buffer decoding normally expands each invalid byte to the three-byte
+      // U+FFFD replacement character. Use a one-byte replacement, then enforce
+      // the final encoded-byte boundary as a last line of defense.
+      const marker = wasTruncated ? OUTPUT_TRUNCATED_MARKER : '';
+      const maxTextBytes = MAX_OUTPUT_BYTES - Buffer.byteLength(marker, 'utf8');
+      const decoded = Buffer.concat(chunks).toString('utf8').replaceAll('\ufffd', '?').replace(/\r/g, '');
+      return truncateUtf8(decoded, maxTextBytes) + marker;
+    }
+
+    proc.stdout.on('data', (chunk) => capture('stdout', chunk, stdoutChunks));
+    proc.stderr.on('data', (chunk) => capture('stderr', chunk, stderrChunks));
     proc.on('close', (code) => {
-      if (code === 0 || code === 1) {
-        resolve(stdout);
-      } else {
-        reject(new Error(stderr || `rg exited with code ${code}`));
-      }
+      if (settled) return;
+      settled = true;
+      const stdout = decodeCaptured(stdoutChunks, truncatedStream === 'stdout');
+      const stderr = decodeCaptured(stderrChunks, truncatedStream === 'stderr');
+      if (code === 0 || code === 1 || truncatedStream === 'stdout') resolve(stdout);
+      else reject(new Error(stderr || `rg exited with code ${code}`));
+    });
+    proc.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
     });
-    proc.on('error', reject);
   });
 }
 
 /**
  * Fallback: Node.js grep implementation.
  */
-async function nodeGrep(pattern, searchPath, options) {
+export async function nodeGrep(pattern, searchPath, options) {
   const regex = new RegExp(pattern, options.caseInsensitive ? 'gi' : 'g');
-  const results = [];
+  const output = createOutputCollector();
+  let resultCount = 0;
   const SKIP = new Set(['node_modules', '.git', '__pycache__', '.next', 'dist', 'build', '.cache']);
 
   async function searchDir(dir) {
-    if (results.length >= (options.maxResults || 500)) return;
+    if (resultCount >= (options.maxResults || 500)) return;
     let entries;
     try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
 
     for (const entry of entries) {
-      if (results.length >= (options.maxResults || 500)) return;
+      if (resultCount >= (options.maxResults || 500)) return;
       const fullPath = join(dir, entry.name);
 
       if (entry.isDirectory()) {
@@ -111,22 +219,32 @@ async function nodeGrep(pattern, searchPath, options) {
           const fileStat = await stat(fullPath);
           if (fileStat.size > 1024 * 1024) continue; // skip files > 1MB
 
-          const content = await readFile(fullPath, 'utf-8');
+          const buffer = await readFile(fullPath);
+          const content = decodeTextFile(buffer);
+          if (content == null) continue;
           const relPath = relative(searchPath, fullPath);
 
           if (options.filesOnly) {
-            if (regex.test(content)) results.push(relPath);
+            if (regex.test(content)) {
+              resultCount += 1;
+              if (!output.add(relPath)) return;
+            }
             regex.lastIndex = 0;
           } else if (options.count) {
             const matches = content.match(regex);
-            if (matches) results.push(`${relPath}:${matches.length}`);
+            if (matches) {
+              resultCount += 1;
+              if (!output.add(`${relPath}:${matches.length}`)) return;
+            }
           } else {
             const lines = content.split('\n');
             for (let i = 0; i < lines.length; i++) {
               if (regex.test(lines[i])) {
-                results.push(`${relPath}:${i + 1}:${lines[i]}`);
+                resultCount += 1;
+                if (!output.add(`${relPath}:${i + 1}:${lines[i]}`)) return;
               }
               regex.lastIndex = 0;
+              if (resultCount >= (options.maxResults || 500)) return;
             }
           }
         } catch {
@@ -137,7 +255,7 @@ async function nodeGrep(pattern, searchPath, options) {
   }
 
   await searchDir(searchPath);
-  return results.join('\n');
+  return output.toString();
 }
 
 export default defineTool({
@@ -302,15 +420,18 @@ Guidelines:
         return '(no matches)';
       }
 
-      // Limit output lines
+      // Limit output lines, then enforce the byte budget at the actual tool
+      // boundary so prefixes, JSON escaping, and result markers are included.
       const lines = result.trim().split('\n');
       if (lines.length > head_limit) {
-        return lines.slice(0, head_limit).join('\n') + `\n\n... (${lines.length - head_limit} more results)`;
+        return boundToolOutput(
+          lines.slice(0, head_limit).join('\n') + `\n\n... (${lines.length - head_limit} more results)`,
+        );
       }
 
-      return result.trim();
+      return boundToolOutput(result.trim());
     } catch (err) {
-      return JSON.stringify({ error: `Grep failed: ${err.message}` });
+      return formatGrepError(err.message);
     }
   },
 });

package/yeaft/tools/image-generation.js

@@ -5,6 +5,7 @@
  */
 
 import { defineTool } from './types.js';
+import { downloadRemoteImage } from '../remote-image-download.js';
 
 export default defineTool({
   name: 'ImageGeneration',
@@ -83,29 +84,26 @@ Guidelines:
 
       const data = await response.json();
 
-      // If output_path specified, save the image
-      if (output_path && data.url) {
+      if (!data.url) return JSON.stringify({ error: 'Image API returned no image URL' });
+      const { buffer, mimeType } = await downloadRemoteImage(data.url, {
+        signal: ctx?.signal,
+        ...(ctx?.remoteImageDownload || {}),
+      });
+      let savedPath = null;
+      if (output_path) {
         const { resolve: resolvePath } = await import('path');
         const { writeFile } = await import('fs/promises');
-
-        const imgResponse = await fetch(data.url);
-        const buffer = Buffer.from(await imgResponse.arrayBuffer());
-        const absPath = resolvePath(ctx?.cwd || process.cwd(), output_path);
-        await writeFile(absPath, buffer);
-
-        return JSON.stringify({
-          success: true,
-          path: absPath,
-          size,
-          prompt: prompt.slice(0, 100),
-        });
+        savedPath = resolvePath(ctx?.cwd || process.cwd(), output_path);
+        await writeFile(savedPath, buffer);
       }
-
       return JSON.stringify({
         success: true,
-        url: data.url,
+        ...(savedPath ? { path: savedPath } : {}),
         size,
         prompt: prompt.slice(0, 100),
+        image: `data:${mimeType};base64,${buffer.toString('base64')}`,
+        mimeType,
+        filename: savedPath ? savedPath.split(/[/\\]/).pop() : `generated-${Date.now()}`,
       });
     } catch (err) {
       if (err.name === 'AbortError') return JSON.stringify({ error: 'Generation cancelled' });

package/yeaft/vp/registry.js

@@ -27,8 +27,8 @@ export class Registry {
   /**
    * Replace a VP's persona fields in-place, preserving identity so any
    * downstream reference keeps its handle stable across hot-reload.
-   * Fields copied: name, role, traits, modelHint, persona, personaHash,
-   * mtimeMs.
+   * Fields copied: localized identity metadata, aliases, role, traits,
+   * modelHint, persona, personaHash, planInstruction, and mtimeMs.
    */
   updateVpInPlace(next) {
     const cur = this.vpMap.get(next.id);
@@ -37,11 +37,18 @@ export class Registry {
       return next;
     }
     cur.name = next.name;
+    cur.nameZh = next.nameZh;
+    cur.aliases = next.aliases;
+    cur.description = next.description;
+    cur.descriptionZh = next.descriptionZh;
     cur.role = next.role;
+    cur.roleZh = next.roleZh;
+    cur.area = next.area;
     cur.traits = next.traits;
     cur.modelHint = next.modelHint;
     cur.persona = next.persona;
     cur.personaHash = next.personaHash;
+    cur.planInstruction = next.planInstruction;
     cur.mtimeMs = next.mtimeMs;
     // dir / memoryDir / id stable
     return cur;

package/yeaft/vp/seed-defaults.js

@@ -1,14 +1,14 @@
 /**
- * seed-defaults.js — task-337: first-run seed of 33 default Virtual Persons.
+ * seed-defaults.js — task-337: first-run seed of 34 default Virtual Persons.
  *
  * Problem: A brand-new VP library is empty, and asking the user to author
  * dozens of personas before they can even start chatting is a non-starter.
  *
- * Solution: On first-run (libDir empty or missing), materialise 33 classic
+ * Solution: On first-run (libDir empty or missing), materialise 34 classic
  * personas with hand-crafted prompts so the session experience works
- * out of the box. Originally 12 (engineering/design/science/security/business);
- * expanded to 32 by adding philosophy / psychology / strategy / history /
- * investing / business / writing / science / arts (task: VP roster expansion).
+ * out of the box. The original engineering/design/science/security/business
+ * roster was expanded with philosophy, psychology, strategy, history,
+ * investing, writing, arts, a generalist, and a cloud-scale language architect.
  *
  * Idempotent: if ANY VP directory already exists under libDir, this is a
  * no-op. We never overwrite user-authored VPs, never "upgrade" existing
@@ -34,14 +34,14 @@ import { DEFAULT_VP_LIB_DIR } from './vp-store.js';
 import { STOCK_VP_IDS } from './stock-ids.js';
 
 /**
- * The 33 default VPs. Each entry is a valid `createVp` payload.
+ * The 34 default VPs. Each entry is a valid `createVp` payload.
  * Persona bodies are authored directly per stock member in English and Chinese.
  * Legacy bodies are kept only for exact-match safe upgrades.
  *
- * Order is intentional: the original 12 (engineering/design/science/security/
- * business) come first, then the 20 expansion VPs organized by area, followed by
- * the generalist entry point. Sidebar organization by area is a future PR; today
- * the field is data-only.
+ * Order is intentional: the core engineering/design/science/security/business
+ * roster comes first, then the expansion VPs organized by area, followed by the
+ * generalist entry point. Sidebar organization by area is a future PR; today the
+ * field is data-only.
  */
 const DEFAULT_VP_DEFINITIONS = Object.freeze([
   {
@@ -167,6 +167,35 @@ Good for: PR reviews, legacy cleanup, architecture conversations, naming debates
 Bad for: greenfield scaffolding from zero, raw performance tuning, UI design.`,
   },
 
+  {
+    vpId: 'anders',
+    displayName: 'Anders Hejlsberg',
+    displayNameZh: '安德斯·海尔斯伯格',
+    aliases: ['anders', 'hejlsberg', 'andesi', 'haierxiboge'],
+    role: 'Language and Cloud Systems Architect',
+    roleZh: '语言与云系统架构师',
+    description: 'Language design, API compatibility, and reliable cloud-scale evolution',
+    descriptionZh: '语言设计、API 兼容性与可靠的云规模演进',
+    area: 'engineering',
+    traits: [
+      'language-design', 'reliability', 'backward-compatibility',
+      'observability', 'operational-simplicity', 'incremental-evolution',
+      'ownership-boundaries',
+    ],
+    modelHint: 'primary',
+    personaEn: `You are Anders Hejlsberg. You designed C#, TypeScript, and Turbo Pascal. You review code as if it belongs to a large-scale Azure service with millions of users, where a locally elegant choice can become an operational liability at fleet scale.
+
+You prioritize reliability, backward compatibility, observability, operational simplicity, safe incremental evolution, and clear ownership boundaries. Language and API design matter because contracts outlive implementations; migrations, failure modes, diagnostics, and rollback paths are part of the design, not afterthoughts.
+
+Users bring you language, API, platform, and cloud-service changes. Show them the contract that can evolve safely, the compatibility hazards, the operational signals, and the smallest rollout that proves the change. Reject solutions that are beautiful in isolation but difficult to operate across a large service.`,
+    personaZh: `你是安德斯·海尔斯伯格。你设计了 C#、TypeScript 和 Turbo Pascal。你把代码当作服务于数百万用户的 Azure 级系统来评审：局部看似优雅的选择，到了大规模运行环境里可能就是长期运维负担。
+
+你优先考虑可靠性、向后兼容、可观测性、运维简洁、安全的增量演进和清晰的责任边界。语言与 API 设计的核心是长期契约；迁移路径、失败模式、诊断能力和回滚方案本来就是设计的一部分。
+
+用户通常带来语言、API、平台或云服务改动。你会指出能够安全演进的契约、兼容性风险、必要的运行信号，以及验证改动的最小发布步骤。你拒绝那些孤立看很漂亮、在云规模下却难以运营的方案。`,
+    legacyPersonaEn: '',
+  },
+
   {
     vpId: 'dieter',
     displayName: 'Dieter Rams',
@@ -1401,6 +1430,42 @@ Answer style: concise, organized, and forward-moving. When routing is needed, ro
   }
 ]);
 
+const DEFAULT_VP_DESCRIPTIONS = Object.freeze({
+  steve: ['Product vision, ruthless prioritization, and launch narrative', '产品愿景、果断取舍与发布叙事'],
+  linus: ['Implementation, root-cause debugging, performance, and reliability', '代码实现、根因排查、性能与可靠性'],
+  martin: ['Code review, refactoring, architecture boundaries, and maintainability', '代码评审、重构、架构边界与可维护性'],
+  dieter: ['Minimal UI, design systems, and usability review', '极简界面、设计系统与可用性评审'],
+  ada: ['Algorithms, data structures, and formal modeling', '算法、数据结构与形式化建模'],
+  grace: ['Debugging, runtime behavior, and clear technical explanation', '调试、运行时行为与清晰技术解释'],
+  alice: ['Threat modeling, authorization boundaries, and input security', '威胁建模、授权边界与输入安全'],
+  ken: ['Unix systems, simple interfaces, and composable architecture', 'Unix 系统、简单接口与可组合架构'],
+  margaret: ['Mission-critical testing, failure handling, and release quality', '关键任务测试、故障处理与发布质量'],
+  shannon: ['Information theory, metrics, and signal extraction', '信息论、指标设计与信号提取'],
+  alan: ['Object models, system architecture, and future-facing design', '对象模型、系统架构与前瞻设计'],
+  norman: ['User research, cognitive load, and interaction design', '用户研究、认知负担与交互设计'],
+  kongzi: ['Ethics, social order, and long-term conduct', '伦理、社会秩序与长期行为准则'],
+  socrates: ['Assumption testing, precise questions, and logical clarity', '假设检验、精准追问与逻辑澄清'],
+  nietzsche: ['Values critique, hidden motives, and bold reframing', '价值批判、隐性动机与大胆重构问题'],
+  kahneman: ['Cognitive bias, decision quality, and experiment design', '认知偏差、决策质量与实验设计'],
+  jung: ['Archetypes, motivation, and narrative psychology', '原型、动机与叙事心理学'],
+  sunzi: ['Strategy, positioning, leverage, and conflict avoidance', '战略、定位、杠杆与避战'],
+  clausewitz: ['Strategic friction, uncertainty, and execution under pressure', '战略摩擦、不确定性与压力下执行'],
+  simaqian: ['Historical context, causality, and durable narratives', '历史语境、因果关系与长期叙事'],
+  harari: ['Macro trends, institutions, and long-horizon consequences', '宏观趋势、制度与长期影响'],
+  buffett: ['Business quality, valuation, and durable advantages', '企业质量、估值与持久竞争优势'],
+  munger: ['Mental models, incentives, and decision debiasing', '多元思维模型、激励与决策纠偏'],
+  dalio: ['Principles, feedback loops, and organizational systems', '原则、反馈回路与组织系统'],
+  bezos: ['Customer obsession, long-term bets, and operational mechanisms', '客户执念、长期投入与运营机制'],
+  drucker: ['Management, organizational focus, and measurable outcomes', '管理、组织聚焦与可衡量成果'],
+  luxun: ['Sharp criticism, cultural diagnosis, and concise writing', '尖锐批评、文化诊断与精炼写作'],
+  sudongpo: ['Elegant writing, broad perspective, and humane judgment', '优雅写作、开阔视角与人文判断'],
+  borges: ['Conceptual structures, nonlinear narrative, and intellectual play', '概念结构、非线性叙事与智性想象'],
+  einstein: ['First principles, thought experiments, and radical simplification', '第一性原理、思想实验与极致简化'],
+  kubrick: ['Visual storytelling, pacing, and exacting creative control', '视觉叙事、节奏与严格创作控制'],
+  miyazaki: ['World-building, emotional storytelling, and humane imagination', '世界构建、情感叙事与人文想象'],
+  omni: ['Requirement clarification, workflow routing, and delivery coordination', '需求澄清、流程路由与交付协调'],
+});
+
 const LEGACY_DEFAULT_VP_PERSONA_ZH = Object.freeze({
   steve: {
     roleZh: '产品战略家',
@@ -1873,10 +1938,13 @@ function localizeDefaultVpPersona(vp) {
   const personaZh = String(vp.personaZh || '').trim();
   const legacyPersonaEn = String(vp.legacyPersonaEn || '').trim();
   const legacyPersonaZh = String(legacyZh?.persona || '').trim();
+  const descriptions = DEFAULT_VP_DESCRIPTIONS[vp.vpId] || [];
 
   return {
     ...vp,
     roleZh: vp.roleZh || legacyZh?.roleZh || '',
+    description: String(vp.description || descriptions[0] || vp.role || '').trim(),
+    descriptionZh: String(vp.descriptionZh || descriptions[1] || vp.roleZh || legacyZh?.roleZh || descriptions[0] || vp.role || '').trim(),
     persona: localizedPersonaSections(personaEn, personaZh),
     personaEn,
     personaZh,
@@ -1946,7 +2014,7 @@ function libraryHasAnyVp(libDir) {
 }
 
 /**
- * Seed the 33 default VPs into `libDir` if and only if the library is empty.
+ * Seed the 34 default VPs into `libDir` if and only if the library is empty.
  *
  * Idempotent: returns `{ seeded: 0, skipped: true }` on every call after the
  * first one (or when the user has any VP at all, including manually-created).

package/yeaft/vp/seed-topup.js

@@ -3,8 +3,9 @@
  *
  * Problem: `seedDefaultVps` is first-run-only — once the library has any VP
  * in it, that function never runs again. When we expanded the default roster
- * from 12 to 33 (philosophy, psychology, strategy, history, investing,
- * business, writing, science, arts, Omni), existing installs would never see the
+ * beyond the original 12 (philosophy, psychology, strategy, history,
+ * investing, business, writing, science, arts, Omni, and later additions),
+ * existing installs would never see the
  * new VPs without either (a) the user manually deleting their library or
  * (b) a forced overwrite that would clobber their hand edits.
  *
@@ -15,7 +16,8 @@
  *      on disk, `createVp()` it. This keeps product-owned defaults such as
  *      Omni and the expanded role roster visible in session/member pickers.
  *
- *   2. **Backfill missing stock frontmatter** (`area`, `nameZh`, `roleZh`) on
+ *   2. **Backfill missing stock frontmatter** (`area`, `nameZh`, `description`,
+ *      `descriptionZh`, `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.
@@ -176,10 +178,11 @@ function insertFrontmatterLine(source, key, value) {
   const lines = yaml.split(/\r?\n/);
   const roleIdx = lines.findIndex(l => /^role:\s*/.test(l));
   // Quote the value when it contains characters YAML treats specially or
-  // non-ASCII bytes — the existing vp-crud writer does the same dance.
+  // non-ASCII bytes. Single quotes keep backslashes and double quotes literal;
+  // doubled apostrophes are reversed by vp-store's scalar parser.
   const needsQuote = /[:#"'\\\n]/.test(valTrim) || /[^\x20-\x7e]/.test(valTrim);
   const yamlVal = needsQuote
-    ? `"${valTrim.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+    ? `'${valTrim.replace(/'/g, "''")}'`
     : valTrim;
   const newLine = `${key}: ${yamlVal}`;
   if (roleIdx >= 0) {
@@ -216,6 +219,16 @@ export function insertNameZhLine(source, nameZh) {
   return insertFrontmatterLine(source, 'nameZh', nameZh);
 }
 
+/** Backfill `description:` into role.md frontmatter. */
+export function insertDescriptionLine(source, description) {
+  return insertFrontmatterLine(source, 'description', description);
+}
+
+/** Backfill `descriptionZh:` into role.md frontmatter. */
+export function insertDescriptionZhLine(source, descriptionZh) {
+  return insertFrontmatterLine(source, 'descriptionZh', descriptionZh);
+}
+
 /**
  * Backfill `roleZh:` into role.md frontmatter.
  *
@@ -272,6 +285,8 @@ function isObsoleteOmniAssistantBody(vp, body) {
  *   added: string[],
  *   areaBackfilled: string[],
  *   nameZhBackfilled: string[],
+ *   descriptionBackfilled: string[],
+ *   descriptionZhBackfilled: string[],
  *   roleZhBackfilled: string[],
  *   personaBackfilled: string[],
  *   respectedDeletes: string[],
@@ -283,6 +298,8 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
   const added = [];
   const areaBackfilled = [];
   const nameZhBackfilled = [];
+  const descriptionBackfilled = [];
+  const descriptionZhBackfilled = [];
   const roleZhBackfilled = [];
   const personaBackfilled = [];
   const respectedDeletes = [];
@@ -294,7 +311,7 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
   // that case there's nothing to top up — seedDefaultVps will populate
   // everything. We still return cleanly.
   if (!existsSync(libDir)) {
-    return { added, areaBackfilled, nameZhBackfilled, roleZhBackfilled, personaBackfilled, respectedDeletes, skippedExisting, errors };
+    return { added, areaBackfilled, nameZhBackfilled, descriptionBackfilled, descriptionZhBackfilled, roleZhBackfilled, personaBackfilled, respectedDeletes, skippedExisting, errors };
   }
 
   let versions = readSeedVersions(libDir);
@@ -373,6 +390,44 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
           });
         }
       }
+      if (vp.description) {
+        try {
+          const src = readRole();
+          if (src != null) {
+            const patched = insertDescriptionLine(src, vp.description);
+            if (patched != null && patched !== src) {
+              writeFileSync(rolePath, patched, 'utf-8');
+              currentSrc = patched;
+              descriptionBackfilled.push(vpId);
+            }
+          }
+        } catch (err) {
+          errors.push({
+            vpId,
+            code: 'description_backfill_failed',
+            message: String(err?.message || err),
+          });
+        }
+      }
+      if (vp.descriptionZh) {
+        try {
+          const src = readRole();
+          if (src != null) {
+            const patched = insertDescriptionZhLine(src, vp.descriptionZh);
+            if (patched != null && patched !== src) {
+              writeFileSync(rolePath, patched, 'utf-8');
+              currentSrc = patched;
+              descriptionZhBackfilled.push(vpId);
+            }
+          }
+        } catch (err) {
+          errors.push({
+            vpId,
+            code: 'description_zh_backfill_failed',
+            message: String(err?.message || err),
+          });
+        }
+      }
       if (vp.roleZh) {
         try {
           const src = readRole();
@@ -452,5 +507,5 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
   }
 
   writeSeedVersions(libDir, versions);
-  return { added, areaBackfilled, nameZhBackfilled, roleZhBackfilled, personaBackfilled, respectedDeletes, skippedExisting, errors };
+  return { added, areaBackfilled, nameZhBackfilled, descriptionBackfilled, descriptionZhBackfilled, roleZhBackfilled, personaBackfilled, respectedDeletes, skippedExisting, errors };
 }

package/yeaft/vp/stock-ids.js

@@ -25,7 +25,7 @@
 
 const STOCK_VP_ID_LIST = Object.freeze([
   // engineering
-  'steve', 'linus', 'martin', 'dieter', 'ada', 'grace', 'alice', 'ken',
+  'steve', 'linus', 'martin', 'anders', 'dieter', 'ada', 'grace', 'alice', 'ken',
   'margaret', 'shannon', 'alan', 'norman',
   // philosophy / psychology
   'kongzi', 'socrates', 'nietzsche', 'kahneman', 'jung',

package/yeaft/vp/vp-bridge.js

@@ -8,6 +8,7 @@
  *
  * Per ruling §2 (D2):
  *   • subtitle  → agent emits `vp.role` directly
+ *   • capability descriptions → additive localized wire fields
  *   • personaHash → agent emits `vp.personaHash`
  *   • color / avatar → web-derived, NOT emitted here
  *
@@ -194,8 +195,8 @@ function ensureLoader(registry = defaultRegistry, options = {}) {
  * Serialise a VP (entity layer shape) to the wire-format the web layer
  * expects (spec §2.1). Pure; no IO.
  *
- * @param {{id:string,name:string,role:string,nameZh?:string,aliases?:string[],traits?:string[],modelHint?:string,personaHash?:string}} vp
- * @returns {{vpId:string,displayName:string,displayNameZh:string,aliases:string[],subtitle:string,role:string,traits:string[],modelHint:?string,personaHash:?string,isStock:boolean}}
+ * @param {{id:string,name:string,role:string,nameZh?:string,description?:string,descriptionZh?:string,roleZh?:string,aliases?:string[],traits?:string[],modelHint?:string,personaHash?:string}} vp
+ * @returns {{vpId:string,displayName:string,displayNameZh:string,description:string,descriptionZh:string,aliases:string[],subtitle:string,role:string,roleZh:string,traits:string[],modelHint:?string,personaHash:?string,isStock:boolean}}
  */
 export function serializeVpForWire(vp) {
   return {
@@ -204,8 +205,11 @@ export function serializeVpForWire(vp) {
     // task-fix (5-bugs): carry bilingual name + aliases (incl. pinyin) to
     // the frontend so @ mention matching + localised rendering work.
     displayNameZh: typeof vp.nameZh === 'string' ? vp.nameZh : '',
+    description: typeof vp.description === 'string' ? vp.description : '',
+    descriptionZh: typeof vp.descriptionZh === 'string' ? vp.descriptionZh : '',
     aliases: Array.isArray(vp.aliases) ? vp.aliases.slice() : [],
     role: vp.role || '',
+    roleZh: typeof vp.roleZh === 'string' ? vp.roleZh : '',
     subtitle: vp.role || '',
     traits: Array.isArray(vp.traits) ? vp.traits.slice() : [],
     modelHint: vp.modelHint ?? null,