@yeaft/webchat-agent 1.0.409 → 1.0.410

package/yeaft/plugins.js

@@ -0,0 +1,170 @@
+/**
+ * plugins.js — Agent-level selectable Yeaft capabilities.
+ *
+ * An Agent owns installed tools, skills, and MCP configuration. Missing plugin
+ * fields retain historical behavior (everything enabled); explicit arrays are
+ * allowlists and may intentionally be empty.
+ */
+
+function normalizeNameList(value, field) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new Error(`plugins.${field} must be an array`);
+
+  const names = [];
+  const seen = new Set();
+  for (const raw of value) {
+    if (typeof raw !== 'string' || !raw.trim()) {
+      throw new Error(`plugins.${field} entries must be non-empty strings`);
+    }
+    const name = raw.trim();
+    if (!seen.has(name)) {
+      seen.add(name);
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+/** Normalise persisted Agent plugin config while preserving inheritance. */
+export function normalizePluginConfig(value) {
+  // Only an omitted field inherits the legacy all-enabled behavior. An
+  // explicit `null` is persisted schema, not absence, and must be rejected
+  // so every reader can fail closed consistently.
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('plugins must be an object');
+  }
+
+  const out = {};
+  for (const field of ['tools', 'skills', 'mcpServers']) {
+    const names = normalizeNameList(value[field], field);
+    if (names !== undefined) out[field] = names;
+  }
+  for (const key of Object.keys(value)) {
+    if (!['tools', 'skills', 'mcpServers'].includes(key)) {
+      throw new Error(`unknown plugins key: ${key}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Return an explicit deny-all policy for a persisted plugins schema error.
+ * This is deliberately distinct from `{}`, whose missing fields inherit the
+ * historical all-enabled behavior.
+ */
+export function createDenyAllPluginConfig() {
+  return { tools: [], skills: [], mcpServers: [] };
+}
+
+export function isPluginNameEnabled(plugins, field, name) {
+  if (!plugins || !Array.isArray(plugins[field])) return true;
+  return plugins[field].includes(name);
+}
+
+/**
+ * Keep the configured MCP catalog separate from the runtime connection set.
+ * The catalog must retain disabled servers so users can enable them later;
+ * runtimes must receive only the effective allowlisted subset.
+ *
+ * The caller owns the raw configured catalog; this helper never connects it.
+ */
+export function resolveMcpPluginPolicy(mcpConfig, plugins) {
+  const configured = {
+    ...(mcpConfig || {}),
+    servers: Array.isArray(mcpConfig?.servers) ? mcpConfig.servers : [],
+  };
+  if (!Array.isArray(plugins?.mcpServers)) {
+    return { configured, effective: configured };
+  }
+
+  const allowed = new Set(plugins.mcpServers);
+  return {
+    configured,
+    effective: {
+      ...configured,
+      servers: configured.servers.filter(server => allowed.has(server?.name)),
+    },
+  };
+}
+
+/**
+ * Live delegating view over a SkillManager. It does not mutate the shared
+ * manager because Sessions and project runtimes reuse that manager.
+ */
+export function createPluginSkillManager(skillManager, plugins) {
+  if (!skillManager) return null;
+  const hasExplicitSkills = Array.isArray(plugins?.skills);
+  const allowed = hasExplicitSkills ? new Set(plugins.skills) : null;
+  const isAllowed = name => !allowed || allowed.has(name);
+  const has = name => isAllowed(name) && !!skillManager.has?.(name);
+  const list = (...args) => (skillManager.list?.(...args) || [])
+    .filter(skill => isAllowed(skill?.name));
+  const get = name => has(name) ? skillManager.get?.(name) || null : null;
+  const resolve = name => has(name) ? skillManager.resolve?.(name) || null : null;
+  const view = (name, filePath) => has(name) ? skillManager.view?.(name, filePath) || null : null;
+  const findRelevant = (...args) => (skillManager.findRelevant?.(...args) || [])
+    .filter(skill => isAllowed(skill?.name));
+  const getPromptContent = name => has(name) ? skillManager.getPromptContent?.(name) || '' : '';
+
+  return {
+    has,
+    get,
+    resolve,
+    list,
+    view,
+    findRelevant,
+    getPromptContent,
+    getRelevantPromptContent: (...args) => findRelevant(...args)
+      .map(skill => getPromptContent(skill.name))
+      .filter(Boolean)
+      .join('\n\n'),
+    listCategories: () => [...new Set(list().map(skill => skill.category).filter(Boolean))].sort(),
+    get size() { return list().length; },
+  };
+}
+
+/** Build a browser-safe catalog from already discovered Agent assets. */
+export function buildPluginCatalog({ toolRegistry, skillManager, mcpConfig, mcpManager } = {}) {
+  const tools = typeof toolRegistry?.getAllTools === 'function'
+    ? toolRegistry.getAllTools()
+      .filter(tool => !tool?.mcpServer)
+      .map(tool => ({ id: tool.name, label: tool.name }))
+      .sort((a, b) => a.label.localeCompare(b.label))
+    : [];
+
+  const skills = typeof skillManager?.list === 'function'
+    ? skillManager.list()
+      .map(skill => ({
+        id: skill.name,
+        label: skill.name,
+        description: skill.description || '',
+        category: skill.category || null,
+      }))
+      .sort((a, b) => a.label.localeCompare(b.label))
+    : [];
+
+  const statusByName = new Map((mcpManager?.status?.() || [])
+    .map(status => [status.name, status]));
+  // A configured catalog is authoritative, including an explicit empty array.
+  // Only callers that supplied no catalog at all use live status as a legacy
+  // fallback.
+  const configuredMcpServers = Array.isArray(mcpConfig?.servers)
+    ? mcpConfig.servers
+    : (mcpManager?.status?.() || []).map(status => ({ name: status.name, command: '' }));
+  const mcpServers = configuredMcpServers
+    .filter(server => typeof server?.name === 'string' && server.name)
+    .map(server => {
+      const status = statusByName.get(server.name);
+      return {
+        id: server.name,
+        label: server.name,
+        description: server.command || '',
+        ready: status ? !!status.ready : null,
+        toolCount: status?.toolCount || 0,
+      };
+    })
+    .sort((a, b) => a.label.localeCompare(b.label));
+
+  return { tools, skills, mcpServers };
+}

package/yeaft/session.js

@@ -23,6 +23,7 @@ import { recordAgentTokenUsage } from '../metrics.js';
 import { ConversationStore, setDefaultRecentTurnsLimit } from './conversation/persist.js';
 import { SkillManager, createSkillManager } from './skills.js';
 import { MCPManager } from './mcp.js';
+import { resolveMcpPluginPolicy } from './plugins.js';
 import { createFullRegistry } from './tools/index.js';
 import { buildMcpFlattenedTools } from './tools/mcp-tools.js';
 import { Engine } from './engine.js';
@@ -395,19 +396,21 @@ export async function loadSession(options = {}) {
   // present, is only a project tier overlay plus the storage root.
   const projectTierRoot = sessionWorkDir || process.cwd();
 
-  let skillManager;
+  let loadedSkillManager;
   if (skipSkills) {
     // 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(configDir, 'skills'));
+    loadedSkillManager = new SkillManager(join(configDir, 'skills'));
     // Don't call .load() — empty skill manager
   } else {
-    skillManager = createSkillManager(configDir, projectTierRoot);
+    loadedSkillManager = createSkillManager(configDir, projectTierRoot);
   }
+  const skillManager = loadedSkillManager;
 
   // ─── 7. Connect MCP servers ────────────────────────────
-  const mcpConfig = loadMCPConfig(configDir, undefined, projectTierRoot);
+  const rawMcpConfig = loadMCPConfig(configDir, undefined, projectTierRoot);
+  const { effective: mcpConfig } = resolveMcpPluginPolicy(rawMcpConfig, config.plugins);
   const mcpManager = new MCPManager();
   let mcpStatus = { connected: [], failed: [] };
 

package/yeaft/sessions/feature-flag.js

@@ -1,16 +1,18 @@
 /**
  * feature-flag.js — Reads `config.yeaft.multiVp.enabled` from ~/.yeaft/config.json.
  *
- * Per architecture §11: multi-VP group mode is opt-in for MVP. The flag
- * gates UI entry points and (later) migration. This module returns a plain
+ * Per architecture §11: multi-VP Sessions are opt-in for MVP. The flag
+ * gates UI entry points and (later) migration. The reader returns a plain
  * boolean and never throws — missing/corrupt config falls back to `false`.
  *
- * A second helper `setMultiVpEnabled(dir, enabled)` writes through via
- * writeAtomic so tests and future settings UI can toggle it.
+ * The exported writer rejects an existing malformed config or invalid Plugin
+ * schema rather than replacing it, so it cannot reopen a fail-closed Agent
+ * capability policy through an unrelated feature-flag update.
  */
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { normalizePluginConfig } from '../plugins.js';
 import { writeAtomic } from '../storage/index.js';
 
 const CONFIG_FILE = 'config.json';
@@ -20,12 +22,32 @@ function readConfig(yeaftDir) {
   const path = join(yeaftDir, CONFIG_FILE);
   if (!existsSync(path)) return {};
   try {
-    return JSON.parse(readFileSync(path, 'utf8')) || {};
+    const config = JSON.parse(readFileSync(path, 'utf8'));
+    return config && typeof config === 'object' && !Array.isArray(config) ? config : {};
   } catch {
     return {};
   }
 }
 
+/**
+ * Strict precondition for writes to the Agent-owned config document. Reads can
+ * remain tolerant because the flag is optional, but no mutation may replace a
+ * malformed root or a Plugin policy that the runtime must keep fail-closed.
+ */
+function readConfigForWrite(yeaftDir) {
+  const path = join(yeaftDir, CONFIG_FILE);
+  if (!existsSync(path)) return {};
+  const config = JSON.parse(readFileSync(path, 'utf8'));
+  if (!config || typeof config !== 'object' || Array.isArray(config)
+    || Object.getPrototypeOf(config) !== Object.prototype) {
+    throw new Error('config.json must contain an object');
+  }
+  if (Object.prototype.hasOwnProperty.call(config, 'plugins')) {
+    normalizePluginConfig(config.plugins);
+  }
+  return config;
+}
+
 export function isMultiVpEnabled(yeaftDir) {
   const cfg = readConfig(yeaftDir);
   let cur = cfg;
@@ -37,13 +59,24 @@ export function isMultiVpEnabled(yeaftDir) {
 }
 
 export function setMultiVpEnabled(yeaftDir, enabled) {
-  const cfg = readConfig(yeaftDir);
+  let cfg;
+  try {
+    cfg = readConfigForWrite(yeaftDir);
+  } catch (err) {
+    return { error: `Failed to read config.json: ${err?.message || err}` };
+  }
   let cur = cfg;
   for (let i = 0; i < FLAG_PATH.length - 1; i++) {
     const seg = FLAG_PATH[i];
-    if (!cur[seg] || typeof cur[seg] !== 'object') cur[seg] = {};
+    if (!cur[seg] || typeof cur[seg] !== 'object' || Array.isArray(cur[seg])) cur[seg] = {};
     cur = cur[seg];
   }
-  cur[FLAG_PATH[FLAG_PATH.length - 1]] = Boolean(enabled);
-  writeAtomic(join(yeaftDir, CONFIG_FILE), JSON.stringify(cfg, null, 2));
+  const nextValue = Boolean(enabled);
+  cur[FLAG_PATH[FLAG_PATH.length - 1]] = nextValue;
+  try {
+    writeAtomic(join(yeaftDir, CONFIG_FILE), JSON.stringify(cfg, null, 2));
+  } catch (err) {
+    return { error: `Failed to write config.json: ${err?.message || err}` };
+  }
+  return { enabled: nextValue };
 }

package/yeaft/tools/mcp-tools.js

@@ -107,6 +107,7 @@ export function buildMcpFlattenedTools(mcpManager) {
 
     return defineTool({
       name: flattenedName,
+      mcpServer: t.server,
       description: truncateDescription(
         t.description || `MCP tool ${fullName.split('__').slice(1).join('__')} from server ${t.server}`
       ),

package/yeaft/tools/registry.js

@@ -290,6 +290,39 @@ export function isToolHiddenByCollabPolicy(toolName, policy) {
   return normalized === COLLAB_TOOL_POLICY.SINGLE_VP && FORWARD_TOOL_NAMES.includes(toolName);
 }
 
+/**
+ * Normalise an optional Agent-level plugin selection. Missing category fields
+ * preserve historical behavior; explicit empty arrays disable that category.
+ *
+ * @param {object|null|undefined} plugins
+ * @returns {{ tools: Set<string>|null, mcpServers: Set<string>|null }}
+ */
+export function normalizePluginToolPolicy(plugins) {
+  const normalize = (value) => {
+    if (!Array.isArray(value)) return null;
+    return new Set(value
+      .filter(item => typeof item === 'string' && item.trim())
+      .map(item => item.trim()));
+  };
+  return {
+    tools: normalize(plugins?.tools),
+    mcpServers: normalize(plugins?.mcpServers),
+  };
+}
+
+/**
+ * Check a canonical ToolDef against the Agent-level plugin selection. MCP
+ * tools are controlled by server name; built-ins use their canonical name.
+ */
+export function isToolHiddenByPluginPolicy(tool, plugins) {
+  if (!tool) return true;
+  const policy = normalizePluginToolPolicy(plugins);
+  if (tool.mcpServer) {
+    return policy.mcpServers !== null && !policy.mcpServers.has(tool.mcpServer);
+  }
+  return policy.tools !== null && !policy.tools.has(tool.name);
+}
+
 export class ToolRegistry {
   /** @type {Map<string, import('./types.js').ToolDef>} */
   #tools = new Map();
@@ -383,7 +416,7 @@ export class ToolRegistry {
    * Sessions).
    *
    * @param {string} [language='en']
-   * @param {{ collabToolPolicy?: string, activeToolNames?: Set<string>|string[] }} [opts]
+   * @param {{ collabToolPolicy?: string, plugins?: object, activeToolNames?: Set<string>|string[] }} [opts]
    * @returns {{ name: string, description: string, parameters: object }[]}
    */
   getToolDefs(language = 'en', opts = {}) {
@@ -395,6 +428,7 @@ export class ToolRegistry {
     return this.getAllTools()
       .filter(t => !activeToolNames || activeToolNames.has(t.name))
       .filter(t => !isToolHiddenByCollabPolicy(t.name, collabToolPolicy))
+      .filter(t => !isToolHiddenByPluginPolicy(t, opts?.plugins))
       .map(t => {
         return {
           name: t.name,
@@ -413,7 +447,7 @@ export class ToolRegistry {
    * may execute only when canonical `SpawnAgent` is active for this request.
    *
    * @param {string} name
-   * @param {{ collabToolPolicy?: string, activeToolNames?: Set<string>|string[] }} [opts]
+   * @param {{ collabToolPolicy?: string, plugins?: object, activeToolNames?: Set<string>|string[] }} [opts]
    * @returns {boolean}
    */
   isAllowed(name, opts = {}) {
@@ -423,16 +457,26 @@ export class ToolRegistry {
       ? opts.activeToolNames
       : (Array.isArray(opts?.activeToolNames) ? new Set(opts.activeToolNames) : null);
     if (activeToolNames && !activeToolNames.has(tool.name)) return false;
-    return !isToolHiddenByCollabPolicy(tool.name, opts?.collabToolPolicy);
+    return !isToolHiddenByCollabPolicy(tool.name, opts?.collabToolPolicy)
+      && !isToolHiddenByPluginPolicy(tool, opts?.plugins);
   }
 
   /**
-   * Get all registered tool names (canonical only — aliases are excluded
-   * so debug surfaces like the tool-stats panel show one row per tool).
+   * Get registered canonical tool names under an optional policy. Aliases are
+   * excluded so debug surfaces still show one row per real tool.
+   * @param {{ collabToolPolicy?: string, plugins?: object, activeToolNames?: Set<string>|string[] }} [opts]
    * @returns {string[]}
    */
-  getToolNames() {
-    return this.getAllTools().map(t => t.name);
+  getToolNames(opts = {}) {
+    const collabToolPolicy = normalizeCollabToolPolicy(opts?.collabToolPolicy);
+    const activeToolNames = opts?.activeToolNames instanceof Set
+      ? opts.activeToolNames
+      : (Array.isArray(opts?.activeToolNames) ? new Set(opts.activeToolNames) : null);
+    return this.getAllTools()
+      .filter(t => !activeToolNames || activeToolNames.has(t.name))
+      .filter(t => !isToolHiddenByCollabPolicy(t.name, collabToolPolicy))
+      .filter(t => !isToolHiddenByPluginPolicy(t, opts?.plugins))
+      .map(t => t.name);
   }
 
   /**

package/yeaft/tools/types.js

@@ -73,6 +73,7 @@
  * @property {boolean | ((input?: object) => boolean)} [mayMutateWorkspaceAfterReturn] — may keep changing the workspace after execute() resolves; disables same-query read reuse
  * @property {(input?: object) => boolean} [isDestructive] — destructive operation?
  * @property {'json-error-envelope' | null} [errorOutput] — explicit returned-output error contract; null means only thrown errors fail
+ * @property {string} [mcpServer] — owning MCP server for flattened MCP tools
  * @property {'external' | 'run'} [sideEffectScope] — whether mutations escape the current Run collector
  */
 
@@ -90,6 +91,7 @@
  *   mayMutateWorkspaceAfterReturn?: boolean | ((input?: object) => boolean),
  *   isDestructive?: (input?: object) => boolean,
  *   errorOutput?: 'json-error-envelope' | null,
+ *   mcpServer?: string,
  *   sideEffectScope?: 'external' | 'run',
  *   timeoutMs?: number,
  * }} def
@@ -107,6 +109,7 @@ export function defineTool({
   mayMutateWorkspaceAfterReturn = false,
   isDestructive = () => false,
   errorOutput = 'json-error-envelope',
+  mcpServer,
   sideEffectScope = 'external',
   timeoutMs,
 }) {
@@ -132,6 +135,9 @@ export function defineTool({
   if (Array.isArray(aliases) && aliases.length > 0) {
     def.aliases = aliases.slice();
   }
+  if (typeof mcpServer === 'string' && mcpServer.trim()) {
+    def.mcpServer = mcpServer.trim();
+  }
   // Only attach `timeoutMs` when the tool author opts in. Leaving it
   // unset means ToolRegistry.execute uses DEFAULT_TOOL_TIMEOUT_MS — set
   // to <= 0 to disable the per-tool timeout entirely.