@aiready/agents 0.1.3

package/.turbo/turbo-test.log

@@ -0,0 +1,16 @@
+
+
+> @aiready/agents@0.1.2 test /Users/pengcao/projects/aiready/packages/agents
+> vitest run
+
+
+ RUN  v1.6.1 /Users/pengcao/projects/aiready/packages/agents
+
+ ✓ src/__tests__/smoke.test.ts  (1 test) 2ms
+
+ Test Files  1 passed (1)
+      Tests  1 passed (1)
+   Start at  15:19:25
+   Duration  249ms (transform 41ms, setup 1ms, collect 37ms, tests 2ms, environment 0ms, prepare 52ms)
+
+[?25h

package/index.ts

@@ -0,0 +1,9 @@
+export * from './src/risk-agent';
+export * from './src/refactor-agent';
+export * from './src/prioritization-agent';
+export * from './src/rename-agent';
+export * from './src/impact-agent';
+export * from './src/restructure-agent';
+export * from './src/validation-agent';
+export * from './src/workflows/remediation-swarm';
+export * from './src/tools/github';

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@aiready/agents",
+  "version": "0.1.3",
+  "description": "Agentic remediation and analysis system for AIReady",
+  "main": "index.js",
+  "type": "module",
+  "dependencies": {
+    "mastra": "^0.1.0",
+    "zod": "^3.0.0",
+    "@aiready/core": "0.21.21",
+    "@aiready/cli": "0.12.23"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/__tests__/smoke.test.ts

@@ -0,0 +1,7 @@
+import { describe, it, expect } from 'vitest';
+
+describe('Agents Smoke Test', () => {
+  it('should pass', () => {
+    expect(true).toBe(true);
+  });
+});

package/src/impact-agent.ts

@@ -0,0 +1,34 @@
+import { Agent } from 'mastra';
+import { z } from 'zod';
+
+export const ImpactAgent = new Agent({
+  name: 'Impact Agent',
+  instructions: `
+    You are a financial analyst for AI infrastructure.
+    Your goal is to estimate the Monthly Token Savings (in USD) for a specific code remediation.
+
+    Analysis Logic:
+    1. Base Cost: Assume an average developer interacts with this code 20 times/day via AI.
+    2. Token Impact: Calculate token reduction based on "Cognitive Load" and "Context Window" savings.
+    3. Model Pricing: Use a blended rate of $10 per 1M tokens (GPT-4o/Claude 3.5 Sonnet average).
+    4. Formulas:
+       - MonthlySavings = (TokensSavedPerInteraction * 20 * 22 days) * (Rate / 1,000,000)
+    
+    Output a JSON object with:
+    - estimatedMonthlySavings: number (USD)
+    - confidenceScore: number (0.0 to 1.0)
+    - breakdown: string (explanation of the math)
+  `,
+  model: {
+    provider: 'openai',
+    name: 'gpt-4o',
+  },
+});
+
+export const ImpactSchema = z.object({
+  estimatedMonthlySavings: z.number(),
+  confidenceScore: z.number(),
+  breakdown: z.string(),
+});
+
+export type ImpactResult = z.infer<typeof ImpactSchema>;

package/src/prioritization-agent.ts

@@ -0,0 +1,31 @@
+import { Agent } from 'mastra';
+import { z } from 'zod';
+
+export const PrioritizationAgent = new Agent({
+  name: 'Prioritization Agent',
+  instructions: `
+    You are a strategic technical debt manager. Your goal is to rank remediation tasks based on their Return on Investment (ROI).
+    
+    ROI Calculation logic:
+    1. savingsScore = estimatedSavings / 100 (capped at 5)
+    2. riskPenalty = { 'low': 0, 'medium': 1, 'high': 3, 'critical': 5 }
+    3. priorityScore = savingsScore - (riskPenalty * 0.5)
+
+    Output a JSON object with:
+    - priorityScore: number
+    - rank: 'P0' | 'P1' | 'P2' | 'P3'
+    - reasoning: string explanation of the ranking decision.
+  `,
+  model: {
+    provider: 'openai',
+    name: 'gpt-4o',
+  },
+});
+
+export const PrioritySchema = z.object({
+  priorityScore: z.number(),
+  rank: z.enum(['P0', 'P1', 'P2', 'P3']),
+  reasoning: z.string(),
+});
+
+export type PriorityResult = z.infer<typeof PrioritySchema>;

package/src/refactor-agent.ts

@@ -0,0 +1,35 @@
+import { Agent } from 'mastra';
+import { z } from 'zod';
+
+export const RefactorAgent = new Agent({
+  name: 'Refactor Agent',
+  instructions: `
+    You are an expert full-stack engineer specialized in code consolidation and refactoring.
+    Your task is to take detected code duplicates or fragmentation issues and consolidate them into reusable components or utilities.
+
+    Follow these rules:
+    1. Preserve functionality: The behavior of the code must remain identical.
+    2. Follow patterns: Match the existing project's implementation patterns (e.g., React hooks, utility functions).
+    3. Type safety: Ensure all changes are correctly typed in TypeScript.
+    4. Minimal changes: Only modify what is necessary to resolve the duplication.
+
+    Workflow:
+    - Read the affected files.
+    - Extract the common logic into a new or existing shared location.
+    - Update the original call sites to use the consolidated logic.
+    - Verify with type checking if possible.
+  `,
+  model: {
+    provider: 'openai',
+    name: 'gpt-4o',
+  },
+});
+
+export const RefactorResultSchema = z.object({
+  status: z.enum(['success', 'failure']),
+  diff: z.string(),
+  filesModified: z.array(z.string()),
+  explanation: z.string(),
+});
+
+export type RefactorResult = z.infer<typeof RefactorResultSchema>;

package/src/rename-agent.ts

@@ -0,0 +1,39 @@
+import { Agent } from 'mastra';
+import { z } from 'zod';
+
+export const RenameAgent = new Agent({
+  name: 'Rename Agent',
+  instructions: `
+    You are a linguistics and domain-modeling expert specialized in software engineering.
+    Your goal is to resolve "Terminology Drift" by standardizing identifiers (variables, functions, classes) across the codebase.
+
+    Follow these rules:
+    1. Domain Alignment: Map technical identifiers to the business domain language provided in the context.
+    2. Consistency: Ensure the same concept is named identically everywhere.
+    3. Type Safety: Verify that renames don't break TypeScript types or external API contracts.
+    4. Documentation: Update JSDoc/TSDoc comments to reflect the new names.
+
+    Workflow:
+    - Analyze the current naming patterns vs. the target domain model.
+    - Propose a mapping of old -> new names.
+    - Execute the rename across all affected files.
+  `,
+  model: {
+    provider: 'openai',
+    name: 'gpt-4o',
+  },
+});
+
+export const RenameResultSchema = z.object({
+  status: z.enum(['success', 'failure']),
+  renames: z.array(
+    z.object({
+      oldName: z.string(),
+      newName: z.string(),
+      files: z.array(z.string()),
+    })
+  ),
+  explanation: z.string(),
+});
+
+export type RenameResult = z.infer<typeof RenameResultSchema>;

package/src/restructure-agent.ts

@@ -0,0 +1,42 @@
+import { Agent } from 'mastra';
+import { z } from 'zod';
+
+export const RestructureAgent = new Agent({
+  name: 'Restructure Agent',
+  instructions: `
+    You are an expert Software Architect specialized in AI-Ready codebases.
+    Your goal is to optimize the repository structure to reduce "Context Fragmentation".
+
+    Core Analysis Principles:
+    1. Feature-First: Group files by feature/domain rather than by technical layer (e.g., put 'user-api', 'user-service', 'user-schema' in one folder).
+    2. Flattening: Reduce deep nesting (3+ levels) which confuses AI navigation.
+    3. Cohesion: Identify files that are always imported together and propose merging or co-location.
+
+    Output a JSON object with:
+    - proposedChanges: array of { type: 'move' | 'merge' | 'delete', source: string, target: string, reason: string }
+    - strategy: string (explanation of the architectural vision)
+    - impact: { cognitiveLoadReduction: number (0-100), fragmentationReduction: number (0-100) }
+  `,
+  model: {
+    provider: 'openai',
+    name: 'gpt-4o',
+  },
+});
+
+export const RestructureSchema = z.object({
+  proposedChanges: z.array(
+    z.object({
+      type: z.enum(['move', 'merge', 'delete']),
+      source: z.string(),
+      target: z.string(),
+      reason: z.string(),
+    })
+  ),
+  strategy: z.string(),
+  impact: z.object({
+    cognitiveLoadReduction: z.number(),
+    fragmentationReduction: z.number(),
+  }),
+});
+
+export type RestructureResult = z.infer<typeof RestructureSchema>;

package/src/risk-agent.ts

@@ -0,0 +1,34 @@
+import { Agent } from 'mastra';
+import { z } from 'zod';
+
+export const RiskAssessmentAgent = new Agent({
+  name: 'Risk Assessment Agent',
+  instructions: `
+    You are an expert software architect specialized in analyzing the risk of automated code refactorings.
+    Your goal is to evaluate a set of code metrics and determine if it's safe to apply an automated fix.
+
+    Consider the following risk factors:
+    1. linesChanged: More changes increase risk.
+    2. filesAffected: High blast radius increases risk.
+    3. cognitiveLoad: High complexity makes it harder to verify the fix.
+    4. testabilityIndex: Low testability makes it dangerous to refactor.
+    5. dependencyHealth: Fragmented imports increase the chance of side effects.
+
+    Output a JSON object with:
+    - riskLevel: 'low' | 'medium' | 'high' | 'critical'
+    - autoApprove: boolean (true only for 'low' risk)
+    - reasoning: string
+  `,
+  model: {
+    provider: 'openai',
+    name: 'gpt-4o',
+  },
+});
+
+export const RiskSchema = z.object({
+  riskLevel: z.enum(['low', 'medium', 'high', 'critical']),
+  autoApprove: z.boolean(),
+  reasoning: z.string(),
+});
+
+export type RiskAssessment = z.infer<typeof RiskSchema>;

package/src/tools/github.ts

@@ -0,0 +1,55 @@
+import { createTool } from 'mastra';
+import { z } from 'zod';
+
+// Note: In a real implementation, this would use Octokit with appropriate auth
+export const githubTools = {
+  createBranch: createTool({
+    id: 'create-branch',
+    description: 'Create a new branch in the repository',
+    inputSchema: z.object({
+      repoId: z.string(),
+      branchName: z.string(),
+      baseBranch: z.string().default('main'),
+    }),
+    outputSchema: z.object({
+      success: z.boolean(),
+      branchUrl: z.string().optional(),
+    }),
+    execute: async ({ input }) => {
+      console.log(
+        `[GitHubTool] Creating branch ${input.branchName} from ${input.baseBranch}`
+      );
+      // Mock implementation
+      return {
+        success: true,
+        branchUrl: `https://github.com/placeholder/${input.branchName}`,
+      };
+    },
+  }),
+
+  createPullRequest: createTool({
+    id: 'create-pr',
+    description: 'Create a Pull Request for a branch',
+    inputSchema: z.object({
+      repoId: z.string(),
+      title: z.string(),
+      body: z.string(),
+      head: z.string(),
+      base: z.string().default('main'),
+    }),
+    outputSchema: z.object({
+      success: z.boolean(),
+      prNumber: z.number().optional(),
+      prUrl: z.string().optional(),
+    }),
+    execute: async ({ input }) => {
+      console.log(`[GitHubTool] Creating PR: ${input.title}`);
+      // Mock implementation
+      return {
+        success: true,
+        prNumber: 123,
+        prUrl: 'https://github.com/placeholder/pull/123',
+      };
+    },
+  }),
+};

package/src/validation-agent.ts

@@ -0,0 +1,38 @@
+import { Agent } from 'mastra';
+import { z } from 'zod';
+
+export const ValidationAgent = new Agent({
+  name: 'Validation Agent',
+  instructions: `
+    You are a Senior QA Automation Engineer and Type System Expert.
+    Your role is to verify that an AI-generated refactor is technically sound.
+
+    Validation Cycle:
+    1. Check for TypeScript compilation errors (if applicable).
+    2. Verify that exported symbols are still available at the same paths or updated correctly.
+    3. Analyze test output (if provided) to identify regression causes.
+
+    Output a JSON object with:
+    - status: 'pass' | 'fail'
+    - errors: array of { file: string, message: string, line?: number }
+    - feedbackForRefactor: string (detailed instructions for the RefactorAgent on how to fix these errors)
+  `,
+  model: {
+    provider: 'openai',
+    name: 'gpt-4o',
+  },
+});
+
+export const ValidationSchema = z.object({
+  status: z.enum(['pass', 'fail']),
+  errors: z.array(
+    z.object({
+      file: z.string(),
+      message: z.string(),
+      line: z.number().optional(),
+    })
+  ),
+  feedbackForRefactor: z.string().optional(),
+});
+
+export type ValidationResult = z.infer<typeof ValidationSchema>;

package/src/workflows/remediation-swarm.ts

@@ -0,0 +1,39 @@
+import { Workflow } from 'mastra';
+import { PrioritizationAgent } from '../prioritization-agent';
+import { ImpactAgent } from '../impact-agent';
+import { RestructureAgent } from '../restructure-agent';
+import { RefactorAgent } from '../refactor-agent';
+import { ValidationAgent } from '../validation-agent';
+
+export const RemediationSwarm = new Workflow({
+  name: 'Remediation Swarm',
+  steps: [
+    {
+      id: 'prioritize',
+      agent: PrioritizationAgent,
+      description: 'Calculating ROI and Risk hierarchy',
+    },
+    {
+      id: 'impact',
+      agent: ImpactAgent,
+      description: 'Predicting monetary token savings',
+    },
+    {
+      id: 'restructure',
+      agent: RestructureAgent,
+      description: 'Optimizing architecture and folder structure',
+    },
+    {
+      id: 'refactor',
+      agent: RefactorAgent,
+      description: 'Executing the code consolidation',
+    },
+    {
+      id: 'validate',
+      agent: ValidationAgent,
+      description: 'Verifying types and automated tests',
+    },
+  ],
+  // Note: Complex looping and conditional logic is typically handled
+  // in the workflow's trigger or a custom execution handler in Mastra.
+});