@yeaft/webchat-agent 0.1.934 → 0.1.936

package/connection/message-router.js

@@ -37,7 +37,7 @@ import { handleRestartAgent, handleUpgradeAgent } from './upgrade.js';
 import { loadMcpServers, updateMcpConfig } from '../mcp.js';
 import { getLlmConfig, updateLlmConfig, getYeaftSettings, updateYeaftSettings, getSearchSettings, updateSearchSettings, fetchTavilyUsage } from '../yeaft/config-api.js';
 import { fetchModelsDev } from '../yeaft/llm/models-dev.js';
-import { handleYeaftSessionSend, handleYeaftModeSwitch, handleYeaftModelSwitch, resetYeaftSession, handleYeaftLoadHistory, handleYeaftLoadMoreHistory, handleYeaftAbortThread, handleYeaftAbortAll, handleYeaftAbortTurn, handleYeaftVpSubscribe, handleYeaftVpCreate, handleYeaftVpUpdate, handleYeaftVpDelete, handleYeaftVpRead, handleYeaftListSessions, handleYeaftCreateSession, handleYeaftRenameSession, handleYeaftUpdateSession, handleYeaftUpdateSessionConfig, handleYeaftArchiveSession, handleYeaftDeleteSession, handleYeaftSessionAddMember, handleYeaftSessionRemoveMember, handleYeaftSessionSetDefaultVp, handleYeaftScanWorkdirSessions, handleYeaftRestoreSession, handleYeaftDreamTrigger, handleYeaftFetchToolStats, handleYeaftFetchDebugHistory, broadcastLanguageChange, broadcastYeaftSessionSnapshotEager } from '../yeaft/web-bridge.js';
+import { handleYeaftSessionSend, handleYeaftModeSwitch, handleYeaftModelSwitch, resetYeaftSession, handleYeaftLoadHistory, handleYeaftLoadMoreHistory, handleYeaftAbortThread, handleYeaftAbortAll, handleYeaftAbortTurn, handleYeaftVpSubscribe, handleYeaftVpCreate, handleYeaftVpUpdate, handleYeaftVpDelete, handleYeaftVpRead, handleYeaftListSessions, handleYeaftCreateSession, handleYeaftRenameSession, handleYeaftUpdateSession, handleYeaftUpdateSessionConfig, handleYeaftArchiveSession, handleYeaftDeleteSession, handleYeaftSessionAddMember, handleYeaftSessionRemoveMember, handleYeaftSessionSetDefaultVp, handleYeaftScanWorkdirSessions, handleYeaftRestoreSession, handleYeaftDreamTrigger, handleYeaftFetchToolStats, handleYeaftFetchDebugHistory, handleYeaftMcpList, handleYeaftMcpAdd, handleYeaftMcpRemove, handleYeaftMcpReload, broadcastLanguageChange, broadcastYeaftSessionSnapshotEager } from '../yeaft/web-bridge.js';
 import { startYeaftStatusRefresh, refreshYeaftStatus } from '../yeaft/status-cache.js';
 
 export async function handleMessage(msg) {
@@ -441,6 +441,27 @@ export async function handleMessage(msg) {
       break;
     }
 
+    // Yeaft MCP CRUD (Claude-Code-style Settings → MCP tab).
+    // Each wire op mutates ~/.yeaft/config.json `mcpServers` AND, when
+    // the session is alive, mirrors the change into `mcpManager` + hot-
+    // swaps the live `toolRegistry`. See handlers in web-bridge.js for
+    // the broadcast contract (`yeaft_mcp_updated`).
+    case 'yeaft_mcp_list':
+      handleYeaftMcpList(msg);
+      break;
+
+    case 'yeaft_mcp_add':
+      await handleYeaftMcpAdd(msg);
+      break;
+
+    case 'yeaft_mcp_remove':
+      await handleYeaftMcpRemove(msg);
+      break;
+
+    case 'yeaft_mcp_reload':
+      await handleYeaftMcpReload(msg);
+      break;
+
     // Yeaft — single conversation backed by the default session.
     //
     // Wire-alias scope: the `yeaft_group_chat` op (and its envelope

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.934",
+  "version": "0.1.936",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/yeaft/config-api.js

@@ -376,3 +376,195 @@ export async function fetchTavilyUsage(dir) {
   }
 }
 
+// ─── MCP server config (mcpServers array in config.json) ──
+
+/**
+ * Server-name regex: lowercase letters, digits, underscore, dash. Matches
+ * what Claude Code accepts so config files are portable. Single source of
+ * truth for both add/update/remove validation.
+ */
+const MCP_NAME_RE = /^[a-z0-9_-]+$/;
+
+/**
+ * Normalise one MCP server entry on read. The on-disk shape that the
+ * MCPManager understands is `{ name, command, args?, env? }`. This pass
+ * strips unknown / non-string keys, coerces args to an array of strings,
+ * and forces env to a plain {string→string} object so the UI doesn't
+ * crash on a malformed handwritten config.
+ *
+ * @param {unknown} entry
+ * @returns {{ name: string, command: string, args: string[], env: Record<string,string> } | null}
+ */
+function normaliseMcpServer(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const e = /** @type {any} */ (entry);
+  const name = typeof e.name === 'string' ? e.name.trim() : '';
+  const command = typeof e.command === 'string' ? e.command.trim() : '';
+  if (!name || !command) return null;
+  const args = Array.isArray(e.args)
+    ? e.args.filter(a => typeof a === 'string')
+    : [];
+  /** @type {Record<string,string>} */
+  // Use a null-prototype object so a malicious config entry can't poison
+  // future lookups via `__proto__` / `constructor` / `prototype` keys. Even
+  // with the explicit skip list below, the null-prototype is the right
+  // baseline: env maps are plain key/value bags, they have no business
+  // owning prototype methods.
+  const env = Object.create(null);
+  if (e.env && typeof e.env === 'object' && !Array.isArray(e.env)) {
+    for (const [k, v] of Object.entries(e.env)) {
+      // Skip dangerous keys that would let attacker-controlled config
+      // pollute Object.prototype if env were ever spread / merged
+      // somewhere that doesn't expect a null-proto map.
+      if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
+      if (typeof k === 'string' && typeof v === 'string') env[k] = v;
+    }
+  }
+  return { name, command, args, env };
+}
+
+/**
+ * Validate a server config for add/update. Returns null on success or a
+ * string error suitable for forwarding to the UI.
+ *
+ * @param {unknown} entry
+ * @returns {string|null}
+ */
+function validateMcpServer(entry) {
+  if (!entry || typeof entry !== 'object') return 'server payload required';
+  const e = /** @type {any} */ (entry);
+  if (typeof e.name !== 'string' || !MCP_NAME_RE.test(e.name)) {
+    return 'server name must match /^[a-z0-9_-]+$/';
+  }
+  if (typeof e.command !== 'string' || !e.command.trim()) {
+    return 'server command is required';
+  }
+  if (e.args !== undefined && (!Array.isArray(e.args) || !e.args.every(a => typeof a === 'string'))) {
+    return 'server args must be an array of strings';
+  }
+  if (e.env !== undefined && (typeof e.env !== 'object' || e.env === null || Array.isArray(e.env))) {
+    return 'server env must be an object of string→string';
+  }
+  if (e.env && typeof e.env === 'object') {
+    for (const [k, v] of Object.entries(e.env)) {
+      if (typeof k !== 'string' || typeof v !== 'string') {
+        return 'server env entries must all be strings';
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Read existing config.json (silently start fresh on missing / corrupt).
+ * Internal helper used by the MCP CRUD trio to share one parse path.
+ *
+ * @param {string} configPath
+ * @returns {object}
+ */
+function readConfigJson(configPath) {
+  if (!existsSync(configPath)) return {};
+  try {
+    const raw = readFileSync(configPath, 'utf8');
+    const json = JSON.parse(raw);
+    return (json && typeof json === 'object') ? json : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * List MCP servers currently saved in config.json. Returns an array — empty
+ * when none configured. Each entry is the normalised on-disk shape, NOT
+ * the runtime status (which lives on `mcpManager.status()`).
+ *
+ * @param {string} [dir]
+ * @returns {{ servers: Array<{ name: string, command: string, args: string[], env: Record<string,string> }> } | { error: string }}
+ */
+export function listMcpServers(dir) {
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  const configPath = join(root, 'config.json');
+  try {
+    const json = readConfigJson(configPath);
+    const raw = Array.isArray(json.mcpServers) ? json.mcpServers : [];
+    const servers = raw.map(normaliseMcpServer).filter(Boolean);
+    return { servers };
+  } catch (e) {
+    return { error: `Failed to read config.json: ${e.message}` };
+  }
+}
+
+/**
+ * Add or update an MCP server config entry. Match is by `name`. Returns
+ * the post-update list of servers (same shape as `listMcpServers`) plus
+ * the entry that was just written, so callers can pass it directly into
+ * `mcpManager.connect()` without re-reading the file.
+ *
+ * @param {{ name: string, command: string, args?: string[], env?: Record<string,string> }} server
+ * @param {string} [dir]
+ * @returns {{ servers: Array<object>, server: object } | { error: string }}
+ */
+export function upsertMcpServer(server, dir) {
+  const err = validateMcpServer(server);
+  if (err) return { error: err };
+
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  const configPath = join(root, 'config.json');
+  const existing = readConfigJson(configPath);
+  const list = Array.isArray(existing.mcpServers) ? existing.mcpServers.slice() : [];
+
+  const normalised = normaliseMcpServer(server);
+  if (!normalised) return { error: 'invalid server payload' };
+
+  const idx = list.findIndex(s => s && typeof s === 'object' && s.name === normalised.name);
+  if (idx >= 0) {
+    list[idx] = normalised;
+  } else {
+    list.push(normalised);
+  }
+  existing.mcpServers = list;
+
+  try {
+    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+  } catch (e) {
+    return { error: `Failed to write config.json: ${e.message}` };
+  }
+
+  return { servers: list.map(normaliseMcpServer).filter(Boolean), server: normalised };
+}
+
+/**
+ * Remove the MCP server config entry with the given name. Idempotent —
+ * removing a non-existent name returns the unchanged list with
+ * `removed: false`. This lets the UI safely call delete after a
+ * concurrent change without surfacing a spurious error.
+ *
+ * @param {string} name
+ * @param {string} [dir]
+ * @returns {{ servers: Array<object>, removed: boolean } | { error: string }}
+ */
+export function removeMcpServer(name, dir) {
+  if (typeof name !== 'string' || !name.trim()) {
+    return { error: 'name required' };
+  }
+  // Trim once for the comparison too — without this, "  github  " from the
+  // wire would silently fail to delete "github" on disk because we'd be
+  // matching against the padded string.
+  const target = name.trim();
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  const configPath = join(root, 'config.json');
+  const existing = readConfigJson(configPath);
+  const list = Array.isArray(existing.mcpServers) ? existing.mcpServers.slice() : [];
+  const next = list.filter(s => !(s && typeof s === 'object' && s.name === target));
+  const removed = next.length !== list.length;
+  existing.mcpServers = next;
+
+  try {
+    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+  } catch (e) {
+    return { error: `Failed to write config.json: ${e.message}` };
+  }
+
+  return { servers: next.map(normaliseMcpServer).filter(Boolean), removed };
+}
+

package/yeaft/conversation/persist.js

@@ -1064,7 +1064,18 @@ export class ConversationStore {
 
     const startIdx = indexOfNthTurnFromEnd(visible, turnsLimit);
     const start = startIdx === -1 ? 0 : startIdx;
-    const messages = pairSanitize(visible.slice(start));
+    // Visible history is for UI replay, not LLM context. The visible loader
+    // already excludes tool-result rows, so running pairSanitize here can
+    // incorrectly treat tool-using assistant replies as orphaned tool arcs and
+    // drop/trim VP messages. Strip tool-call metadata instead and keep the
+    // user-visible assistant text for the conversation pane.
+    const messages = visible.slice(start).map(m => {
+      if (m && m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
+        const { toolCalls, ...rest } = m;
+        return rest;
+      }
+      return m;
+    });
     const oldestSeq = messages.length ? parseSeqFromId(messages[0].id) : null;
     const firstVisibleSeq = parseSeqFromId(visible[0].id);
     const hasMore = messages.length > 0

package/yeaft/engine.js

@@ -2219,6 +2219,7 @@ export class Engine {
             // history replay can re-stamp them on reload.
             sessionId,
             threadId,
+            vpId: this.#vpId,
             // Multi-VP fan-out (history-dedup): skip the user-row append
             // in stop-hooks when the orchestrator already wrote it once
             // for this turn. The hook still persists assistant + tool

package/yeaft/init.js

@@ -5,14 +5,16 @@
  * Creates default config.md, MEMORY.md, and chat/index.md if missing.
  */
 
-import { existsSync, mkdirSync, writeFileSync, accessSync, constants } from 'fs';
-import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, accessSync, constants } from 'fs';
+import { join, dirname } from 'path';
 import { homedir } from 'os';
+import { createHash } from 'crypto';
 // NOTE: migrateSessions runs at the end of initYeaftDir(). It collapses
 // legacy groups/ + chats/ + memory/{group,chat}/ into the unified sessions/
 // layout AND rewrites pre-rename per-message frontmatter (groupId → sessionId).
 // Idempotent via the `.yeaft-migration.done` sentinel file.
 import { migrateSessions } from './migrate/sessions.js';
+import { bundledYeaftSkillsDir } from './skills.js';
 
 /**
  * Check if an error is a permission error (EACCES or EPERM).
@@ -157,7 +159,7 @@ This file tracks one Yeaft message-history mode.
  * Initialize the Yeaft data directory structure.
  *
  * @param {string} [dir] — Root directory path. Defaults to ~/.yeaft/
- * @returns {{ dir: string, created: string[], writable: boolean, warnings: string[] }} — The root dir, list of created paths, writability status, and any warnings
+ * @returns {{ dir: string, created: string[], writable: boolean, warnings: string[], seededSkills?: number }} — The root dir, list of created paths, writability status, any warnings, and how many bundled skills were seeded
  */
 export function initYeaftDir(dir) {
   const root = dir || DEFAULT_YEAFT_DIR;
@@ -215,6 +217,22 @@ export function initYeaftDir(dir) {
     created.push(mcpExamplePath);
   }
 
+  // Seed bundled yeaft-skills into the user dir (Claude-Code-style). After
+  // every successful boot the user dir mirrors the bundled set (modulo files
+  // the user has hand-edited — those are detected via the manifest sha and
+  // left alone). New bundled skills appear automatically; bundled-version
+  // upgrades flow through; user edits are never clobbered.
+  let seededSkills = 0;
+  try {
+    const seedResult = seedBundledSkills(join(root, 'skills'), warnings);
+    seededSkills = seedResult.copied;
+    if (seedResult.copied > 0 || seedResult.updated > 0) {
+      console.log(`[yeaft] seeded ${seedResult.copied} new + ${seedResult.updated} updated bundled skills (${seedResult.preserved} user edits preserved)`);
+    }
+  } catch (err) {
+    warnings.push(`Failed to seed bundled skills: ${err?.message || err}`);
+  }
+
   // NOTE: sessions migration runs synchronously here. It MUST complete before
   // any LLM request fires, because step 7 (per-message frontmatter rewrite)
   // is what lets the persist.js parser drop the legacy `groupId:` row alias.
@@ -230,5 +248,191 @@ export function initYeaftDir(dir) {
     console.warn(`[yeaft] session migration failed (continuing): ${err?.message || err}`);
   }
 
-  return { dir: root, created, writable, warnings };
+  return { dir: root, created, writable, warnings, seededSkills };
+}
+
+// ─── Bundled skills seeding ───────────────────────────────
+
+/**
+ * Filename inside the user skills directory that tracks which files we
+ * previously installed from the bundled package, keyed by their sha256.
+ * On re-seed, files whose CURRENT on-disk content matches a manifest entry
+ * are considered "still bundled" and can be safely overwritten if the
+ * bundled version has changed. Files whose sha doesn't match the manifest
+ * are treated as user-modified and left alone — Claude Code uses the same
+ * "user edits win" rule.
+ */
+const SEED_MANIFEST_FILE = '.bundled-manifest.json';
+
+/**
+ * sha256 of a string, hex encoded.
+ * @param {string} content
+ * @returns {string}
+ */
+function sha256(content) {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+/**
+ * Recursively walk a directory and yield relative file paths.
+ * @param {string} root
+ * @param {string} [sub]
+ * @returns {string[]}
+ */
+function walkFiles(root, sub = '') {
+  const dir = sub ? join(root, sub) : root;
+  if (!existsSync(dir)) return [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const rel = sub ? join(sub, entry.name) : entry.name;
+    if (entry.isFile()) {
+      out.push(rel);
+    } else if (entry.isDirectory()) {
+      out.push(...walkFiles(root, rel));
+    }
+  }
+  return out;
+}
+
+/**
+ * Read a tiny JSON file and return parsed value, or `{}` on missing/broken.
+ * @param {string} filePath
+ * @returns {Record<string, string>}
+ */
+function readManifest(filePath) {
+  try {
+    if (!existsSync(filePath)) return {};
+    const raw = readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Seed bundled `yeaft-skills` into a user skills directory.
+ *
+ * Behavior (Claude-Code style):
+ *   - Every file under the bundled dir is mirrored to the user dir at the
+ *     same relative path.
+ *   - If target doesn't exist → copy verbatim, record sha in manifest.
+ *   - If target exists AND its current sha matches the manifest entry → the
+ *     file is "still the version we installed", so overwrite with the new
+ *     bundled version (= picks up a bundled upgrade) and refresh the sha.
+ *   - If target exists AND its sha differs from manifest → the user edited
+ *     it. Leave it alone. Do NOT touch the manifest (so future runs still
+ *     see the divergence).
+ *   - Manifest is per-relative-path → sha256 of the BUNDLED version we last
+ *     installed at that path.
+ *
+ * Re-runs are idempotent: stable state on disk + manifest produces no
+ * writes on the second pass.
+ *
+ * @param {string} userSkillsDir — absolute path to user-tier skills dir (e.g. ~/.yeaft/skills)
+ * @param {string[]} warnings    — array to push warnings into
+ * @returns {{ copied: number, updated: number, preserved: number, skipped: number }}
+ */
+export function seedBundledSkills(userSkillsDir, warnings = []) {
+  const bundled = bundledYeaftSkillsDir();
+  if (!bundled) {
+    return { copied: 0, updated: 0, preserved: 0, skipped: 0 };
+  }
+
+  // Ensure user dir exists (no-op if already there from SUBDIRS).
+  if (!existsSync(userSkillsDir)) {
+    if (!safeMkdir(userSkillsDir, warnings)) {
+      return { copied: 0, updated: 0, preserved: 0, skipped: 0 };
+    }
+  }
+
+  const manifestPath = join(userSkillsDir, SEED_MANIFEST_FILE);
+  const manifest = readManifest(manifestPath);
+  const nextManifest = { ...manifest };
+
+  let copied = 0;
+  let updated = 0;
+  let preserved = 0;
+  let skipped = 0;
+
+  const files = walkFiles(bundled);
+  for (const rel of files) {
+    const sourcePath = join(bundled, rel);
+    const targetPath = join(userSkillsDir, rel);
+
+    let bundledContent;
+    try {
+      bundledContent = readFileSync(sourcePath, 'utf8');
+    } catch (err) {
+      warnings.push(`Cannot read bundled skill ${rel}: ${err.message}`);
+      skipped += 1;
+      continue;
+    }
+    const bundledSha = sha256(bundledContent);
+
+    if (!existsSync(targetPath)) {
+      // First-time install — copy.
+      if (!safeMkdir(dirname(targetPath), warnings)) {
+        skipped += 1;
+        continue;
+      }
+      safeWriteFile(targetPath, bundledContent, warnings);
+      if (existsSync(targetPath)) {
+        nextManifest[rel] = bundledSha;
+        copied += 1;
+      } else {
+        skipped += 1;
+      }
+      continue;
+    }
+
+    // Target exists. Read it, sha it, decide.
+    let currentContent;
+    try {
+      currentContent = readFileSync(targetPath, 'utf8');
+    } catch (err) {
+      warnings.push(`Cannot read existing skill ${rel}: ${err.message}`);
+      skipped += 1;
+      continue;
+    }
+    const currentSha = sha256(currentContent);
+
+    if (currentSha === bundledSha) {
+      // Already up to date — no write, but make sure the manifest knows.
+      nextManifest[rel] = bundledSha;
+      continue;
+    }
+
+    const manifestSha = manifest[rel];
+    if (manifestSha && manifestSha === currentSha) {
+      // The on-disk file is the version WE installed; user hasn't touched
+      // it. The bundled version has changed (we passed the previous
+      // currentSha === bundledSha check), so apply the upgrade.
+      safeWriteFile(targetPath, bundledContent, warnings);
+      nextManifest[rel] = bundledSha;
+      updated += 1;
+      continue;
+    }
+
+    // Either: (a) no manifest entry (= file pre-existed before we tracked
+    // it) or (b) manifest sha doesn't match current sha (= user edited).
+    // Either way the file is user-owned now — leave it alone, don't
+    // overwrite, don't touch the manifest (so divergence stays visible).
+    preserved += 1;
+  }
+
+  // Write manifest only if it actually changed (avoids needless disk
+  // writes when nothing new happened).
+  const manifestChanged = JSON.stringify(manifest) !== JSON.stringify(nextManifest);
+  if (manifestChanged) {
+    safeWriteFile(manifestPath, JSON.stringify(nextManifest, null, 2) + '\n', warnings);
+  }
+
+  return { copied, updated, preserved, skipped };
 }

package/yeaft/session.js

@@ -21,6 +21,7 @@ import { ConversationStore, setDefaultRecentTurnsLimit } from './conversation/pe
 import { SkillManager, createSkillManager } from './skills.js';
 import { MCPManager } from './mcp.js';
 import { createFullRegistry } from './tools/index.js';
+import { buildMcpFlattenedTools } from './tools/mcp-tools.js';
 import { Engine } from './engine.js';
 import { Compactor } from './compact/compactor.js';
 import { resolveContextWindow } from './models.js';
@@ -369,10 +370,19 @@ export async function loadSession(options = {}) {
   // ─── 6. Load skills ────────────────────────────────────
   let skillManager;
   if (skipSkills) {
-    skillManager = new SkillManager(yeaftDir);
+    // Pass the literal user-tier dir (matches the normal branch's tier 2)
+    // so any save/remove calls land in the same place users expect. New
+    // `SkillManager` API takes literal scan dirs — no auto-suffix of /skills.
+    skillManager = new SkillManager(join(yeaftDir, 'skills'));
     // Don't call .load() — empty skill manager
   } else {
-    skillManager = createSkillManager(yeaftDir);
+    // Pass the agent's current working directory as the project tier root.
+    // Per-session/per-group workdirs override at tool-execution time via
+    // ToolContext.cwd; for the SYSTEM-PROMPT skill set we just use the
+    // agent process cwd, which is the common case when an agent is
+    // launched inside a project the user wants project-tier skills for.
+    const projectTierRoot = process.cwd();
+    skillManager = createSkillManager(yeaftDir, projectTierRoot);
   }
 
   // ─── 7. Connect MCP servers ────────────────────────────
@@ -392,6 +402,20 @@ export async function loadSession(options = {}) {
     toolRegistry.register(tool);
   }
 
+  // Register flattened MCP tools (one ToolDef per MCP tool, named
+  // `mcp__<server>__<tool>` per Claude Code's convention). This replaces
+  // the legacy mcp_list_tools / mcp_call_tool meta-tools — the LLM now
+  // calls MCP tools directly in a single turn, no discovery dance.
+  // Re-built and re-registered on every connect/disconnect via
+  // `toolRegistry.replaceMcpTools(mcpManager, buildMcpFlattenedTools)`
+  // which is invoked from the MCP web-bridge handlers.
+  if (mcpManager.hasServers) {
+    const flattened = buildMcpFlattenedTools(mcpManager);
+    for (const tool of flattened) {
+      toolRegistry.register(tool);
+    }
+  }
+
   // ─── 9. Create engine (wires everything) ───────────────
   // Tool-call usage statistics: persisted to <yeaftDir>/stats/tool-usage.json.
   // Loaded synchronously at boot so the first turn already sees prior counts.