@yeaft/webchat-agent 1.0.377 → 1.0.378

package/yeaft/tools/activation.js

@@ -0,0 +1,180 @@
+import { COLLAB_TOOL_POLICY } from './registry.js';
+
+/**
+ * Built-ins whose schemas stay visible on every provider request. Registration
+ * remains broader than exposure so legacy aliases and conditional tools can
+ * still be resolved without paying their schema cost on unrelated turns.
+ */
+export const ALWAYS_VISIBLE_TOOL_NAMES = Object.freeze([
+  'Skill',
+  'EnterWorktree',
+  'ExitWorktree',
+  'AskUser',
+  'DiscoverTools',
+  'WebSearch',
+  'WebFetch',
+  'Bash',
+  'FileRead',
+  'FileWrite',
+  'FileEdit',
+  'Glob',
+  'Grep',
+  'ListDir',
+  'StartPlan',
+  'TodoWrite',
+  'ViewImage',
+]);
+
+export const BACKGROUND_TASK_TOOL_NAMES = Object.freeze([
+  'ListTasks',
+  'ReadTaskLog',
+  'CancelTask',
+]);
+
+export const SUB_AGENT_MANAGEMENT_TOOL_NAMES = Object.freeze([
+  'PromptAgent',
+  'WaitAgent',
+  'CloseAgent',
+  'ListAgents',
+]);
+
+export const CONDITIONAL_BUILTIN_TOOL_NAMES = new Set([
+  'HistorySearch',
+  'DiskUsage',
+  'ApplyPatch',
+  'ListTasks',
+  'ReadTaskLog',
+  'CancelTask',
+  'SpawnAgent',
+  'PromptAgent',
+  'WaitAgent',
+  'CloseAgent',
+  'ListAgents',
+  'RouteForward',
+  'CreateWorkItem',
+  'JsRepl',
+  'NotebookEdit',
+  'ImageGeneration',
+]);
+
+const HISTORY_INTENT_RE = /(?:\bhistory\b|\b(?:prior|previous) (?:chat|conversation|discussion)\b|\bprevious(?:ly)? discussed\b|\bwhat did we (?:decide|discuss|say|agree)\b|\b(?:our|the) (?:earlier|last) decision\b|历史|之前(?:的)?(?:对话|讨论|会话|决定)|过去(?:的)?会话|我们(?:之前|上次)(?:决定|讨论|说)了什么)/iu;
+const DISK_INTENT_RE = /(?:\bdisk (?:usage|space|full)\b|\bstorage (?:usage|space|full)\b|\blargest director|\benospc\b|\bno space left on device\b|磁盘(?:占用|空间|已满)|存储空间|目录占用|空间不足)/iu;
+const PATCH_INTENT_RE = /(?:\bapply (?:a )?patch\b|\bunified diff\b|\bpatch file\b|应用补丁|统一 diff|补丁文件)/iu;
+const TASK_INTENT_RE = /(?:\bbackground (?:task|job|command|process)\b|\btask[_-][a-z0-9]+\b|\btask log\b|后台(?:任务|命令|进程)|任务日志)/iu;
+const SUB_AGENT_INTENT_RE = /(?:\bsub[ -]?agent\b|\bagent(?:s)?\b|\bparallel(?:ize| work| task| review)?\b|\bindependent(?:ly| review)?\b|\banother (?:worker|reviewer|agent)\b|\bdelegate\b|\b(?:run|start|launch|spawn) (?:the |a )?(?:task|child)\b|子 ?Agent|并行(?:处理|工作|任务|审查)?|独立(?:处理|审查)?|另一个(?:人|助手|Agent)|委派)/iu;
+const WORK_ITEM_INTENT_RE = /(?:\bwork ?center\b|\bwork ?item\b|\bdurable tracking\b|\bcross[- ]turn\b|\blong[- ]running goal\b|\bacross multiple (?:turns|sessions)\b|\buntil (?:it is|it's) finished\b|工作中心|工作项|持久(?:任务|跟踪)|跨 ?turn|跨多个会话|长期任务|持续跟踪)/iu;
+const REPL_INTENT_RE = /(?:\bjs ?repl\b|\bjavascript (?:calculation|experiment|evaluation)\b|\bcalculate\b|\bdata transform\b|JavaScript (?:计算|实验|求值)|数据转换|快速计算)/iu;
+const NOTEBOOK_INTENT_RE = /(?:\.ipynb\b|\bjupyter\b|\bnotebook (?:cell|file)\b|Jupyter|笔记本单元格)/iu;
+const IMAGE_GENERATION_INTENT_RE = /(?:\b(?:generate|make|design|draw) (?:me |us )?(?:an? |the )?(?:image|picture|logo|icon|illustration|graphic)\b|\bcreate (?:me |us )?(?:an? |the )?(?:illustration|image|picture|logo|icon|graphic)\b|生成(?:一张)?(?:图片|图像|标志|图标|插图)|创建(?:一张)?(?:插图|图片|图像|标志|图标)|画(?:一张)?(?:图|图片|图标))/iu;
+const MCP_INTENT_RE = /(?:\bmcp\b|model context protocol|模型上下文协议)/iu;
+
+function messageText(message) {
+  const content = message?.content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter(part => part?.type === 'text' && typeof part.text === 'string')
+    .map(part => part.text)
+    .join('\n');
+}
+
+/**
+ * Build a bounded intent window from the current request and recent context.
+ * A short "continue" / "yes" turn can therefore retain a conditional tool
+ * selected by the immediately preceding discussion without making every old
+ * topic permanently activate tools.
+ */
+export function buildToolIntentText(prompt, messages = []) {
+  const recent = Array.isArray(messages) ? messages.slice(-6) : [];
+  const pieces = [...recent.map(messageText), typeof prompt === 'string' ? prompt : '']
+    .filter(Boolean);
+  return pieces.join('\n').slice(-12_000);
+}
+
+function matchedMcpTools(intentText, toolNames) {
+  const mcpTools = toolNames.filter(name => name.startsWith('mcp__'));
+  const normalized = intentText.toLowerCase();
+  const explicitMatches = mcpTools.filter(name => {
+    if (normalized.includes(name.toLowerCase())) return true;
+    const [, server = '', tool = ''] = name.split('__');
+    if (tool && normalized.includes(tool.toLowerCase())) return true;
+    return server && tool
+      && normalized.includes(server.toLowerCase())
+      && normalized.includes(tool.toLowerCase());
+  });
+  if (explicitMatches.length > 0) return explicitMatches;
+  return MCP_INTENT_RE.test(intentText) ? mcpTools : [];
+}
+
+/**
+ * Resolve the canonical tool names exposed to one provider request.
+ *
+ * Unknown caller-registered tools remain visible for compatibility. Only
+ * Yeaft built-ins and flattened MCP tools participate in conditional hiding.
+ *
+ * @param {{
+ *   toolNames: string[],
+ *   prompt?: string,
+ *   messages?: object[],
+ *   collabToolPolicy?: string|null,
+ *   activeTasks?: object[],
+ *   subAgentToolsActivated?: boolean,
+ *   imageGenerationConfigured?: boolean,
+ * }} opts
+ * @returns {Set<string>}
+ */
+export function resolveActiveToolNames({
+  toolNames = [],
+  prompt = '',
+  messages = [],
+  collabToolPolicy = null,
+  activeTasks = [],
+  subAgentToolsActivated = false,
+  imageGenerationConfigured = false,
+} = {}) {
+  const registered = new Set(Array.isArray(toolNames) ? toolNames : []);
+  const active = new Set(ALWAYS_VISIBLE_TOOL_NAMES.filter(name => registered.has(name)));
+  const intentText = buildToolIntentText(prompt, messages);
+  const tasks = Array.isArray(activeTasks) ? activeTasks : [];
+  const hasActiveTasks = tasks.length > 0;
+  const hasSubAgentTask = tasks.some(task => task?.kind === 'sub_agent');
+
+  if (HISTORY_INTENT_RE.test(intentText)) active.add('HistorySearch');
+  if (DISK_INTENT_RE.test(intentText)) active.add('DiskUsage');
+  if (PATCH_INTENT_RE.test(intentText)) active.add('ApplyPatch');
+
+  if (hasActiveTasks || TASK_INTENT_RE.test(intentText)) {
+    for (const name of BACKGROUND_TASK_TOOL_NAMES) active.add(name);
+  }
+
+  if (SUB_AGENT_INTENT_RE.test(intentText) || subAgentToolsActivated || hasSubAgentTask) {
+    active.add('SpawnAgent');
+    for (const name of SUB_AGENT_MANAGEMENT_TOOL_NAMES) active.add(name);
+  }
+
+  if (collabToolPolicy === COLLAB_TOOL_POLICY.MULTI_VP) active.add('RouteForward');
+  if (WORK_ITEM_INTENT_RE.test(intentText)) active.add('CreateWorkItem');
+  if (REPL_INTENT_RE.test(intentText)) active.add('JsRepl');
+  if (NOTEBOOK_INTENT_RE.test(intentText)) active.add('NotebookEdit');
+  if (imageGenerationConfigured && IMAGE_GENERATION_INTENT_RE.test(intentText)) active.add('ImageGeneration');
+
+  for (const name of matchedMcpTools(intentText, toolNames)) active.add(name);
+
+  // Extra tools supplied by an embedding caller have no Yeaft activation
+  // policy. Preserve the historical contract and expose them by default.
+  for (const name of registered) {
+    if (ALWAYS_VISIBLE_TOOL_NAMES.includes(name)) continue;
+    if (CONDITIONAL_BUILTIN_TOOL_NAMES.has(name)) continue;
+    if (name.startsWith('mcp__')) continue;
+    active.add(name);
+  }
+
+  // Never advertise deprecated schema-only compatibility shims. Direct
+  // registry execution without an active-set fence remains backward compatible.
+  active.delete('JsReplReset');
+
+  for (const name of [...active]) {
+    if (!registered.has(name)) active.delete(name);
+  }
+  return active;
+}

package/yeaft/tools/discover-tools.js

@@ -0,0 +1,198 @@
+import { defineTool } from './types.js';
+
+export const TOOL_DISCOVERY_MAX_RESULTS = 24;
+export const TOOL_DISCOVERY_MAX_NAME_CHARS = 256;
+export const TOOL_DISCOVERY_MAX_DESCRIPTION_CHARS = 320;
+export const TOOL_DISCOVERY_MAX_OUTPUT_BYTES = 12 * 1024;
+
+const TOKEN_RE = /[\p{L}\p{N}]+/gu;
+const STOP_WORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'can', 'do', 'for', 'from',
+  'how', 'i', 'in', 'is', 'it', 'me', 'my', 'of', 'on', 'or', 'the', 'this',
+  'to', 'us', 'we', 'what', 'when', 'where', 'which', 'who', 'why', 'with', 'you',
+]);
+
+function lowerTokens(value) {
+  const text = String(value || '');
+  if (!text) return [];
+  const expanded = text
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ');
+  return (expanded.match(TOKEN_RE) || []).map(token => token.toLocaleLowerCase());
+}
+
+function tokens(value) {
+  return lowerTokens(value).filter(token => token.length > 1 && !STOP_WORDS.has(token));
+}
+
+function truncate(value, maxChars) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  return text.length <= maxChars ? text : `${text.slice(0, maxChars - 1)}…`;
+}
+
+function toolSearchText(tool) {
+  return [
+    tool.name,
+    tool.description,
+    ...Object.keys(tool.parameters?.properties || {}),
+  ].map(value => String(value || '')).join(' ');
+}
+
+function scoreTool(tool, queryTokens) {
+  if (queryTokens.length === 0) return 0;
+  const name = String(tool.name || '').toLocaleLowerCase();
+  const text = toolSearchText(tool).toLocaleLowerCase();
+  const haystackTokens = new Set(tokens(text));
+  let score = 0;
+  for (const token of queryTokens) {
+    if (name.includes(token)) score += 8;
+    else if (haystackTokens.has(token)) score += 4;
+    else if (token.length >= 5 && text.includes(token)) score += 1;
+  }
+  return score;
+}
+
+function normalizeCursor(value) {
+  if (value == null || value === '') return 0;
+  const cursor = Number(value);
+  return Number.isInteger(cursor) && cursor >= 0 ? cursor : null;
+}
+
+function validCandidate(tool) {
+  return typeof tool?.name === 'string'
+    && tool.name.length > 0
+    && tool.name.length <= TOOL_DISCOVERY_MAX_NAME_CHARS;
+}
+
+function byteLength(value) {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+
+/**
+ * Return one deterministic page from the complete hidden tool directory.
+ * Lexical scoring only improves ordering; it never decides reachability.
+ */
+export function discoverToolCapabilities({
+  query,
+  candidates = [],
+  cursor = 0,
+  maxResults = TOOL_DISCOVERY_MAX_RESULTS,
+} = {}) {
+  const boundedMax = Math.max(1, Math.min(Number(maxResults) || TOOL_DISCOVERY_MAX_RESULTS, TOOL_DISCOVERY_MAX_RESULTS));
+  const queryTokens = [...new Set(tokens(query))];
+  let omittedInvalid = 0;
+  const scored = [];
+  for (const tool of Array.isArray(candidates) ? candidates : []) {
+    if (!validCandidate(tool)) {
+      omittedInvalid += 1;
+      continue;
+    }
+    scored.push({
+      tool,
+      score: scoreTool(tool, queryTokens),
+    });
+  }
+  scored.sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name));
+
+  const normalizedCursor = normalizeCursor(cursor);
+  if (normalizedCursor == null || normalizedCursor > scored.length) {
+    return {
+      tools: [],
+      next_cursor: null,
+      total: scored.length,
+      omitted_invalid: omittedInvalid,
+      restart_required: true,
+      message: 'The hidden tool directory changed or the cursor is invalid. Restart discovery without a cursor.',
+    };
+  }
+  const start = normalizedCursor;
+  const tools = [];
+  let index = start;
+  while (index < scored.length && tools.length < boundedMax) {
+    const tool = scored[index].tool;
+    const item = {
+      name: tool.name,
+      description: truncate(tool.description, TOOL_DISCOVERY_MAX_DESCRIPTION_CHARS),
+    };
+    const hasMoreAfterItem = index + 1 < scored.length;
+    const tentative = {
+      tools: [...tools, item],
+      next_cursor: hasMoreAfterItem ? index + 1 : null,
+      total: scored.length,
+      omitted_invalid: omittedInvalid,
+    };
+    if (byteLength(tentative) > TOOL_DISCOVERY_MAX_OUTPUT_BYTES) break;
+    tools.push(item);
+    index += 1;
+  }
+
+  const nextCursor = index < scored.length && tools.length > 0 ? index : null;
+  const result = {
+    tools,
+    next_cursor: nextCursor,
+    total: scored.length,
+    omitted_invalid: omittedInvalid,
+  };
+  if (byteLength(result) > TOOL_DISCOVERY_MAX_OUTPUT_BYTES) {
+    return { tools: [], next_cursor: null, total: 0, omitted_invalid: omittedInvalid };
+  }
+  return result;
+}
+
+export default defineTool({
+  name: 'DiscoverTools',
+  description: {
+    en: `Discover registered tools whose full schemas are not currently active.
+
+Use this when the visible tools do not clearly cover the user's request. Search by the user's goal or capability, not by a guessed tool name. The result is a bounded page from the complete hidden tool directory, ordered by likely relevance; lexical similarity affects ordering only and never removes capabilities. If the target is absent, continue with next_cursor until found or the directory is exhausted. If restart_required is true, discard the cursor and restart without one because the registered directory changed. Returned tool schemas become available on the next model loop.`,
+    zh: `发现已注册但当前未激活完整 schema 的工具。
+
+当可见工具不能明确覆盖用户请求时使用。应按用户目标或能力搜索，不要猜工具名。结果是完整隐藏工具目录中的有界分页，并按可能相关性排序；词法相似度只影响顺序，绝不会让能力不可达。如果当前页没有目标，应使用 next_cursor 继续翻页直到找到或目录耗尽。如果 restart_required 为 true，说明注册目录已变化，应丢弃游标并在不带游标的情况下重新开始。返回工具的 schema 会在下一轮模型调用中可用。`,
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: {
+          en: 'User goal or capability used to rank the complete hidden directory',
+          zh: '用于排序完整隐藏目录的用户目标或能力',
+        },
+      },
+      cursor: {
+        type: 'number',
+        description: {
+          en: 'Pagination cursor returned by a previous discovery page',
+          zh: '上一页发现结果返回的分页游标',
+        },
+      },
+      max_results: {
+        type: 'number',
+        description: {
+          en: 'Maximum directory entries to activate (default and maximum: 24)',
+          zh: '最多激活的目录项数（默认及上限为 24）',
+        },
+      },
+    },
+    required: ['query'],
+  },
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx = {}) {
+    const query = typeof input?.query === 'string' ? input.query.trim() : '';
+    if (!query) return JSON.stringify({ error: 'query is required' });
+    if (typeof ctx?.discoverTools !== 'function') {
+      return JSON.stringify({ error: 'Tool discovery is unavailable in this runtime.' });
+    }
+    const result = await ctx.discoverTools({
+      query,
+      cursor: input?.cursor,
+      maxResults: input?.max_results,
+    });
+    const output = JSON.stringify(result);
+    if (Buffer.byteLength(output, 'utf8') > TOOL_DISCOVERY_MAX_OUTPUT_BYTES) {
+      throw new Error('Tool discovery violated its bounded result budget');
+    }
+    return output;
+  },
+});

package/yeaft/tools/index.js

@@ -28,6 +28,7 @@ import askUser from './ask-user.js';
 import webSearch from './web-search.js';
 import webFetch from './web-fetch.js';
 import historySearch from './history-search.js';
+import discoverTools from './discover-tools.js';
 
 // --- P0 File tools ---
 import bash from './bash.js';
@@ -94,6 +95,7 @@ export const allTools = [
   webSearch,
   webFetch,
   historySearch,
+  discoverTools,
 
   // P0 File
   bash,

package/yeaft/tools/registry.js

@@ -48,7 +48,7 @@ function isLocalizedTextObject(value) {
   return ['en', 'zh', 'zh-CN', 'en-US', 'default'].some(key => typeof value[key] === 'string' || typeof value[key] === 'function');
 }
 
-function localizeVisibleText(value, language, toolName) {
+export function localizeVisibleText(value, language, toolName) {
   const lang = normalizeLanguage(language);
   if (typeof value === 'function') return localizeVisibleText(value(lang), lang, toolName);
   if (isLocalizedTextObject(value)) {
@@ -375,17 +375,25 @@ export class ToolRegistry {
 
   /**
    * Get tool definitions for the LLM adapter.
-   * Returns all registered tools unless the current session shape makes a
-   * specific collaboration tool invalid, such as RouteForward in single-VP
-   * sessions.
+   *
+   * Registration and exposure are separate: `activeToolNames` limits which
+   * canonical schemas enter this provider request, while aliases remain
+   * registered for replay compatibility. Collaboration policy is an additional
+   * structural fence (for example, RouteForward is invalid in single-VP
+   * Sessions).
+   *
    * @param {string} [language='en']
-   * @param {{ collabToolPolicy?: string }} [opts]
+   * @param {{ collabToolPolicy?: string, activeToolNames?: Set<string>|string[] }} [opts]
    * @returns {{ name: string, description: string, parameters: object }[]}
    */
   getToolDefs(language = 'en', opts = {}) {
     const lang = normalizeLanguage(language);
     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))
       .map(t => {
         return {
@@ -397,16 +405,24 @@ export class ToolRegistry {
   }
 
   /**
-   * Check whether a tool may be called under the current collaboration policy.
-   * Unknown / absent policy keeps the historical behavior: all registered
-   * tools remain callable.
+   * Check whether a tool may be called under the current exposure and
+   * collaboration policies. Unknown / absent policies keep the historical
+   * behavior for direct registry callers.
+   *
+   * Aliases inherit the canonical tool's activation: an old `Agent` tool call
+   * may execute only when canonical `SpawnAgent` is active for this request.
+   *
    * @param {string} name
-   * @param {{ collabToolPolicy?: string }} [opts]
+   * @param {{ collabToolPolicy?: string, activeToolNames?: Set<string>|string[] }} [opts]
    * @returns {boolean}
    */
   isAllowed(name, opts = {}) {
     const tool = this.#tools.get(name);
     if (!tool) return false;
+    const activeToolNames = opts?.activeToolNames instanceof Set
+      ? 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);
   }
 

package/yeaft/tools/types.js

@@ -22,6 +22,7 @@
  * @property {object} [skillManager] — Skill manager
  * @property {object} [trace] — debug trace
  * @property {object} [config] — engine config
+ * @property {(input: {query:string, cursor?:number, maxResults?:number}) => Promise<object>|object} [discoverTools] — page through hidden registered tool capabilities and activate returned entries for the next provider loop
  * @property {import('../tasks/manager.js').TaskManager} [taskManager] — Session task manager
  * @property {string} [sessionId] — current Session id
  * @property {string[]} [projectSessionIds] — same-Agent sibling Session ids in the current Project