lynkr 8.0.1 → 9.0.2

package/src/tools/code-mode.js

@@ -0,0 +1,304 @@
+/**
+ * Code Mode — Meta-Tools for MCP Token Optimization
+ *
+ * Replaces 100+ individual MCP tool definitions with 4 meta-tools,
+ * reducing tool-catalog token overhead from ~17,500 to ~700 tokens.
+ *
+ * Inspired by Bifrost's Code Mode. Instead of sending every MCP tool
+ * schema in every request, the LLM discovers tools lazily:
+ *   1. mcp_list_tools   → discover available tools (compact)
+ *   2. mcp_tool_info    → load full schema for one tool
+ *   3. mcp_tool_docs    → get usage examples
+ *   4. mcp_execute      → execute a tool by name
+ *
+ * Activation: CODE_MODE_ENABLED=true
+ *
+ * @module tools/code-mode
+ */
+
+const { registerTool } = require('.');
+const { listServers, ensureClient } = require('../mcp');
+const config = require('../config');
+const logger = require('../logger');
+
+// ── Tool List Cache ─────────────────────────────────────────────────
+
+let toolListCache = null;
+let toolListCacheTs = 0;
+
+function getCacheTtl() {
+  return config.mcp?.codeMode?.toolListCacheTtl || 60_000;
+}
+
+/**
+ * Fetch tool lists from all MCP servers, with caching.
+ * @param {string} [filterServerId] - Optional: only fetch from this server
+ * @param {boolean} [forceRefresh] - Bypass cache
+ * @returns {Promise<Object>} { serverId: [{ name, description }] }
+ */
+async function fetchToolList(filterServerId, forceRefresh = false) {
+  const now = Date.now();
+  if (!forceRefresh && toolListCache && (now - toolListCacheTs < getCacheTtl())) {
+    if (filterServerId) {
+      return { [filterServerId]: toolListCache[filterServerId] || [] };
+    }
+    return toolListCache;
+  }
+
+  const servers = listServers();
+  const result = {};
+
+  await Promise.all(
+    servers.map(async (server) => {
+      if (filterServerId && server.id !== filterServerId) return;
+      try {
+        const client = await ensureClient(server.id);
+        if (!client) {
+          result[server.id] = { error: 'Server not available' };
+          return;
+        }
+        const response = await client.request('tools/list', {});
+        const tools = Array.isArray(response?.tools) ? response.tools : [];
+        result[server.id] = tools.map(t => ({
+          name: t.name ?? t.method ?? 'unknown',
+          description: (t.description || '').substring(0, 100),
+        }));
+      } catch (err) {
+        result[server.id] = { error: err.message };
+      }
+    })
+  );
+
+  // Update cache if we fetched all servers
+  if (!filterServerId) {
+    toolListCache = result;
+    toolListCacheTs = now;
+  }
+
+  return filterServerId ? { [filterServerId]: result[filterServerId] || [] } : result;
+}
+
+/**
+ * Fetch full tool schema for a specific tool on a specific server.
+ * @param {string} serverId
+ * @param {string} toolName
+ * @returns {Promise<Object|null>}
+ */
+async function fetchToolSchema(serverId, toolName) {
+  const client = await ensureClient(serverId);
+  if (!client) return null;
+
+  const response = await client.request('tools/list', {});
+  const tools = Array.isArray(response?.tools) ? response.tools : [];
+  return tools.find(t => (t.name ?? t.method) === toolName) || null;
+}
+
+/**
+ * Generate a usage example from a tool's input schema.
+ * @param {Object} tool - Tool definition with inputSchema
+ * @returns {string} Example JSON
+ */
+function generateExample(tool) {
+  const schema = tool.inputSchema || tool.input_schema || {};
+  const props = schema.properties || {};
+  const example = {};
+
+  for (const [key, def] of Object.entries(props)) {
+    if (def.type === 'string') example[key] = def.example || `<${key}>`;
+    else if (def.type === 'number' || def.type === 'integer') example[key] = def.example || 0;
+    else if (def.type === 'boolean') example[key] = def.example ?? true;
+    else if (def.type === 'array') example[key] = [];
+    else if (def.type === 'object') example[key] = {};
+    else example[key] = null;
+  }
+
+  return JSON.stringify(example, null, 2);
+}
+
+// ── Meta-Tool Registration ──────────────────────────────────────────
+
+function registerCodeModeTools() {
+  // 1. mcp_list_tools — discover available tools
+  registerTool(
+    'mcp_list_tools',
+    async ({ args = {} }) => {
+      const serverId = args.server_id || null;
+      const forceRefresh = args.force_refresh === true;
+      const result = await fetchToolList(serverId, forceRefresh);
+
+      // Add summary stats
+      let totalTools = 0;
+      for (const tools of Object.values(result)) {
+        if (Array.isArray(tools)) totalTools += tools.length;
+      }
+
+      return {
+        ok: true,
+        status: 200,
+        content: JSON.stringify({ total_tools: totalTools, servers: result }, null, 2),
+      };
+    },
+    {
+      category: 'code-mode',
+      description: 'List all available MCP tools across all servers. Returns tool names and brief descriptions. Use this first to discover what tools are available.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          server_id: { type: 'string', description: 'Optional: filter to a specific MCP server ID' },
+          force_refresh: { type: 'boolean', description: 'Bypass cache and refresh tool list' },
+        },
+      },
+    }
+  );
+
+  // 2. mcp_tool_info — load full schema for one tool
+  registerTool(
+    'mcp_tool_info',
+    async ({ args = {} }) => {
+      const serverId = args.server_id;
+      const toolName = args.tool_name;
+
+      if (!serverId || !toolName) {
+        throw new Error('mcp_tool_info requires server_id and tool_name');
+      }
+
+      const tool = await fetchToolSchema(serverId, toolName);
+      if (!tool) {
+        throw new Error(`Tool "${toolName}" not found on server "${serverId}"`);
+      }
+
+      return {
+        ok: true,
+        status: 200,
+        content: JSON.stringify({
+          server: serverId,
+          name: tool.name ?? tool.method,
+          description: tool.description || '',
+          inputSchema: tool.inputSchema || tool.input_schema || {},
+        }, null, 2),
+      };
+    },
+    {
+      category: 'code-mode',
+      description: 'Get the full schema and detailed description for a specific MCP tool. Use after mcp_list_tools to get the exact parameters needed before calling mcp_execute.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          server_id: { type: 'string', description: 'MCP server ID' },
+          tool_name: { type: 'string', description: 'Tool name from mcp_list_tools' },
+        },
+        required: ['server_id', 'tool_name'],
+      },
+    }
+  );
+
+  // 3. mcp_tool_docs — usage examples
+  registerTool(
+    'mcp_tool_docs',
+    async ({ args = {} }) => {
+      const serverId = args.server_id;
+      const toolName = args.tool_name;
+
+      if (!serverId || !toolName) {
+        throw new Error('mcp_tool_docs requires server_id and tool_name');
+      }
+
+      const tool = await fetchToolSchema(serverId, toolName);
+      if (!tool) {
+        throw new Error(`Tool "${toolName}" not found on server "${serverId}"`);
+      }
+
+      const schema = tool.inputSchema || tool.input_schema || {};
+      const params = Object.entries(schema.properties || {}).map(([name, def]) => ({
+        name,
+        type: def.type || 'any',
+        required: (schema.required || []).includes(name),
+        description: def.description || '',
+      }));
+
+      return {
+        ok: true,
+        status: 200,
+        content: JSON.stringify({
+          server: serverId,
+          tool: tool.name ?? tool.method,
+          description: tool.description || '',
+          parameters: params,
+          example_arguments: generateExample(tool),
+          usage: `Use mcp_execute with server_id="${serverId}", tool_name="${toolName}", and arguments matching the schema above.`,
+        }, null, 2),
+      };
+    },
+    {
+      category: 'code-mode',
+      description: 'Get usage documentation, parameter details, and example arguments for an MCP tool.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          server_id: { type: 'string', description: 'MCP server ID' },
+          tool_name: { type: 'string', description: 'Tool name' },
+        },
+        required: ['server_id', 'tool_name'],
+      },
+    }
+  );
+
+  // 4. mcp_execute — execute a tool by name
+  registerTool(
+    'mcp_execute',
+    async ({ args = {} }) => {
+      const serverId = args.server_id;
+      const toolName = args.tool_name;
+      const toolArgs = args.arguments ?? {};
+
+      if (!serverId || !toolName) {
+        throw new Error('mcp_execute requires server_id and tool_name');
+      }
+
+      const client = await ensureClient(serverId.trim());
+      if (!client) {
+        throw new Error(`MCP server "${serverId}" is not available.`);
+      }
+
+      const result = await client.request(toolName.trim(), toolArgs);
+
+      return {
+        ok: true,
+        status: 200,
+        content: JSON.stringify({
+          server: serverId,
+          tool: toolName,
+          result,
+        }, null, 2),
+        metadata: { server: serverId, tool: toolName },
+      };
+    },
+    {
+      category: 'code-mode',
+      description: 'Execute an MCP tool by name with JSON arguments. First use mcp_list_tools to discover tools, then mcp_tool_info to get the schema, then this tool to execute.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          server_id: { type: 'string', description: 'MCP server ID' },
+          tool_name: { type: 'string', description: 'Tool method name' },
+          arguments: {
+            type: 'object',
+            description: 'JSON arguments matching the tool input schema',
+            additionalProperties: true,
+          },
+        },
+        required: ['server_id', 'tool_name'],
+      },
+    }
+  );
+
+  logger.info('[code-mode] Registered 4 meta-tools: mcp_list_tools, mcp_tool_info, mcp_tool_docs, mcp_execute');
+}
+
+module.exports = {
+  registerCodeModeTools,
+  // Exported for testing
+  fetchToolList,
+  fetchToolSchema,
+  generateExample,
+};

package/src/tools/index.js

@@ -34,7 +34,7 @@ const TOOL_ALIASES = {
   webagent: "web_agent",
   WebAgent: "web_agent",
   tinyfish: "web_agent",
-  task: "fs_write",
+  task: "Task",
   write: "fs_write",
   filewrite: "fs_write",
   read: "fs_read",

package/src/tools/lazy-loader.js

@@ -77,6 +77,11 @@ const TOOL_CATEGORIES = {
     loader: () => require('./agent-task').registerAgentTaskTool,
     priority: 2,
   },
+  'code-mode': {
+    keywords: ['mcp', 'execute', 'server', 'tool', 'code mode'],
+    loader: () => require('./code-mode').registerCodeModeTools,
+    priority: 3,
+  },
 };
 
 /**
@@ -281,6 +286,12 @@ function loadCategoryForTool(toolName) {
     'workspace_sandbox_sessions': 'mcp',
     'workspace_mcp_servers': 'mcp',
 
+    // Code Mode meta-tools
+    'mcp_list_tools': 'code-mode',
+    'mcp_tool_info': 'code-mode',
+    'mcp_tool_docs': 'code-mode',
+    'mcp_execute': 'code-mode',
+
     // Agent task
     // TinyFish (web agent)
     'web_agent': 'tinyfish',

package/src/tools/mcp-remote.js

@@ -1,5 +1,6 @@
 const { registerTool } = require(".");
 const { listServers, ensureClient } = require("../mcp");
+const config = require("../config");
 const logger = require("../logger");
 
 const REMOTE_TOOL_PREFIX = "mcp";
@@ -12,6 +13,12 @@ function sanitiseName(value) {
 }
 
 async function registerRemoteTools() {
+  // Code Mode: register 4 meta-tools instead of individual remote tools
+  if (config.mcp?.codeMode?.enabled) {
+    const { registerCodeModeTools } = require("./code-mode");
+    registerCodeModeTools();
+    return;
+  }
   const servers = listServers();
   await Promise.all(
     servers.map(async (server) => {

package/src/tools/smart-selection.js

@@ -316,6 +316,17 @@ function selectToolsSmartly(tools, classification, options = {}) {
     selectedTools = selectedTools.filter(t => minimalTools.includes(t.name));
   }
 
+  // Code Mode: always include the 4 meta-tools (only ~700 tokens total)
+  const codeConfig = require('../config');
+  if (codeConfig.mcp?.codeMode?.enabled) {
+    const codeModeNames = new Set(['mcp_list_tools', 'mcp_tool_info', 'mcp_tool_docs', 'mcp_execute']);
+    for (const tool of tools) {
+      if (codeModeNames.has(tool.name) && !selectedTools.some(t => t.name === tool.name)) {
+        selectedTools.push(tool);
+      }
+    }
+  }
+
   return selectedTools;
 }
 

package/src/tools/web.js

@@ -152,7 +152,7 @@ function summariseResult(item) {
   return {
     title: item.title ?? item.name ?? null,
     url: item.url ?? item.link ?? null,
-    snippet: item.snippet ?? item.summary ?? item.excerpt ?? null,
+    snippet: item.snippet ?? item.content ?? item.summary ?? item.excerpt ?? null,
     score: item.score ?? item.rank ?? null,
     source: item.source ?? null,
     metadata: item.metadata ?? null,

package/src/utils/payload.js

@@ -0,0 +1,206 @@
+/**
+ * Smart Payload Cloning & Size Estimation
+ *
+ * Optimizes deep-cloning of LLM request payloads to avoid
+ * wasting memory on large base64 media blocks that will be
+ * discarded by flattenBlocks() for most providers.
+ *
+ * @module utils/payload
+ */
+
+const logger = require('../logger');
+
+/**
+ * Estimate the byte size of message content without full serialization.
+ * Scans for base64 image/audio data blocks and text blocks.
+ *
+ * @param {Object} payload - Request payload
+ * @returns {number} Estimated size in bytes
+ */
+function estimateContentSize(payload) {
+  if (!payload || !Array.isArray(payload.messages)) return 0;
+
+  let size = 0;
+  for (const msg of payload.messages) {
+    if (!msg) continue;
+
+    if (typeof msg.content === 'string') {
+      size += msg.content.length;
+      continue;
+    }
+
+    if (!Array.isArray(msg.content)) continue;
+
+    for (const block of msg.content) {
+      if (!block || typeof block !== 'object') continue;
+
+      if (block.text) {
+        size += block.text.length;
+      }
+      // Anthropic image format
+      if (block.source?.data) {
+        size += block.source.data.length;
+      }
+      // OpenAI image_url format (inline base64)
+      if (block.image_url?.url && block.image_url.url.startsWith('data:')) {
+        size += block.image_url.url.length;
+      }
+      // tool_result content
+      if (block.type === 'tool_result' && typeof block.content === 'string') {
+        size += block.content.length;
+      }
+    }
+  }
+
+  return size;
+}
+
+/**
+ * Check if any message content block has base64 media data exceeding threshold.
+ *
+ * @param {Object} payload - Request payload
+ * @param {number} threshold - Size threshold in bytes (default 1MB)
+ * @returns {boolean}
+ */
+function hasLargeMedia(payload, threshold = 1_048_576) {
+  if (!payload || !Array.isArray(payload.messages)) return false;
+
+  for (const msg of payload.messages) {
+    if (!msg || !Array.isArray(msg.content)) continue;
+
+    for (const block of msg.content) {
+      if (!block || typeof block !== 'object') continue;
+
+      // Anthropic base64 image
+      if (block.source?.data && block.source.data.length > threshold) {
+        return true;
+      }
+      // OpenAI inline base64 image
+      if (block.image_url?.url && block.image_url.url.length > threshold) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+// Block types that flattenBlocks() discards (returns empty string)
+const HEAVY_BLOCK_TYPES = new Set(['image', 'audio', 'image_url', 'video']);
+
+/**
+ * Check if a content block is a heavy media block that flattenBlocks() discards.
+ * @param {Object} block
+ * @returns {boolean}
+ */
+function isHeavyMediaBlock(block) {
+  if (!block || typeof block !== 'object') return false;
+  if (HEAVY_BLOCK_TYPES.has(block.type)) return true;
+  if (block.source?.type === 'base64') return true;
+  return false;
+}
+
+/**
+ * Clone payload optimized for providers that will flatten content.
+ * Skips cloning heavy media blocks since flattenBlocks() discards them.
+ *
+ * @param {Object} payload
+ * @returns {Object} Cloned payload with media placeholders
+ */
+function cloneWithFlattenAwareness(payload) {
+  const clean = { ...payload };
+
+  // Deep-clone messages array but skip heavy media blocks
+  if (Array.isArray(payload.messages)) {
+    clean.messages = payload.messages.map(msg => {
+      if (!msg) return msg;
+      const cloned = { ...msg };
+
+      if (Array.isArray(msg.content)) {
+        cloned.content = msg.content.map(block => {
+          if (!block || typeof block !== 'object') return block;
+
+          // Skip heavy media blocks — flattenBlocks() produces "" for these
+          if (isHeavyMediaBlock(block)) {
+            return { type: block.type, _skipped: true };
+          }
+
+          // Shallow clone small blocks (text, tool_result, tool_use)
+          if (block.type === 'tool_result' && typeof block.content === 'object') {
+            return { ...block, content: JSON.parse(JSON.stringify(block.content)) };
+          }
+          return { ...block };
+        });
+      } else if (typeof msg.content === 'object' && msg.content !== null) {
+        cloned.content = { ...msg.content };
+      }
+
+      // Clone tool_calls if present
+      if (Array.isArray(msg.tool_calls)) {
+        cloned.tool_calls = JSON.parse(JSON.stringify(msg.tool_calls));
+      }
+
+      return cloned;
+    });
+  }
+
+  // Deep-clone small arrays that get mutated
+  if (Array.isArray(payload.tools)) {
+    clean.tools = JSON.parse(JSON.stringify(payload.tools));
+  }
+  if (Array.isArray(payload.system)) {
+    clean.system = JSON.parse(JSON.stringify(payload.system));
+  } else if (typeof payload.system === 'string') {
+    clean.system = payload.system;
+  }
+
+  return clean;
+}
+
+/**
+ * Smart deep-clone a request payload.
+ *
+ * - If willFlatten is true: skips cloning heavy media blocks (they'll be discarded)
+ * - If willFlatten is false: uses structuredClone (faster than JSON round-trip)
+ * - Falls back to JSON.parse(JSON.stringify()) for compatibility
+ *
+ * @param {Object} payload - Request payload to clone
+ * @param {Object} options
+ * @param {boolean} options.willFlatten - Whether flattenBlocks() will run (true for most providers)
+ * @returns {Object} Cloned payload
+ */
+function clonePayloadSmart(payload, options = {}) {
+  if (!payload) return {};
+
+  const { willFlatten = false } = options;
+
+  // Fast path: provider will flatten content — skip cloning media blocks
+  if (willFlatten && Array.isArray(payload.messages)) {
+    const hasMedia = payload.messages.some(msg =>
+      Array.isArray(msg?.content) && msg.content.some(isHeavyMediaBlock)
+    );
+    if (hasMedia) {
+      logger.debug('[payload] Using flatten-aware clone (skipping media blocks)');
+      return cloneWithFlattenAwareness(payload);
+    }
+  }
+
+  // Medium path: structuredClone (faster, no string intermediate)
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(payload);
+    } catch {
+      // structuredClone can fail on functions, symbols, etc.
+    }
+  }
+
+  // Slow path: JSON round-trip (original behavior)
+  return JSON.parse(JSON.stringify(payload));
+}
+
+module.exports = {
+  estimateContentSize,
+  hasLargeMedia,
+  clonePayloadSmart,
+  isHeavyMediaBlock,
+};

package/src/utils/perf-timer.js

@@ -0,0 +1,80 @@
+/**
+ * Request Performance Timer
+ *
+ * Lightweight timing instrumentation for the request hot path.
+ * Enable with LOG_LEVEL=debug or PERF_TIMER=true to see per-request
+ * breakdown of where time is spent.
+ *
+ * Usage:
+ *   const timer = createTimer('processMessage');
+ *   timer.mark('sanitizePayload');
+ *   // ... do work ...
+ *   timer.mark('cacheCheck');
+ *   // ... do work ...
+ *   timer.done(); // logs full breakdown
+ *
+ * @module utils/perf-timer
+ */
+
+const { performance } = require('perf_hooks');
+const logger = require('../logger');
+
+const ENABLED = process.env.PERF_TIMER === 'true';
+
+/**
+ * Create a performance timer for a named operation.
+ * @param {string} name - Timer name (e.g., 'processMessage', 'invokeModel')
+ * @returns {{ mark: (label: string) => void, done: () => Object }}
+ */
+function createTimer(name) {
+  if (!ENABLED) {
+    // No-op when disabled — zero overhead
+    return {
+      mark() {},
+      done() { return null; },
+    };
+  }
+
+  const start = performance.now();
+  const marks = [];
+  let lastMark = start;
+
+  return {
+    /**
+     * Record a checkpoint.
+     * @param {string} label - What just completed
+     */
+    mark(label) {
+      const now = performance.now();
+      marks.push({
+        label,
+        elapsed: now - lastMark,
+        cumulative: now - start,
+      });
+      lastMark = now;
+    },
+
+    /**
+     * Finish timing and log the breakdown.
+     * @returns {Object} Timing breakdown
+     */
+    done() {
+      const total = performance.now() - start;
+      const breakdown = {};
+
+      for (const m of marks) {
+        breakdown[m.label] = `${m.elapsed.toFixed(2)}ms`;
+      }
+
+      logger.info({
+        timer: name,
+        totalMs: total.toFixed(2),
+        breakdown,
+      }, `[perf] ${name}: ${total.toFixed(1)}ms`);
+
+      return { name, totalMs: total, marks, breakdown };
+    },
+  };
+}
+
+module.exports = { createTimer };