skyloom 1.4.0

package/src/core/tool.ts

@@ -0,0 +1,427 @@
+/**
+ * Tool registration and execution framework with retry support
+ */
+
+import { EventEmitter } from "events";
+import { getLogger } from "./logger";
+import { CircuitBreaker } from "./circuit_breaker";
+
+const log = getLogger("tool");
+
+/**
+ * Tool parameter definition
+ */
+export interface ToolParameter {
+  name: string;
+  type: "string" | "number" | "boolean" | "array" | "object";
+  description: string;
+  required?: boolean;
+  default?: unknown;
+  enum?: string[];
+}
+
+/**
+ * Tool handler function
+ */
+export type ToolHandler = (params: Record<string, unknown>) => Promise<string>;
+
+/**
+ * Tool definition
+ */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters?: ToolParameter[];
+  handler?: ToolHandler;
+  maxRetries?: number;
+  retryDelay?: number;
+  dangerous?: boolean;
+  cacheable?: boolean;
+  timeout?: number;
+}
+
+/**
+ * Tool execution result
+ */
+export interface ToolResult {
+  success: boolean;
+  result: string;
+  error?: string;
+  retries?: number;
+  duration?: number;
+}
+
+const CACHE_MAXSIZE = 128;
+const DEFAULT_TIMEOUT = 30000; // 30 seconds
+const DEFAULT_RETRIES = 2;
+const DEFAULT_RETRY_DELAY = 0.5; // seconds
+
+/**
+ * Tool result cache
+ */
+class ToolResultStore {
+  private store: Map<string, Map<string, string>> = new Map();
+
+  get(toolName: string, key: string): string | undefined {
+    const bucket = this.store.get(toolName);
+    if (!bucket) return undefined;
+
+    const value = bucket.get(key);
+    if (value) {
+      // Move to end (LRU)
+      bucket.delete(key);
+      bucket.set(key, value);
+    }
+    return value;
+  }
+
+  set(toolName: string, key: string, value: string): void {
+    let bucket = this.store.get(toolName);
+    if (!bucket) {
+      bucket = new Map();
+      this.store.set(toolName, bucket);
+    }
+
+    bucket.set(key, value);
+
+    // Evict oldest if over limit
+    if (bucket.size > CACHE_MAXSIZE) {
+      const firstKey = bucket.keys().next().value;
+      if (firstKey !== undefined) bucket.delete(firstKey);
+    }
+  }
+
+  clear(toolName?: string): void {
+    if (toolName) {
+      this.store.delete(toolName);
+    } else {
+      this.store.clear();
+    }
+  }
+}
+
+const resultStore = new ToolResultStore();
+
+/**
+ * Type coercion for tool parameters
+ */
+function coerceValue(value: unknown, targetType: string): [boolean, unknown] {
+  if (value === null || value === undefined) {
+    return [true, value];
+  }
+
+  // Already correct type
+  if (targetType === "string" && typeof value === "string") {
+    return [true, value];
+  }
+  if (targetType === "number" && typeof value === "number") {
+    return [true, value];
+  }
+  if (targetType === "boolean" && typeof value === "boolean") {
+    return [true, value];
+  }
+  if (targetType === "array" && Array.isArray(value)) {
+    return [true, value];
+  }
+  if (targetType === "object" && typeof value === "object") {
+    return [true, value];
+  }
+
+  // Lenient coercion from string
+  if (typeof value === "string") {
+    const stripped = value.trim();
+
+    if (targetType === "integer" || targetType === "number") {
+      const num = parseInt(stripped, 10);
+      if (!isNaN(num)) return [true, num];
+      const float = parseFloat(stripped);
+      if (!isNaN(float)) return [true, float];
+      return [false, value];
+    }
+
+    if (targetType === "boolean") {
+      const lower = stripped.toLowerCase();
+      if (["true", "1", "yes", "y"].includes(lower)) return [true, true];
+      if (["false", "0", "no", "n"].includes(lower)) return [true, false];
+      return [false, value];
+    }
+
+    if (targetType === "array") {
+      if (stripped.includes(",")) {
+        return [true, stripped.split(",").map((s) => s.trim())];
+      }
+      return [true, [value]];
+    }
+  }
+
+  return [false, value];
+}
+
+/**
+ * Tool registry and executor
+ */
+export class ToolRegistry extends EventEmitter {
+  private tools: Map<string, ToolDefinition> = new Map();
+  private breakers: Map<string, CircuitBreaker> = new Map();
+
+  /**
+   * Register a tool
+   */
+  register(def: ToolDefinition): void {
+    if (!def.name || !def.description) {
+      throw new Error("Tool must have name and description");
+    }
+
+    this.tools.set(def.name, def);
+
+    // Create circuit breaker for the tool
+    if (!this.breakers.has(def.name)) {
+      this.breakers.set(
+        def.name,
+        new CircuitBreaker({
+          name: `tool_${def.name}`,
+          failureThreshold: 5,
+          resetTimeout: 60000,
+        })
+      );
+    }
+
+    log.info("Tool registered", { tool: def.name });
+    this.emit("registered", def.name);
+  }
+
+  /**
+   * Unregister a tool
+   */
+  unregister(toolName: string): void {
+    this.tools.delete(toolName);
+    this.emit("unregistered", toolName);
+    log.info("Tool unregistered", { tool: toolName });
+  }
+
+  /**
+   * Get a tool definition
+   */
+  get(toolName: string): ToolDefinition | undefined {
+    return this.tools.get(toolName);
+  }
+
+  /**
+   * List all registered tools
+   */
+  list(): ToolDefinition[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Check if tool is registered
+   */
+  has(toolName: string): boolean {
+    return this.tools.has(toolName);
+  }
+
+  /**
+   * Validate tool parameters
+   */
+  validateParameters(toolName: string, params: Record<string, unknown>): [boolean, string] {
+    const tool = this.tools.get(toolName);
+    if (!tool) {
+      return [false, `Tool ${toolName} not found`];
+    }
+
+    if (!tool.parameters) {
+      return [true, ""];
+    }
+
+    for (const param of tool.parameters) {
+      if (param.required && !(param.name in params)) {
+        return [false, `Missing required parameter: ${param.name}`];
+      }
+
+      if (param.name in params) {
+        const [valid] = coerceValue(params[param.name], param.type);
+        if (!valid) {
+          return [false, `Invalid type for parameter ${param.name}: expected ${param.type}`];
+        }
+      }
+    }
+
+    return [true, ""];
+  }
+
+  /**
+   * Execute a tool with retry support
+   */
+  async execute(toolName: string, params: Record<string, unknown>): Promise<ToolResult> {
+    const tool = this.tools.get(toolName);
+    if (!tool) {
+      return {
+        success: false,
+        result: "",
+        error: `Tool ${toolName} not found`,
+      };
+    }
+
+    // Check circuit breaker
+    const breaker = this.breakers.get(toolName);
+    if (breaker && !breaker.canExecute()) {
+      return {
+        success: false,
+        result: "",
+        error: `Tool ${toolName} is temporarily unavailable (circuit breaker open)`,
+      };
+    }
+
+    // Check cache
+    if (tool.cacheable) {
+      const cacheKey = JSON.stringify(params);
+      const cached = resultStore.get(toolName, cacheKey);
+      if (cached) {
+        log.debug("Tool cache hit", { tool: toolName });
+        return {
+          success: true,
+          result: cached,
+        };
+      }
+    }
+
+    // Validate parameters
+    const [valid, error] = this.validateParameters(toolName, params);
+    if (!valid) {
+      return {
+        success: false,
+        result: "",
+        error,
+      };
+    }
+
+    // Execute with retries
+    const maxRetries = tool.maxRetries ?? DEFAULT_RETRIES;
+    const retryDelay = (tool.retryDelay ?? DEFAULT_RETRY_DELAY) * 1000;
+    const timeout = tool.timeout ?? DEFAULT_TIMEOUT;
+
+    let lastError: Error | null = null;
+    let retries = 0;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        if (attempt > 0) {
+          await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        }
+
+        if (!tool.handler) {
+          throw new Error(`No handler for tool ${toolName}`);
+        }
+
+        const startTime = Date.now();
+
+        // Execute with timeout
+        const promise = tool.handler(params);
+        const timeoutPromise = new Promise<string>((_, reject) =>
+          setTimeout(() => reject(new Error("Tool execution timeout")), timeout)
+        );
+
+        const result = await Promise.race([promise, timeoutPromise]);
+
+        const duration = Date.now() - startTime;
+
+        // Cache result
+        if (tool.cacheable) {
+          const cacheKey = JSON.stringify(params);
+          resultStore.set(toolName, cacheKey, result);
+        }
+
+        breaker?.recordSuccess();
+
+        log.info("Tool executed successfully", {
+          tool: toolName,
+          duration,
+          retries: attempt,
+        });
+
+        return {
+          success: true,
+          result,
+          duration,
+          retries: attempt,
+        };
+      } catch (error) {
+        lastError = error as Error;
+        retries = attempt;
+
+        if (attempt < maxRetries) {
+          log.warn("Tool execution failed, retrying", {
+            tool: toolName,
+            attempt: attempt + 1,
+            error: lastError.message,
+          });
+        }
+      }
+    }
+
+    breaker?.recordFailure();
+
+    log.error("Tool execution failed after retries", {
+      tool: toolName,
+      retries,
+      error: lastError?.message,
+    });
+
+    return {
+      success: false,
+      result: "",
+      error: lastError?.message || "Tool execution failed",
+      retries,
+    };
+  }
+
+  /**
+   * Get all tools (alias for list, used by agent code)
+   */
+  getTools(): ToolDefinition[] {
+    return this.list();
+  }
+
+  /**
+   * List all registered tool names
+   */
+  listNames(): string[] {
+    return Array.from(this.tools.keys());
+  }
+
+  /**
+   * Merge tools from another registry into this one.
+   */
+  merge(other: ToolRegistry): void {
+    for (const tool of other.list()) {
+      this.tools.set(tool.name, tool);
+    }
+  }
+
+  /**
+   * Clear result cache for a tool or all tools
+   */
+  clearCache(toolName?: string): void {
+    resultStore.clear(toolName);
+    if (toolName) {
+      log.info("Tool cache cleared", { tool: toolName });
+    } else {
+      log.info("All tool caches cleared");
+    }
+  }
+}
+
+/**
+ * Global tool registry
+ */
+let globalRegistry: ToolRegistry | null = null;
+
+/**
+ * Get the global tool registry
+ */
+export function getToolRegistry(): ToolRegistry {
+  if (!globalRegistry) {
+    globalRegistry = new ToolRegistry();
+  }
+  return globalRegistry;
+}

package/src/core/tool_router.ts

@@ -0,0 +1,193 @@
+/**
+ * Tool-subset selection for LLM calls.
+ *
+ * Without filtering, every chat turn ships ~50 tool schemas (built-ins + MCP +
+ * skill-required + delegation) to the model. That dilutes attention (the LLM
+ * picks plausible-but-wrong tools more often) and burns 8-15k input tokens per
+ * turn. This module narrows the active tool set to ~12 by lightweight scoring
+ * against the user's latest message.
+ *
+ * The router intentionally avoids embeddings / LLM calls — it must run in <1ms
+ * on every turn, before the real LLM call. A coarse keyword/substring score is
+ * good enough to keep the right tools in and bad enough to be cheap.
+ */
+
+import type { ToolDefinition, ToolRegistry } from './tool';
+
+// Infrastructure tools that are useful on most turns.
+const INFRA_TOOLS: ReadonlySet<string> = new Set([
+  'delegate_to',
+  'list_skills',
+  'use_skill',
+  'recall_facts',
+  'remember_fact',
+]);
+
+const MUTATING_TOOLS: ReadonlySet<string> = new Set([
+  'write_file',
+  'edit_file',
+  'move_file',
+  'copy_file',
+  'delete_file',
+  'git_add',
+  'git_commit',
+  'git_checkout',
+  'shell_exec',
+  'http_post',
+  'mcp_add_server',
+  'mcp_remove_server',
+  'mcp_scaffold_server',
+  'kill_process',
+  'package_manager',
+  'service_control',
+]);
+
+const TOKEN_RE = /[A-Za-z][A-Za-z0-9_]*|[一-鿿]+/g;
+
+const STOPWORDS: ReadonlySet<string> = new Set([
+  'a', 'an', 'the', 'is', 'are', 'was', 'were', 'and', 'or', 'but',
+  'to', 'for', 'of', 'in', 'on', 'at', 'with', 'by', 'do', 'did',
+  'does', 'i', 'me', 'my', 'you', 'your', 'it', 'this', 'that',
+  'what', 'how', 'can', 'could', 'would', 'should', 'please',
+  'tell', 'show', 'help', 'ok', 'yes', 'no',
+  '好', '的', '是', '我', '你', '他', '她', '它', '这', '那',
+  '什么', '怎么', '请', '帮', '麻烦',
+]);
+
+function tokenize(text: string): Set<string> {
+  const tokens = new Set<string>();
+  const matches = text?.toLowerCase().match(TOKEN_RE) || [];
+  for (const t of matches) {
+    if (t.length >= 2 && !STOPWORDS.has(t)) {
+      tokens.add(t);
+    }
+  }
+  return tokens;
+}
+
+function scoreTool(tool: ToolDefinition, queryTokens: Set<string>, queryLc: string): number {
+  if (queryTokens.size === 0) return 0;
+  let score = 0;
+
+  // Tool name tokens carry the strongest signal
+  const nameTokens = tokenize(tool.name.replace(/_/g, ' '));
+  for (const qt of queryTokens) {
+    if (nameTokens.has(qt)) {
+      score += 5;
+    } else if (tool.name.toLowerCase().includes(qt)) {
+      score += 3;
+    }
+  }
+
+  // Description tokens are weaker
+  const descTokens = tokenize(tool.description);
+  for (const qt of queryTokens) {
+    if (descTokens.has(qt)) {
+      score += 1;
+    }
+  }
+
+  // Intent boosts for common Chinese/English tasks
+  const name = tool.name;
+  if (['read_file', 'list_directory', 'tree', 'file_search', 'code_search', 'grep'].includes(name) &&
+    ['read', 'file', 'inspect', 'search', 'grep', '看', '读', '查', '搜索', '文件', '代码'].some(k => queryLc.includes(k))) {
+    score += 4;
+  }
+  if (['write_file', 'edit_file', 'move_file', 'copy_file', 'delete_file'].includes(name) &&
+    ['write', 'edit', 'modify', 'fix', 'save', '生成', '写', '改', '修复', '保存', '删除'].some(k => queryLc.includes(k))) {
+    score += 4;
+  }
+  if (name.startsWith('git_') &&
+    ['git', 'commit', 'diff', 'branch', '提交', '分支', '差异'].some(k => queryLc.includes(k))) {
+    score += 4;
+  }
+  if (['web_search', 'fetch_page', 'http_get'].includes(name) &&
+    ['web', 'url', 'http', 'research', '搜索', '网页', '联网', '资料'].some(k => queryLc.includes(k))) {
+    score += 4;
+  }
+  if (['list_skills', 'use_skill'].includes(name) &&
+    ['skill', '能力', '技能', 'ppt', 'pdf', 'excel', 'xlsx', 'docx'].some(k => queryLc.includes(k))) {
+    score += 4;
+  }
+
+  return score;
+}
+
+/**
+ * Return up to ~topK tool names ordered by relevance to the query.
+ *
+ * Always-included infrastructure tools and mustInclude (e.g. active
+ * skill required_tools) are appended regardless of score. When the candidate
+ * set is already small (<= topK + |mustInclude|), no filtering is applied.
+ *
+ * A short or empty query means we have no signal to filter — returning the
+ * full candidate set is correct in that case.
+ */
+export function selectRelevantTools(
+  registry: ToolRegistry,
+  candidateNames: string[],
+  query: string,
+  options?: {
+    topK?: number;
+    mustInclude?: Set<string>;
+  }
+): string[] {
+  const topK = options?.topK ?? 12;
+  const explicitMust = new Set(options?.mustInclude ?? []);
+
+  const infraPresent = candidateNames.filter(n => INFRA_TOOLS.has(n) && !explicitMust.has(n));
+  const mustPresent = candidateNames.filter(n => explicitMust.has(n));
+  const remaining = candidateNames.filter(n => !explicitMust.has(n) && !INFRA_TOOLS.has(n));
+
+  const queryTokens = tokenize(query);
+  const queryLc = (query || '').toLowerCase();
+  const smallSurface = candidateNames.length <= topK + mustPresent.length + infraPresent.length;
+  const lowSignal = queryTokens.size < 2 && queryLc.length < 8;
+
+  // No filtering when the set is already small or the query is too short
+  if (smallSurface || lowSignal) {
+    return [...mustPresent, ...infraPresent, ...remaining];
+  }
+
+  const scored: Array<{ name: string; score: number; penalty: number }> = [];
+  const allScoredNames = [...infraPresent, ...remaining];
+
+  for (const name of allScoredNames) {
+    const tool = registry.get(name);
+    if (!tool) continue;
+    const score = scoreTool(tool, queryTokens, queryLc);
+    const penalty = MUTATING_TOOLS.has(name) && score === 0 ? 1 : 0;
+    scored.push({ name, score, penalty });
+  }
+
+  // Stable sort by descending score; zero-score tools only fill spare slots
+  scored.sort((a, b) => {
+    if (a.score !== b.score) return b.score - a.score;
+    return a.penalty - b.penalty;
+  });
+
+  const budget = Math.max(0, topK - mustPresent.length);
+  const picked: string[] = [];
+  const pickedSet = new Set<string>();
+
+  for (const item of scored) {
+    if (picked.length >= budget) break;
+    if (item.score > 0) {
+      picked.push(item.name);
+      pickedSet.add(item.name);
+    }
+  }
+
+  // Fill remaining slots with zero-score tools
+  if (picked.length < budget) {
+    for (const item of scored) {
+      if (picked.length >= budget) break;
+      if (!pickedSet.has(item.name)) {
+        picked.push(item.name);
+        pickedSet.add(item.name);
+      }
+    }
+  }
+
+  return [...mustPresent, ...picked];
+}