@yeaft/webchat-agent 0.1.934 → 0.1.936

package/yeaft/skills.js

@@ -19,12 +19,32 @@
  * - keywords: array of match keywords (alternative to trigger)
  * - platforms: array of ["macos", "linux", "windows"]
  *
+ * ─── Layered loading (Claude-Code-style) ─────────────────
+ *
+ * A `SkillManager` can scan multiple directories in priority order — later
+ * directories OVERRIDE earlier ones for skills with the same `name`. This
+ * mirrors Claude Code's plugin → user → project layering and lets a user
+ * customise a bundled skill without touching the bundled file.
+ *
+ * The standard tier order set up by `createSkillManager` is:
+ *
+ *   tier 1 (bundled): wherever yeaft-skills is installed on disk — typically
+ *           ~/.claude/skills/yeaft-skills/skills/. Read-only — `save()` and
+ *           `remove()` never target this tier.
+ *   tier 2 (user):    <yeaftDir>/skills (e.g. ~/.yeaft/skills). User edits
+ *           land here. `save()` writes here. `init.js` seeds it from tier 1
+ *           on first boot so users start with the full bundled set.
+ *   tier 3 (project): <workDir>/.yeaft/skills (if provided). Highest
+ *           priority — a project can pin a skill version without affecting
+ *           the user's other projects.
+ *
  * Reference: yeaft-yeaft-design.md §8, yeaft-yeaft-core-systems.md
  */
 
 import { existsSync, readFileSync, readdirSync, writeFileSync, unlinkSync, mkdirSync, statSync } from 'fs';
-import { join, basename, relative, dirname, sep } from 'path';
-import { platform } from 'os';
+import { join, basename, sep, dirname, resolve } from 'path';
+import { platform, homedir } from 'os';
+import { fileURLToPath } from 'url';
 
 // ─── Platform Matching ────────────────────────────────────
 
@@ -61,6 +81,7 @@ export function matchesPlatform(platforms) {
  * @property {string} content — full skill instructions (markdown body)
  * @property {string} _source — 'file' | 'directory'
  * @property {string} _path — full path to skill file or directory
+ * @property {string} [_tier] — 'bundled' | 'user' | 'project' — origin tier this skill was loaded from
  * @property {string[]} [_references] — filenames in references/ dir
  * @property {string[]} [_templates] — filenames in templates/ dir
  */
@@ -316,48 +337,103 @@ function matchKeywords(keywords, prompt) {
 /**
  * SkillManager — loads, indexes, and queries skills.
  * Supports both single-file and directory-based skills.
+ *
+ * Layered loading: pass an array of directories (lowest priority → highest).
+ * Skills with the same `name` in a later directory OVERRIDE earlier entries.
+ * The user-writable tier (where `save()` / `remove()` operate) is configured
+ * via the `userDir` option and must match one of the entries in `dirs` —
+ * if it isn't given, the last entry in `dirs` is used as the user tier.
  */
 export class SkillManager {
   /** @type {Map<string, Skill>} */
   #skills = new Map();
 
+  /** @type {string[]} */
+  #skillsDirs;
+
   /** @type {string} */
-  #skillsDir;
+  #userDir;
+
+  /** @type {Map<string, string>} — dir path → tier label */
+  #tierByDir;
 
   /**
-   * @param {string} yeaftDir — Yeaft root directory (e.g. ~/.yeaft)
+   * @param {string | string[]} dirs — single directory (back-compat) or array of
+   *   directories in priority order (lowest → highest). Falsy entries are
+   *   filtered out so callers can write `[bundled, user, projectOrNull]`.
+   * @param {{ userDir?: string, tierByDir?: Record<string, string> }} [opts]
+   *   userDir: directory where `save()` and `remove()` write. Defaults to the
+   *     last entry in `dirs` (typical case: user dir is highest priority that
+   *     isn't a per-project layer).
+   *   tierByDir: optional label map — dir path → 'bundled' | 'user' | 'project'.
+   *     Decorates each discovered Skill with `_tier` for diagnostics (Settings
+   *     UI uses this to show "where this skill came from").
    */
-  constructor(yeaftDir) {
-    this.#skillsDir = join(yeaftDir, 'skills');
+  constructor(dirs, opts = {}) {
+    const list = Array.isArray(dirs)
+      ? dirs.filter(d => typeof d === 'string' && d.length > 0)
+      : (typeof dirs === 'string' && dirs.length > 0 ? [dirs] : []);
+    this.#skillsDirs = list;
+    // Default user-writable tier: explicit opt → last array entry → first
+    // entry → empty string. Empty string disables write attempts but the
+    // manager still loads.
+    this.#userDir = (opts && typeof opts.userDir === 'string' && opts.userDir.length > 0)
+      ? opts.userDir
+      : (list.length > 0 ? list[list.length - 1] : '');
+    this.#tierByDir = new Map();
+    if (opts && opts.tierByDir && typeof opts.tierByDir === 'object') {
+      for (const [d, tier] of Object.entries(opts.tierByDir)) {
+        if (typeof d === 'string' && typeof tier === 'string') {
+          this.#tierByDir.set(d, tier);
+        }
+      }
+    }
   }
 
-  /** The skills root directory path. */
+  /** The user-writable skills directory (save/remove target). */
   get skillsDir() {
-    return this.#skillsDir;
+    return this.#userDir;
+  }
+
+  /** All directories scanned, in priority order (lowest → highest). */
+  get skillsDirs() {
+    return [...this.#skillsDirs];
   }
 
   /**
-   * Load all skills from the skills directory (recursive).
+   * Load all skills from all configured directories.
+   *
+   * Lower-priority directories load first; later (higher-priority) entries
+   * with the same skill `name` overwrite earlier ones. Each loaded skill is
+   * tagged with `_tier` (from the constructor's `tierByDir` map, or the dir
+   * basename as fallback) so consumers can show provenance.
    *
    * @returns {{ loaded: number, errors: string[] }}
    */
   load() {
     this.#skills.clear();
+    const allErrors = [];
 
-    if (!existsSync(this.#skillsDir)) {
+    if (this.#skillsDirs.length === 0) {
       return { loaded: 0, errors: [] };
     }
 
-    const { skills, errors } = discoverSkills(this.#skillsDir);
-
-    for (const skill of skills) {
-      // Platform filtering at load time
-      if (matchesPlatform(skill.platforms)) {
+    for (const dir of this.#skillsDirs) {
+      if (!existsSync(dir)) continue;
+      const { skills, errors } = discoverSkills(dir);
+      const tier = this.#tierByDir.get(dir) || basename(dir);
+      for (const skill of skills) {
+        // Platform filtering at load time
+        if (!matchesPlatform(skill.platforms)) continue;
+        skill._tier = tier;
+        // Later (higher-priority) tier overrides earlier entries with the
+        // same name — this is the layered-load contract.
         this.#skills.set(skill.name, skill);
       }
+      allErrors.push(...errors);
     }
 
-    return { loaded: this.#skills.size, errors };
+    return { loaded: this.#skills.size, errors: allErrors };
   }
 
   /**
@@ -390,7 +466,7 @@ export class SkillManager {
    * surfaced for historic YAML compatibility.
    *
    * @param {string} [_mode] — deprecated, ignored
-   * @returns {Array<{ name: string, description: string, trigger: string, mode: string, category?: string, platforms?: string[], keywords?: string[], source: string, hasReferences: boolean, hasTemplates: boolean }>}
+   * @returns {Array<{ name: string, description: string, trigger: string, mode: string, category?: string, platforms?: string[], keywords?: string[], source: string, tier?: string, hasReferences: boolean, hasTemplates: boolean }>}
    */
   list(_mode) {
     const skills = [...this.#skills.values()];
@@ -404,6 +480,7 @@ export class SkillManager {
       platforms: s.platforms || undefined,
       keywords: s.keywords || undefined,
       source: s._source,
+      tier: s._tier || undefined,
       hasReferences: (s._references && s._references.length > 0) || false,
       hasTemplates: (s._templates && s._templates.length > 0) || false,
     }));
@@ -428,10 +505,13 @@ export class SkillManager {
 
     // Read a specific linked file if requested
     if (filePath && skill._source === 'directory') {
-      const fullPath = join(skill._path, filePath);
-      // Security: ensure path doesn't escape skill directory
-      const resolved = join(skill._path, filePath);
-      if (!resolved.startsWith(skill._path)) {
+      // Security: resolve both ends to absolute paths and require fullPath to
+      // sit under the skill root (separator-anchored so /foo-evil isn't seen
+      // as a child of /foo). `path.join` alone collapses `..` but does not
+      // detect symlink-escapes or absolute-path overrides.
+      const fullPath = resolve(skill._path, filePath);
+      const root = resolve(skill._path) + sep;
+      if (fullPath !== resolve(skill._path) && !fullPath.startsWith(root)) {
         result.linkedContent = 'Error: path traversal not allowed';
       } else if (existsSync(fullPath)) {
         try {
@@ -494,21 +574,36 @@ export class SkillManager {
   /**
    * Add or update a skill (single-file format).
    *
+   * Always writes to the USER tier (`#userDir`) regardless of where the
+   * existing skill (if any) came from. This matches Claude Code: editing a
+   * bundled skill produces a user-tier override, leaving the bundled file
+   * untouched. Calling `load()` after a `save()` will then surface the
+   * user version (higher priority).
+   *
    * @param {Skill} skill
    * @returns {string} — filename
    */
   save(skill) {
     if (!skill.name) throw new Error('Skill must have a name');
+    if (!this.#userDir) {
+      throw new Error('SkillManager has no writable user directory configured');
+    }
 
     const filename = `${skill.name}.md`;
-    const filePath = join(this.#skillsDir, filename);
+    const filePath = join(this.#userDir, filename);
 
-    if (!existsSync(this.#skillsDir)) {
-      mkdirSync(this.#skillsDir, { recursive: true });
+    if (!existsSync(this.#userDir)) {
+      mkdirSync(this.#userDir, { recursive: true });
     }
 
     writeFileSync(filePath, serializeSkill(skill), 'utf8');
-    this.#skills.set(skill.name, { ...skill, _source: 'file', _path: filePath });
+    const userTier = this.#tierByDir.get(this.#userDir) || basename(this.#userDir);
+    this.#skills.set(skill.name, {
+      ...skill,
+      _source: 'file',
+      _path: filePath,
+      _tier: userTier,
+    });
 
     return filename;
   }
@@ -516,6 +611,11 @@ export class SkillManager {
   /**
    * Remove a skill (supports both file and directory skills).
    *
+   * Only removes user-tier files. Bundled / project-tier skills are
+   * read-only — attempting to remove one returns `false` and leaves the
+   * file alone (the in-memory entry is also kept so a subsequent `load()`
+   * still picks it up).
+   *
    * @param {string} name
    * @returns {boolean}
    */
@@ -523,13 +623,20 @@ export class SkillManager {
     const skill = this.#skills.get(name);
     if (!skill) return false;
 
+    // Only allow removing files inside the user-writable directory. A
+    // bundled or project-tier file would silently come back on the next
+    // load() anyway; refusing here makes the failure obvious.
+    if (!this.#userDir || !skill._path || !skill._path.startsWith(this.#userDir)) {
+      return false;
+    }
+
     if (skill._source === 'directory' && skill._path) {
       // For directory skills, we only delete the SKILL.md to "deactivate"
       // Full directory removal is left to the user (too dangerous to rm -rf)
       const skillMd = join(skill._path, 'SKILL.md');
       try { unlinkSync(skillMd); } catch { /* noop */ }
     } else {
-      const filePath = skill._path || join(this.#skillsDir, `${name}.md`);
+      const filePath = skill._path || join(this.#userDir, `${name}.md`);
       try { unlinkSync(filePath); } catch { /* noop */ }
     }
 
@@ -584,13 +691,89 @@ export class SkillManager {
 }
 
 /**
- * Create a SkillManager and load skills.
+ * Create a SkillManager wired with the standard layered tier list and load it.
+ *
+ * Tier order (lowest → highest priority):
+ *   1. bundled — the yeaft-skills package on disk, located via
+ *      `bundledYeaftSkillsDir()` (typically ~/.claude/skills/yeaft-skills/skills/).
+ *   2. user    — `<yeaftDir>/skills` (e.g. ~/.yeaft/skills). User edits + saves.
+ *   3. project — `<workDir>/.yeaft/skills` when a workDir is provided.
+ *
+ * `save()` / `remove()` always target the USER tier, matching Claude Code.
  *
- * @param {string} yeaftDir
+ * @param {string} yeaftDir — Yeaft data dir (user tier root)
+ * @param {string} [workDir] — optional project working directory (project tier root)
  * @returns {SkillManager}
  */
-export function createSkillManager(yeaftDir) {
-  const manager = new SkillManager(yeaftDir);
+export function createSkillManager(yeaftDir, workDir) {
+  const bundled = bundledYeaftSkillsDir();
+  const userDir = join(yeaftDir, 'skills');
+  const projectDir = workDir ? join(workDir, '.yeaft', 'skills') : null;
+
+  const dirs = [bundled, userDir, projectDir].filter(Boolean);
+  const tierByDir = {};
+  if (bundled) tierByDir[bundled] = 'bundled';
+  tierByDir[userDir] = 'user';
+  if (projectDir) tierByDir[projectDir] = 'project';
+
+  const manager = new SkillManager(dirs, { userDir, tierByDir });
   manager.load();
   return manager;
 }
+
+// ─── Bundled-skills resolver ──────────────────────────────
+
+/**
+ * Locate the bundled `yeaft-skills` package on disk.
+ *
+ * Resolution order (first existing directory wins):
+ *   1. $YEAFT_SKILLS_BUNDLED_DIR — explicit env override (testing / packaging)
+ *   2. ~/.claude/skills/yeaft-skills/skills/    — standard Claude Code plugin layout
+ *   3. ~/.claude/plugins/yeaft-skills/skills/   — alternate plugin layout
+ *   4. <agent-pkg>/skills/                       — bundled-with-agent fallback so
+ *      a future npm release can ship its own skills directory
+ *
+ * Returns `null` when none exist — callers must tolerate this (Yeaft still
+ * runs; the user just sees no pre-installed bundled skills). Co-located here
+ * (rather than in init.js) so both `createSkillManager()` and init.js's seed
+ * step can call it without a module cycle.
+ *
+ * @returns {string|null}
+ */
+export function bundledYeaftSkillsDir() {
+  const candidates = [];
+
+  const envOverride = process.env.YEAFT_SKILLS_BUNDLED_DIR;
+  if (envOverride && typeof envOverride === 'string' && envOverride.length > 0) {
+    candidates.push(envOverride);
+  }
+
+  const home = homedir();
+  if (home) {
+    candidates.push(join(home, '.claude', 'skills', 'yeaft-skills', 'skills'));
+    candidates.push(join(home, '.claude', 'plugins', 'yeaft-skills', 'skills'));
+  }
+
+  // Bundled-with-agent fallback: <agent-pkg-root>/skills. The package root is
+  // the directory containing agent/, so we walk up from this file.
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // here = .../agent/yeaft
+    const agentRoot = join(here, '..', '..');
+    candidates.push(join(agentRoot, 'skills'));
+  } catch {
+    // fileURLToPath can throw on exotic loaders — non-fatal.
+  }
+
+  for (const c of candidates) {
+    try {
+      if (c && existsSync(c) && statSync(c).isDirectory()) {
+        return c;
+      }
+    } catch {
+      // permission errors etc. — try the next candidate.
+    }
+  }
+
+  return null;
+}

package/yeaft/stop-hooks.js

@@ -65,6 +65,9 @@ export async function runStopHooks(context) {
     // history replay can route messages back into the originating group.
     sessionId,
     threadId,
+    // Group VP attribution: persist the engine-bound VP id on assistant/tool
+    // rows so history replay can route replies back to the same visible VP.
+    vpId,
     // Multi-VP fan-out (history-dedup): when several engines run the
     // same user prompt in parallel, the orchestrator persists the user
     // row exactly once before fan-out. Each VP's stop-hook then skips
@@ -164,6 +167,9 @@ export async function runStopHooks(context) {
         // Bug 6: stamp sessionId / threadId so replay can re-route by group.
         if (sessionId) record.sessionId = sessionId;
         if (threadId) record.threadId = threadId;
+        if (vpId && (msg.role === 'assistant' || msg.role === 'tool')) {
+          record.speakerVpId = vpId;
+        }
         conversationStore.append(record);
         result.messagesPersisted++;
       }

package/yeaft/tools/index.js

@@ -11,7 +11,14 @@
 import { ToolRegistry } from './registry.js';
 
 // --- Existing tools ---
-import mcpTools from './mcp-tools.js';
+// NOTE: MCP tools are no longer auto-registered here. The mcp_list_tools /
+// mcp_call_tool meta-tools from `./mcp-tools.js` are kept exported for
+// back-compat, but the default registry now ships only flattened MCP tools
+// (mcp__<server>__<tool>), registered in session.js after the MCPManager
+// has connected to its configured servers. See agent/yeaft/session.js for
+// the flatten-and-register step, and agent/yeaft/tools/mcp-tools.js for
+// the `buildMcpFlattenedTools(mcpManager)` builder used to construct them
+// on first connect and on hot-reload.
 import skillTool from './skill.js';
 import enterWorktree from './enter-worktree.js';
 import exitWorktree from './exit-worktree.js';
@@ -73,7 +80,6 @@ import viewImage from './view-image.js';
  */
 export const allTools = [
   // Existing tools
-  ...mcpTools,
   skillTool,
   enterWorktree,
   exitWorktree,

package/yeaft/tools/mcp-tools.js

@@ -1,17 +1,138 @@
 /**
  * mcp-tools.js — MCP (Model Context Protocol) tool bridge
  *
- * Provides two tools for interacting with MCP servers:
- * - mcp_list_tools: Discover available MCP tools from connected servers
- * - mcp_call_tool: Invoke an MCP tool by name with arguments
+ * Provides TWO surfaces for exposing MCP tools to the LLM:
  *
- * These are exported as an array (unlike other tool files that export a single tool).
+ *   1. **Flattened tools (preferred)** — every MCP tool is registered as a
+ *      first-class entry in the ToolRegistry under the canonical
+ *      `mcp__<server>__<originalToolName>` name (Claude Code convention).
+ *      The LLM sees these in its tool catalogue and can call them in a
+ *      single turn — no `mcp_list_tools` / `mcp_call_tool` indirection.
+ *      Use `buildMcpFlattenedTools(mcpManager)` to obtain the registration
+ *      array, then `toolRegistry.registerAll(...)`. Hot-reload after a
+ *      server connect/disconnect via `toolRegistry.replaceMcpTools(mcpManager)`.
+ *
+ *   2. **Meta tools (back-compat / fallback)** — `mcp_list_tools` and
+ *      `mcp_call_tool` are still exported as standalone ToolDefs. They are
+ *      NOT in the default tool registry anymore; a caller can opt them
+ *      back in by importing and registering them explicitly. Kept for any
+ *      external integration that depends on the old indirection shape.
  *
  * Reference: yeaft-yeaft-design.md §8
  */
 
 import { defineTool } from './types.js';
 
+// ─── Constants ─────────────────────────────────────────────
+
+/**
+ * Cap each flattened MCP tool's description at this many characters when
+ * registering. The system-prompt tool catalogue inflates linearly with
+ * description length and the LLM doesn't need 2KB of vendor-prose per
+ * tool — the inputSchema is what tells it how to call. 256 is enough to
+ * communicate intent for ~all real-world MCP tools and bounds worst-case
+ * prompt growth at `256 * num_mcp_tools` chars.
+ */
+const MAX_DESCRIPTION_LENGTH = 256;
+
+/**
+ * Truncate a description for the tool catalogue.
+ * @param {string} desc
+ * @returns {string}
+ */
+function truncateDescription(desc) {
+  const s = String(desc || '');
+  if (s.length <= MAX_DESCRIPTION_LENGTH) return s;
+  return s.slice(0, MAX_DESCRIPTION_LENGTH - 1) + '…';
+}
+
+/**
+ * Best-effort serialize an MCP tool result into a string the engine can
+ * forward as a tool_result message. MCP's standard `content` array of
+ * `{type:'text', text}` parts is concatenated; anything else falls back
+ * to JSON.
+ *
+ * @param {unknown} result
+ * @returns {string}
+ */
+function formatMcpResult(result) {
+  if (result && typeof result === 'object' && Array.isArray(result.content)) {
+    const textParts = result.content
+      .filter(c => c && c.type === 'text')
+      .map(c => c.text);
+    if (textParts.length > 0) return textParts.join('\n');
+  }
+  if (typeof result === 'string') return result;
+  try {
+    return JSON.stringify(result, null, 2);
+  } catch {
+    return String(result);
+  }
+}
+
+// ─── Flatten builder (preferred surface) ───────────────────
+
+/**
+ * Build a `defineTool(...)` registration for every tool exposed by the
+ * given MCPManager. Tools are named `mcp__<server>__<originalName>`
+ * matching Claude Code's convention so an LLM that's seen this pattern
+ * before treats them identically across hosts.
+ *
+ * The execute function captures the MANAGER reference (not the individual
+ * server / tool entry) so that even if the user disconnects and
+ * reconnects the underlying server between registration and call, the
+ * lookup goes through `mcpManager.callTool(fullName, ...)` and finds the
+ * fresh connection.
+ *
+ * Token-budget note: descriptions are truncated to MAX_DESCRIPTION_LENGTH
+ * chars before being attached. The full description stays accessible to
+ * code via mcpManager.listTools() if a future feature wants it.
+ *
+ * @param {import('../mcp.js').MCPManager} mcpManager
+ * @returns {import('./types.js').ToolDef[]}
+ */
+export function buildMcpFlattenedTools(mcpManager) {
+  if (!mcpManager || typeof mcpManager.listTools !== 'function') {
+    return [];
+  }
+
+  const tools = mcpManager.listTools();
+  return tools.map(t => {
+    // mcpManager.listTools() returns entries shaped as
+    //   { name: '<server>__<tool>', server: '<server>', description, inputSchema }
+    // Pull the original tool name from the suffix; the manager's callTool
+    // expects the full `server__tool` name.
+    const fullName = t.name;
+    const flattenedName = `mcp__${fullName}`;
+
+    return defineTool({
+      name: flattenedName,
+      description: truncateDescription(
+        t.description || `MCP tool ${fullName.split('__').slice(1).join('__')} from server ${t.server}`
+      ),
+      parameters: t.inputSchema || { type: 'object', properties: {} },
+      async execute(input = {}, _ctx) {
+        // Look up the manager fresh on each call. We deliberately don't
+        // close over a server reference — hot-reload may have replaced
+        // the connection since registration.
+        //
+        // Errors are THROWN, not stringified into the result. The engine's
+        // tool-execution catch (engine.js: `catch (err) { output = 'Error: …';
+        // isError = true; }`) turns thrown errors into a `tool_result` with
+        // `is_error: true` so the LLM sees an error signal rather than a
+        // plausible-looking JSON blob it might mistake for normal output.
+        if (!mcpManager || typeof mcpManager.callTool !== 'function') {
+          throw new Error(`MCP manager not available for ${flattenedName}`);
+        }
+        const result = await mcpManager.callTool(fullName, input || {});
+        return formatMcpResult(result);
+      },
+    });
+  });
+}
+
+// ─── Meta tools (legacy / fallback surface) ────────────────
+
 export const mcpListTools = defineTool({
   name: 'mcp_list_tools',
   description: `List all tools available from connected MCP (Model Context Protocol) servers.
@@ -39,11 +160,11 @@ Usage guidelines:
     if (!mcpManager || !mcpManager.hasServers) {
       return JSON.stringify({
         tools: [],
-        message: 'No MCP servers are connected. Configure MCP servers in ~/.yeaft/config.md',
+        message: 'No MCP servers are connected. Configure MCP servers in ~/.yeaft/config.json',
       });
     }
 
-    const tools = mcpManager.listTools(input.server || undefined);
+    const tools = mcpManager.listTools(input?.server || undefined);
 
     return JSON.stringify({
       tools: tools.map(t => ({
@@ -91,12 +212,16 @@ Usage guidelines:
     const mcpManager = ctx?.mcpManager;
 
     if (!mcpManager || !mcpManager.hasServers) {
+      // Same shape used by the meta tools historically — kept as a JSON
+      // payload (NOT throw) because callers of `mcp_call_tool` already pattern-
+      // match on the `error` field. Flattened tools (the preferred surface)
+      // throw instead; see buildMcpFlattenedTools above.
       return JSON.stringify({
-        error: 'No MCP servers are connected. Configure MCP servers in ~/.yeaft/config.md',
+        error: 'No MCP servers are connected. Configure MCP servers in ~/.yeaft/config.json',
       });
     }
 
-    const { tool_name, arguments: args = {}, timeout_ms } = input;
+    const { tool_name, arguments: args = {}, timeout_ms } = input || {};
 
     if (!tool_name) {
       return JSON.stringify({ error: 'tool_name is required' });
@@ -104,20 +229,7 @@ Usage guidelines:
 
     try {
       const result = await mcpManager.callTool(tool_name, args, timeout_ms || 30000);
-
-      // Format MCP result
-      if (result?.content) {
-        // MCP standard response format
-        const textParts = result.content
-          .filter(c => c.type === 'text')
-          .map(c => c.text);
-        if (textParts.length > 0) {
-          return textParts.join('\n');
-        }
-      }
-
-      return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
-
+      return formatMcpResult(result);
     } catch (err) {
       return JSON.stringify({
         error: err.message,
@@ -127,5 +239,11 @@ Usage guidelines:
   },
 });
 
-// Default export as array for compatibility with bulk registration
+/**
+ * Legacy default export: the meta tools as an array. Kept so any existing
+ * caller doing `import mcpTools from './mcp-tools.js'` still works, but
+ * `tools/index.js` no longer ships these in `createFullRegistry()`.
+ * Flattened tools (preferred) are registered by `session.js` after the
+ * MCPManager has connected to its servers.
+ */
 export default [mcpListTools, mcpCallTool];

package/yeaft/tools/registry.js

@@ -359,6 +359,48 @@ export class ToolRegistry {
   get names() {
     return this.getAllTools().map(t => t.name);
   }
+
+  /**
+   * Hot-swap the flattened MCP tool set.
+   *
+   * Removes every currently registered tool whose canonical name starts
+   * with `mcp__` (the flattened MCP tool naming convention used by
+   * `buildMcpFlattenedTools()`), then re-registers a fresh set built from
+   * the live MCPManager. Called by the MCP web-bridge after a successful
+   * connect/disconnect/reload so the running engine's next turn sees the
+   * new tool catalogue without needing a full session restart.
+   *
+   * Why "starts with `mcp__`": that prefix is the canonical Claude Code
+   * naming for flattened MCP tools. It cleanly distinguishes them from
+   * built-in tools (Bash, FileRead, etc.) and from the legacy meta-tools
+   * (`mcp_list_tools`, `mcp_call_tool` — single underscore, NOT removed
+   * here) which a caller may still opt into.
+   *
+   * @param {import('../mcp.js').MCPManager} mcpManager
+   * @param {(mgr: import('../mcp.js').MCPManager) => import('./types.js').ToolDef[]} buildFlattened
+   *   — the builder from `./mcp-tools.js`. Injected so this registry file
+   *   stays free of circular `import` to mcp-tools.js (mcp-tools imports
+   *   `defineTool` from types.js, which lives alongside this file).
+   * @returns {{ removed: number, added: number }}
+   */
+  replaceMcpTools(mcpManager, buildFlattened) {
+    let removed = 0;
+    for (const name of [...this.#tools.keys()]) {
+      if (name.startsWith('mcp__')) {
+        this.#tools.delete(name);
+        removed += 1;
+      }
+    }
+    let added = 0;
+    if (typeof buildFlattened === 'function' && mcpManager) {
+      const fresh = buildFlattened(mcpManager) || [];
+      for (const tool of fresh) {
+        this.register(tool);
+        added += 1;
+      }
+    }
+    return { removed, added };
+  }
 }
 
 /**