repos — cfx-tools

@cfxdevkit/llm-agents Module

Typed LLM workflow agents for Conflux DevKit repository automation. This module provides a framework for running automated repository maintenance tasks using Large Language Models (LLMs), including code review, issue remediation planning, commit workflows, and model validation.

Key Features

Agent Workflows

Review Agent (runReviewAgent): Detects generated file changes, security-sensitive modifications, and code hotspots
Check Agent (runAgentCheck): Runs repository validation, plans OpenSpec remediation changes, generates specification artifacts
Smoke Test (runAgentSmoke): Validates LLM provider responsiveness and JSON output capabilities
All Agent (runAll): Executes the review agent and generates consolidated reports

Commit Workflow

Commit Workflow (runCommitWorkflow): Full automated commit process including:
- Preflight checks (GitNexus, changed scopes)
- Release intent analysis (changeset generation)
- LLM-generated commit messages
- Approval mechanisms (dry-run, prompt, auto-approve)
- Changeset file creation
- Post-generation validation
- Git commit execution

Generic Action System

Action Runner (runAction): Execute any registered repository action via LLM
Configuration (configure): Manage LLM provider settings and action-model mappings
Discovery (listActions, listModels): Enumerate available actions and discovered models

Shared Utilities

Execution context resolution (unit/LLM configuration)
Report generation (JSON/Markdown)
Corpus processing for LLM context
Path validation and documentation link checking
Code hotspot reporting
Model inventory extraction from provider responses

Architecture

Module Structure


workers/
├── agents/           # Specialized LLM agents (review, check, smoke, all)
├── commit/           # Git commit workflow implementation
├── completion/       # LLM provider abstraction and configuration
├── docs/             # Documentation validation utilities
├── runtime/          # Shared utilities (corpus, reporting, path handling)
├── shared/           # Execution context and repo-action definitions
├── tests/            # Test upkeep pipeline
├── validate-models/  # LLM validation probing
└── commands.ts       # Generic action execution and configuration

Usage

CLI Commands

All functionality is exposed via pnpm run llm:<command>:

Command	Description
`llm:all`	Run review agent and generate reports
`llm:check`	Run repository check agent with optional branch/PR creation
`llm:review`	Run code review agent
`llm:smoke`	Test LLM provider responsiveness
`llm:commit`	Execute full commit workflow
`llm:precommit`	Execute precommit workflow
`llm:run <action>`	Execute a specific repository action
`llm:actions`	List all available repository actions
`llm:models`	Discover and list available LLM models
`llm:config`	View or modify LLM configuration

Programmatic Usage


import {
  runReviewAgent,
  runAgentCheck,
  runCommitWorkflow,
  runAction
} from '@cfxdevkit/llm-agents';
 
// Run review agent
await runReviewAgent({ silent: true });
 
// Run check agent with flags
await runAgentCheck(['--quick', '--dry-run']);
 
// Execute commit workflow
await runCommitWorkflow(['--message', 'Fix typo']);
 
// Run generic action
await runAction(['review', '--prompt', 'Focus on security']);
 
// Configure LLM provider
await configure(['set', 'provider', 'lemonade']);
await configure(['set', 'default-model', 'qwen3-coder']);

Configuration

LLM provider configuration is stored in .pi/providers.json (or path specified by CFX_LLM_CONFIG_PATH environment variable):


{
  "provider": "lemonade",
  "baseUrl": "http://host.containers.internal:13305/",
  "defaultModel": "qwen3-coder",
  "requestTimeoutMs": 120000,
  "actions": {
    "review": "gemma-4-26b",
    "check": "qwen3-coder",
    "commit": "qwen3-coder"
  },
  "tokenBudget": {
    "contextFraction": 0.75,
    "cap": 32768,
    "quick": 512,
    "cloudFallback": 4096
  }
}

Configuration can be modified via:


pnpm run llm:config -- set provider openai-compat
pnpm run llm:config -- set base-url https://api.openai.com/v1
pnpm run llm:config -- set default-model gpt-4o
pnpm run llm:config -- set action commit gemma-4-26b

Extending the Module

Adding New Repository Actions

Define the action in workers/shared/repo-actions.ts:


export const myNewAction: RepoActionDefinition = {
  title: 'My New Action',
  description: 'Description of what this action does',
  defaultPrompt: 'Perform the new action on the repository',
  // Optional: action-specific validation
};

Implement the action logic in workers/completion/index.ts within the complete function’s action switch statement, or create a new worker module and export it from src/index.ts.
Add any necessary types or utilities to support the action.

Adding Custom Validation Steps

Validation steps for the check agent are defined in the validation artifact schema. To add new validation:

Extend the validation check in workers/cdk-repo-check (dependency)
The check agent will automatically process new warning/error steps
Customize remediation planning in workers/agents/check/plan.ts if needed

Internal Module Details

Execution Context (`workers/shared/execution-context.ts`)

Resolves whether to use unit-specific configuration or shared repo configuration, and prepares LLM provider settings based on action and model overrides.

Report Generation (`workers/runtime/reports.ts`)

Handles writing JSON and Markdown reports to artifacts/llm/reports/, including:

Agent execution summaries
Validation findings
Commit workflow previews
LLM provider test results

Corpus Processing (`workers/runtime/corpus.ts`)

Collects and chunks files from the repository for LLM context, respecting:

Generated file exclusions
Size limits (512KB per file)
Text file filtering
Chunking by language-appropriate sizes

Path Utilities (`workers/runtime/paths.ts`)

Provides helper functions for:

Detecting security-sensitive files
Identifying generated/distributed files
Determining package ownership from file paths
Language detection from file extensions
Path relativization and SHA256 hashing

LLM Completion (`workers/completion/index.ts`)

Abstracts LLM provider interactions with:

Provider resolution (lemonade, litellm, openai-compat, github-models)
Configuration management
Prompt construction and token budgeting
Thinking mode control
Response validation and retry logic
Progress reporting for long operations

Dependencies

@cfxdevkit/cdk-repo-check: Repository validation (used by check agent)
@cfxdevkit/docs-pipeline: Documentation processing (referenced in agents)
tsx: TypeScript execution for scripts
Vitest: Testing framework
Biome: Code formatting and linting

Error Handling

All async functions properly propagate errors
Configuration errors provide actionable guidance
LLM provider errors include context about the failing action
Workflow failures include detailed failure analysis when LLMs are available
Validation errors include reproducible commands and hints

Contributing

Ensure code passes Biome linting: pnpm lint
Add tests for new functionality in corresponding *.test.ts files
Update documentation for new public APIs
Follow existing patterns for action definitions and workflow implementation
Test changes with pnpm test before submitting PRs

License

This module is part of the Conflux DevKit and is licensed under the same terms as the repository. See the root LICENSE file for details.