agentsys 5.0.0

package/lib/enhance/tool-patterns.js

@@ -0,0 +1,373 @@
+/**
+ * MCP Tool Definition Patterns
+ * Detection patterns for MCP tool definition issues
+ * Based on FUNCTION-CALLING-TOOL-USE-REFERENCE.md best practices
+ *
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Tool definition patterns
+ */
+const toolPatterns = {
+  /**
+   * Tool name should be verb + noun
+   * MEDIUM certainty - naming convention
+   */
+  poor_tool_naming: {
+    id: 'poor_tool_naming',
+    category: 'tool',
+    certainty: 'MEDIUM',
+    autoFix: false,
+    description: 'Tool name should follow verb_noun pattern',
+    check: (tool) => {
+      if (!tool || !tool.name) return null;
+
+      const name = tool.name;
+      // Check for common verb prefixes
+      const verbPrefixes = ['get', 'set', 'create', 'delete', 'update', 'list', 'find', 'search', 'add', 'remove', 'check', 'validate', 'run', 'execute', 'start', 'stop', 'read', 'write'];
+      const hasVerb = verbPrefixes.some(v => name.toLowerCase().startsWith(v));
+
+      if (!hasVerb && name.length > 3) {
+        return {
+          issue: `Tool name "${name}" doesn't start with a verb`,
+          fix: 'Rename to verb_noun pattern (e.g., get_user, create_file)'
+        };
+      }
+      return null;
+    }
+  },
+
+  /**
+   * Use enums for constrained values
+   * MEDIUM certainty - improves reliability
+   */
+  missing_enum: {
+    id: 'missing_enum',
+    category: 'tool',
+    certainty: 'MEDIUM',
+    autoFix: false,
+    description: 'Parameter with limited options should use enum',
+    check: (schema) => {
+      if (!schema || !schema.properties) return null;
+
+      const issues = [];
+      for (const [name, prop] of Object.entries(schema.properties)) {
+        // Check for string params that mention specific options in description
+        if (prop.type === 'string' && prop.description) {
+          const desc = prop.description.toLowerCase();
+          if ((desc.includes('one of') || desc.includes('must be') || desc.includes('can be')) &&
+              !prop.enum) {
+            issues.push({
+              param: name,
+              issue: `Parameter "${name}" describes options but doesn't use enum`,
+              fix: 'Add enum array with valid options'
+            });
+          }
+        }
+      }
+
+      return issues.length > 0 ? issues : null;
+    }
+  },
+
+  /**
+   * Flat structure preferred
+   * MEDIUM certainty - improves LLM reliability
+   */
+  nested_structure: {
+    id: 'nested_structure',
+    category: 'tool',
+    certainty: 'MEDIUM',
+    autoFix: false,
+    description: 'Prefer flat parameter structure over nested objects',
+    maxDepth: 2,
+    check: (schema, depth = 0) => {
+      if (!schema || typeof schema !== 'object') return null;
+
+      if (depth > 2) {
+        return {
+          issue: `Schema nested ${depth} levels (prefer flat structure)`,
+          fix: 'Flatten to max 2 levels for LLM reliability'
+        };
+      }
+
+      if (schema.properties) {
+        for (const [name, prop] of Object.entries(schema.properties)) {
+          if (prop.type === 'object' && prop.properties) {
+            const nested = toolPatterns.nested_structure.check(prop, depth + 1);
+            if (nested) return { ...nested, param: name };
+          }
+        }
+      }
+
+      return null;
+    }
+  },
+
+  /**
+   * Parameter format hints
+   * LOW certainty - improves clarity
+   */
+  missing_format_hints: {
+    id: 'missing_format_hints',
+    category: 'tool',
+    certainty: 'LOW',
+    autoFix: false,
+    description: 'Parameter description could include format hints',
+    check: (schema) => {
+      if (!schema || !schema.properties) return null;
+
+      const issues = [];
+      const formatKeywords = ['date', 'time', 'email', 'url', 'path', 'json', 'uuid', 'regex'];
+
+      for (const [name, prop] of Object.entries(schema.properties)) {
+        if (prop.type === 'string' && prop.description) {
+          const nameLower = name.toLowerCase();
+          const descLower = prop.description.toLowerCase();
+
+          // Check if name suggests a format but no format/pattern specified
+          for (const keyword of formatKeywords) {
+            if ((nameLower.includes(keyword) || descLower.includes(keyword)) &&
+                !prop.format && !prop.pattern) {
+              issues.push({
+                param: name,
+                issue: `Parameter "${name}" may need format hint`,
+                fix: `Consider adding format or pattern for ${keyword} validation`
+              });
+              break;
+            }
+          }
+        }
+      }
+
+      return issues.length > 0 ? issues : null;
+    }
+  },
+
+  /**
+   * Required parameters should be explicit
+   * HIGH certainty - prevents ambiguity
+   */
+  implicit_required: {
+    id: 'implicit_required',
+    category: 'tool',
+    certainty: 'HIGH',
+    autoFix: true,
+    description: 'Parameters should explicitly declare required status',
+    check: (schema) => {
+      if (!schema || !schema.properties) return null;
+
+      const propCount = Object.keys(schema.properties).length;
+      const requiredCount = schema.required?.length || 0;
+
+      // If properties exist but no required array
+      if (propCount > 0 && !schema.required) {
+        return {
+          issue: 'No required array defined',
+          fix: 'Add required array listing mandatory parameters',
+          autoFixFn: (s) => ({
+            ...s,
+            required: Object.keys(s.properties).filter(k => {
+              const prop = s.properties[k];
+              // Consider params required unless they have default or are marked optional
+              return !prop.default && !/optional/i.test(prop.description || '');
+            })
+          })
+        };
+      }
+
+      return null;
+    }
+  },
+
+  /**
+   * Strict mode recommended
+   * HIGH certainty - prevents undefined behavior
+   */
+  missing_strict_mode: {
+    id: 'missing_strict_mode',
+    category: 'tool',
+    certainty: 'HIGH',
+    autoFix: true,
+    description: 'Schema should use strict mode (additionalProperties: false)',
+    check: (schema) => {
+      if (!schema || schema.type !== 'object') return null;
+
+      if (schema.additionalProperties !== false) {
+        return {
+          issue: 'Schema not in strict mode',
+          fix: 'Add additionalProperties: false',
+          autoFixFn: (s) => ({ ...s, additionalProperties: false })
+        };
+      }
+
+      return null;
+    }
+  },
+
+  /**
+   * Description quality check
+   * LOW certainty - stylistic
+   */
+  poor_description: {
+    id: 'poor_description',
+    category: 'tool',
+    certainty: 'LOW',
+    autoFix: false,
+    description: 'Tool description could be more descriptive',
+    minLength: 20,
+    check: (tool) => {
+      if (!tool || !tool.description) return null;
+
+      const desc = tool.description.trim();
+
+      // Too short
+      if (desc.length < 20) {
+        return {
+          issue: `Description too short (${desc.length} chars)`,
+          fix: 'Add more detail about what the tool does'
+        };
+      }
+
+      // Just repeats the name
+      if (tool.name && desc.toLowerCase().replace(/[_-]/g, ' ') === tool.name.toLowerCase().replace(/[_-]/g, ' ')) {
+        return {
+          issue: 'Description just repeats tool name',
+          fix: 'Describe what the tool does, not its name'
+        };
+      }
+
+      return null;
+    }
+  },
+
+  /**
+   * Redundant tool detection
+   * LOW certainty - may be intentional
+   */
+  redundant_tools: {
+    id: 'redundant_tools',
+    category: 'tool',
+    certainty: 'LOW',
+    autoFix: false,
+    description: 'Potentially redundant tools with similar functionality',
+    check: (tools) => {
+      if (!tools || !Array.isArray(tools) || tools.length < 2) return null;
+
+      const issues = [];
+      const seen = new Map();
+
+      for (const tool of tools) {
+        if (!tool.name) continue;
+
+        // Normalize name for comparison
+        const normalized = tool.name.toLowerCase()
+          .replace(/[_-]/g, '')
+          .replace(/^(get|fetch|retrieve|find|search)/, 'get')
+          .replace(/^(set|update|modify|change)/, 'set')
+          .replace(/^(create|make|add|new)/, 'create')
+          .replace(/^(delete|remove|destroy)/, 'delete');
+
+        if (seen.has(normalized)) {
+          issues.push({
+            tool1: seen.get(normalized),
+            tool2: tool.name,
+            issue: `Tools "${seen.get(normalized)}" and "${tool.name}" may be redundant`,
+            fix: 'Consider consolidating into single tool'
+          });
+        }
+        seen.set(normalized, tool.name);
+      }
+
+      return issues.length > 0 ? issues : null;
+    }
+  }
+};
+
+/**
+ * Get all tool patterns
+ * @returns {Object} All tool patterns
+ */
+function getAllPatterns() {
+  return toolPatterns;
+}
+
+/**
+ * Get patterns by certainty level
+ * @param {string} certainty - HIGH, MEDIUM, or LOW
+ * @returns {Object} Filtered patterns
+ */
+function getPatternsByCertainty(certainty) {
+  const result = {};
+  for (const [name, pattern] of Object.entries(toolPatterns)) {
+    if (pattern.certainty === certainty) {
+      result[name] = pattern;
+    }
+  }
+  return result;
+}
+
+/**
+ * Analyze a tool definition
+ * @param {Object} tool - Tool definition object
+ * @returns {Array} Array of issues found
+ */
+function analyzeTool(tool) {
+  const issues = [];
+
+  for (const [name, pattern] of Object.entries(toolPatterns)) {
+    if (pattern.check && name !== 'redundant_tools') {
+      const result = pattern.check(tool);
+      if (result) {
+        if (Array.isArray(result)) {
+          issues.push(...result.map(r => ({ ...r, patternId: pattern.id, certainty: pattern.certainty })));
+        } else {
+          issues.push({ ...result, patternId: pattern.id, certainty: pattern.certainty });
+        }
+      }
+    }
+  }
+
+  // Check schema separately
+  if (tool.inputSchema || tool.parameters) {
+    const schema = tool.inputSchema || tool.parameters;
+    for (const [name, pattern] of Object.entries(toolPatterns)) {
+      if (pattern.check && ['nested_structure', 'missing_enum', 'missing_format_hints', 'implicit_required', 'missing_strict_mode'].includes(name)) {
+        const result = pattern.check(schema);
+        if (result) {
+          if (Array.isArray(result)) {
+            issues.push(...result.map(r => ({ ...r, patternId: pattern.id, certainty: pattern.certainty, tool: tool.name })));
+          } else {
+            issues.push({ ...result, patternId: pattern.id, certainty: pattern.certainty, tool: tool.name });
+          }
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Check for redundant tools across a set
+ * @param {Array} tools - Array of tool definitions
+ * @returns {Array} Array of redundancy issues
+ */
+function checkRedundancy(tools) {
+  const pattern = toolPatterns.redundant_tools;
+  const result = pattern.check(tools);
+  if (result) {
+    return result.map(r => ({ ...r, patternId: pattern.id, certainty: pattern.certainty }));
+  }
+  return [];
+}
+
+module.exports = {
+  toolPatterns,
+  getAllPatterns,
+  getPatternsByCertainty,
+  analyzeTool,
+  checkRedundancy
+};

package/lib/index.js

@@ -0,0 +1,270 @@
+/**
+ * AgentSys Core Library
+ *
+ * Unified entry point for all core library modules.
+ * Provides platform detection, pattern matching, workflow state management,
+ * configuration management, and context optimization utilities.
+ *
+ * @module agentsys/lib
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+const detectPlatform = require('./platform/detect-platform');
+const verifyTools = require('./platform/verify-tools');
+const reviewPatterns = require('./patterns/review-patterns');
+const slopPatterns = require('./patterns/slop-patterns');
+const pipeline = require('./patterns/pipeline');
+const cliEnhancers = require('./patterns/cli-enhancers');
+const workflowState = require('./state/workflow-state');
+const contextOptimizer = require('./utils/context-optimizer');
+const shellEscape = require('./utils/shell-escape');
+const config = require('./config');
+const sourceCache = require('./sources/source-cache');
+const customHandler = require('./sources/custom-handler');
+const policyQuestions = require('./sources/policy-questions');
+const crossPlatform = require('./cross-platform');
+const enhance = require('./enhance');
+const repoMap = require('./repo-map');
+const perf = require('./perf');
+const collectors = require('./collectors');
+const discoveryModule = require('./discovery');
+
+/**
+ * Platform detection and verification utilities
+ */
+const platform = {
+  /**
+   * Detect project platform configuration
+   * @see module:platform/detect-platform
+   */
+  detect: detectPlatform.detect,
+  detectAsync: detectPlatform.detectAsync,
+  detectCI: detectPlatform.detectCI,
+  detectDeployment: detectPlatform.detectDeployment,
+  detectProjectType: detectPlatform.detectProjectType,
+  detectPackageManager: detectPlatform.detectPackageManager,
+  detectBranchStrategy: detectPlatform.detectBranchStrategy,
+  detectMainBranch: detectPlatform.detectMainBranch,
+  invalidateCache: detectPlatform.invalidateCache,
+
+  /**
+   * Verify tool availability
+   * @see module:platform/verify-tools
+   */
+  verifyTools: verifyTools.verify,
+  verifyToolsAsync: verifyTools.verifyAsync,
+  checkTool: verifyTools.checkTool,
+  checkToolAsync: verifyTools.checkToolAsync,
+  TOOL_DEFINITIONS: verifyTools.TOOL_DEFINITIONS
+};
+
+/**
+ * Code pattern matching utilities
+ */
+const patterns = {
+  /**
+   * Review patterns for code quality analysis
+   * @see module:patterns/review-patterns
+   */
+  review: reviewPatterns,
+
+  /**
+   * Slop patterns for AI-generated code detection
+   * @see module:patterns/slop-patterns
+   */
+  slop: slopPatterns,
+
+  /**
+   * Slop detection pipeline orchestrator
+   * @see module:patterns/pipeline
+   */
+  pipeline: {
+    runPipeline: pipeline.runPipeline,
+    CERTAINTY: pipeline.CERTAINTY,
+    THOROUGHNESS: pipeline.THOROUGHNESS,
+    formatHandoffPrompt: pipeline.formatHandoffPrompt,
+    buildSummary: pipeline.buildSummary
+  },
+
+  /**
+   * Optional CLI tool enhancers for deep analysis
+   * @see module:patterns/cli-enhancers
+   */
+  cliEnhancers: {
+    detectAvailableTools: cliEnhancers.detectAvailableTools,
+    runDuplicateDetection: cliEnhancers.runDuplicateDetection,
+    runDependencyAnalysis: cliEnhancers.runDependencyAnalysis,
+    runComplexityAnalysis: cliEnhancers.runComplexityAnalysis,
+    getMissingToolsMessage: cliEnhancers.getMissingToolsMessage,
+    CLI_TOOLS: cliEnhancers.CLI_TOOLS
+  }
+};
+
+/**
+ * Workflow state management
+ * @see module:state/workflow-state
+ */
+const state = {
+  // Constants
+  SCHEMA_VERSION: workflowState.SCHEMA_VERSION,
+  PHASES: workflowState.PHASES,
+  DEFAULT_POLICY: workflowState.DEFAULT_POLICY,
+
+  // Core functions
+  generateWorkflowId: workflowState.generateWorkflowId,
+  getStatePath: workflowState.getStatePath,
+  ensureStateDir: workflowState.ensureStateDir,
+  validateStateSchema: workflowState.validateStateSchema,
+
+  // CRUD operations
+  createState: workflowState.createState,
+  readState: workflowState.readState,
+  writeState: workflowState.writeState,
+  updateState: workflowState.updateState,
+  deleteState: workflowState.deleteState,
+
+  // Phase management
+  startPhase: workflowState.startPhase,
+  completePhase: workflowState.completePhase,
+  failPhase: workflowState.failPhase,
+  skipToPhase: workflowState.skipToPhase,
+
+  // Workflow lifecycle
+  completeWorkflow: workflowState.completeWorkflow,
+  abortWorkflow: workflowState.abortWorkflow,
+  hasActiveWorkflow: workflowState.hasActiveWorkflow,
+  getWorkflowSummary: workflowState.getWorkflowSummary,
+
+  // Agent management
+  updateAgentResult: workflowState.updateAgentResult,
+  incrementIteration: workflowState.incrementIteration
+};
+
+/**
+ * Git command optimization and string escaping utilities
+ * @see module:utils/context-optimizer
+ * @see module:utils/shell-escape
+ */
+const utils = {
+  contextOptimizer,
+  shellEscape
+};
+
+/**
+ * Task source management
+ * @see module:sources/source-cache
+ * @see module:sources/custom-handler
+ * @see module:sources/policy-questions
+ */
+const sources = {
+  // Main entry point - returns ready-to-use question structure
+  getPolicyQuestions: policyQuestions.getPolicyQuestions,
+  getCustomTypeQuestions: policyQuestions.getCustomTypeQuestions,
+  getCustomNameQuestion: policyQuestions.getCustomNameQuestion,
+  parseAndCachePolicy: policyQuestions.parseAndCachePolicy,
+  isUsingCached: policyQuestions.isUsingCached,
+  needsCustomFollowUp: policyQuestions.needsCustomFollowUp,
+  needsOtherDescription: policyQuestions.needsOtherDescription,
+
+  // Cache operations (direct access if needed)
+  getPreference: sourceCache.getPreference,
+  savePreference: sourceCache.savePreference,
+  getToolCapabilities: sourceCache.getToolCapabilities,
+  saveToolCapabilities: sourceCache.saveToolCapabilities,
+  clearCache: sourceCache.clearCache,
+
+  // Custom source handling (direct access if needed)
+  SOURCE_TYPES: customHandler.SOURCE_TYPES,
+  probeCLI: customHandler.probeCLI,
+  buildCustomConfig: customHandler.buildCustomConfig
+};
+
+/**
+ * Cross-platform utilities for Claude Code, OpenCode, and Codex CLI
+ * @see module:cross-platform
+ */
+const xplat = {
+  // Platform detection
+  PLATFORMS: crossPlatform.PLATFORMS,
+  STATE_DIRS: crossPlatform.STATE_DIRS,
+  getStateDir: crossPlatform.getStateDir,
+  detectPlatform: crossPlatform.detectPlatform,
+
+  // Tool schema helpers
+  TOOL_SCHEMA_GUIDELINES: crossPlatform.TOOL_SCHEMA_GUIDELINES,
+  createToolDefinition: crossPlatform.createToolDefinition,
+
+  // Response helpers (MCP-compatible)
+  successResponse: crossPlatform.successResponse,
+  errorResponse: crossPlatform.errorResponse,
+  unknownToolResponse: crossPlatform.unknownToolResponse,
+
+  // Prompt formatting
+  formatBlock: crossPlatform.formatBlock,
+  formatList: crossPlatform.formatList,
+  formatSection: crossPlatform.formatSection,
+
+  // Token efficiency
+  truncate: crossPlatform.truncate,
+  compactSummary: crossPlatform.compactSummary,
+
+  // Agent prompts
+  AGENT_TEMPLATE: crossPlatform.AGENT_TEMPLATE,
+  createAgentPrompt: crossPlatform.createAgentPrompt,
+
+  // Platform configs
+  getOpenCodeConfig: crossPlatform.getOpenCodeConfig,
+  getCodexConfig: crossPlatform.getCodexConfig,
+  getInstructionFiles: crossPlatform.getInstructionFiles,
+  INSTRUCTION_FILES: crossPlatform.INSTRUCTION_FILES
+};
+
+/**
+ * Plugin discovery via filesystem convention
+ * @see module:discovery
+ */
+const discovery = {
+  parseFrontmatter: discoveryModule.parseFrontmatter,
+  discoverPlugins: discoveryModule.discoverPlugins,
+  discoverCommands: discoveryModule.discoverCommands,
+  discoverAgents: discoveryModule.discoverAgents,
+  discoverSkills: discoveryModule.discoverSkills,
+  discoverAll: discoveryModule.discoverAll,
+  getCommandMappings: discoveryModule.getCommandMappings,
+  getCodexSkillMappings: discoveryModule.getCodexSkillMappings,
+  getPluginPrefixRegex: discoveryModule.getPluginPrefixRegex,
+  invalidateCache: discoveryModule.invalidateCache
+};
+
+// Main exports
+module.exports = {
+  platform,
+  patterns,
+  state,
+  utils,
+  config,
+  sources,
+  xplat,
+  enhance,
+  repoMap,
+  perf,
+  collectors,
+  discovery,
+
+  // Direct module access for backward compatibility
+  detectPlatform,
+  verifyTools,
+  reviewPatterns,
+  slopPatterns,
+  pipeline,
+  cliEnhancers,
+  workflowState,
+  contextOptimizer,
+  shellEscape,
+  sourceCache,
+  customHandler,
+  policyQuestions,
+  crossPlatform,
+  discoveryModule
+};

package/lib/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@agentsys/lib",
+  "version": "4.2.0",
+  "description": "Core library for AgentSys: platform detection, pattern matching, workflow state, and utilities",
+  "main": "index.js",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Avi Fenesh",
+    "url": "https://github.com/avifenesh"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avifenesh/agentsys.git",
+    "directory": "lib"
+  },
+  "files": [
+    "**/*.js",
+    "**/*.json",
+    "!**/*.test.js"
+  ]
+}