Universal Coding Agent (UCA)

A provider-agnostic autonomous coding agent supervisor with failover, persistent task state, and multi-provider orchestration.

Overview

The Universal Coding Agent (UCA) is a supervisor/orchestrator that manages coding tasks across multiple AI providers. It does not replace coding agents like OpenCode—it wraps them, providing:

Persistent task state that survives crashes, restarts, and provider switches
Automatic failover between providers when one fails or exhausts quota
Provider abstraction so you can use Nemotron, Codex, Claude, Gemini, OpenRouter, Ollama, or any compatible provider
Git safety with checkpoints and repository state tracking
Verification via tests, build, lint, and typecheck
Routing strategies for quality, speed, cost, or availability

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      UCA Supervisor                          │
├─────────────────────────────────────────────────────────────┤
│  Task Lifecycle Manager  │  Provider Router  │  State Store │
├─────────────────────────────────────────────────────────────┤
│                    Provider Adapters                         │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────┐ │
│  │Nemotron │ │ Codex   │ │ Claude  │ │ Gemini  │ │Ollama │ │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └───────┘ │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │   OpenCode / CLI      │
              │   (Execution Layer)   │
              └───────────────────────┘

Core Components

Component	Responsibility
Task Manager	Creates, tracks, and manages task lifecycle
State Store	Persists task state, checkpoints, history to `.agent/`
Provider Registry	Manages provider adapters and their lifecycle
Provider Router	Selects optimal provider based on strategy
Error Classifier	Categorizes errors for retry/failover decisions
Git Inspector	Tracks repository state, diffs, checkpoints
Verification Engine	Runs tests, build, lint, typecheck

Provider Tiers

Tier 1: Primary

NVIDIA Nemotron 3 Ultra ✅ Implemented - Primary cloud provider via NVIDIA API
OpenCode - Local coding agent execution layer

Tier 2: Strong Cloud

OpenAI Codex (planned)
Anthropic Claude (planned)
Google Gemini (planned, via Antigravity if available)

Tier 3: Other Cloud / Fast

OpenRouter (planned)
OmniRoute (planned)
Groq (planned)

Tier 4: Local Fallback

Ollama (planned) (Qwen, Ministral, Granite, etc.)

Installation

# From source
git clone https://github.com/Fafda-Jalebi/Universal-Coding-Agent
cd Universal-Coding-Agent
npm install
npm run build

# Run CLI
npx uca --help

Quick Start

# Create a task
uca task create "Build a REST API with authentication" --description "JWT-based auth with refresh tokens"

# Start the task (auto-selects best provider)
uca task start <task-id>

# Check status
uca task show <task-id>

# Run verification
uca verify <task-id> -t tests,build,lint

Configuration

Create uca.config.yaml in your project root or ~/.uca/config.yaml:

version: 1
providers:
  - id: nemotron
    name: NVIDIA Nemotron 3 Ultra
    type: nemotron
    priority: 100
    enabled: true
    apiKeyEnv: NEMOTRON_API_KEY
    capabilities: [coding, reasoning, large-context]

  - id: codex
    name: OpenAI Codex
    type: codex
    priority: 95
    enabled: true
    apiKeyEnv: OPENAI_API_KEY
    capabilities: [coding, repository-operations]

  - id: ollama
    name: Ollama Local
    type: ollama
    priority: 20
    enabled: true
    endpoint: http://localhost:11434
    capabilities: [coding, local, privacy]

routing:
  strategy: quality-first  # quality-first | speed-first | cost-first | availability-first | capability-based
  fallbackEnabled: true
  maxFailovers: 3
  escalationEnabled: false

task:
  stateDir: .agent
  defaultVerification: [tests, build, lint]
  checkpointInterval: 5

logging:
  level: info
  fileEnabled: true
  consoleEnabled: true
  logDir: .agent/logs

git:
  autoCheckpoint: false
  checkpointMessagePrefix: "[UCA]"
  trackModifiedFiles: true
  recordDiffs: true

Environment Variables

# Provider API keys (never commit these!)
export NEMOTRON_API_KEY=your-nvidia-api-key    # Required for Nemotron 3 Ultra
export OPENAI_API_KEY=your-key                 # For OpenAI Codex (planned)
export ANTHROPIC_API_KEY=your-key              # For Anthropic Claude (planned)
export GEMINI_API_KEY=your-key                 # For Google Gemini (planned)
export OPENROUTER_API_KEY=your-key             # For OpenRouter (planned)
export OMNIROUTE_API_KEY=your-key              # For OmniRoute (planned)

CLI Commands

Task Management

uca task create <objective> [-d description] [-p priority] [--provider id]
uca task list [-s status]
uca task show <task-id>
uca task start <task-id> [--provider id]
uca task pause <task-id>
uca task resume <task-id>
uca task cancel <task-id>
uca task plan <task-id> <steps...>

Provider Management

uca provider list
uca provider health [provider-id]
uca provider test-failover <task-id> <provider-id>

State Management

uca state checkpoints <task-id>
uca state history <task-id> [-n limit]
uca state export <task-id> [-o file]

Verification

uca verify <task-id> [-t tests,build,lint,typecheck]

Demo

uca demo

Smoke Test (Nemotron)

# Requires NEMOTRON_API_KEY environment variable
export NEMOTRON_API_KEY=your-key
uca smoke-test

Task State Persistence

Task state is stored in .agent/:

.agent/
├── <task-id>.json          # Main task state
├── checkpoints/
│   └── <task-id>-<cp-id>.json  # Checkpoint snapshots
└── logs/
    ├── uca-combined.log    # All logs
    └── uca-error.log       # Errors only

State Contents

Each task state contains:

Task: Objective, status, priority, provider history
Plan: Steps with status, assignments, results
Checkpoints: Git commit, diff, modified files, provider context
History: Timestamped events for debugging
Verification Results: Test/build/lint outcomes
Repository State: Branch, commit, dirty files

Provider Switching

When a provider fails, UCA:

Classifies the error (rate limit, quota, auth, timeout, etc.)
Determines if failover is appropriate
Selects next provider via routing strategy
Restores task state for new provider
Continues from last checkpoint

State is never lost—the new provider receives:

Original objective
Current plan with completed steps
Modified files and git diff
Previous provider's conclusions
Failed tests/errors

Routing Strategies

Strategy	Behavior
`quality-first`	Highest priority, success rate, capabilities
`speed-first`	Lowest latency, streaming support
`cost-first`	Lowest cost per token, prefers local
`availability-first`	Healthiest, lowest error rate
`capability-based`	Best capability match for task

Error Classification

Code	Severity	Retryable	Failover
`RATE_LIMIT`	TRANSIENT	Yes	After retries
`QUOTA_EXHAUSTED`	QUOTA_RELATED	No	Immediate
`AUTHENTICATION_FAILURE`	PERMANENT	No	Immediate
`TIMEOUT`	TRANSIENT	Yes	After retries
`CONNECTION_FAILURE`	TRANSIENT	Yes	After retries
`PROVIDER_UNAVAILABLE`	TRANSIENT	Yes	After retries
`SERVER_ERROR`	TRANSIENT	Yes	After retries
`INVALID_RESPONSE`	PERMANENT	No	Immediate
`TOOL_FAILURE`	PERMANENT	No	Immediate

Git Safety

No destructive operations in Phase 1
Checkpoints record: commit hash, diff, modified files
Manual rollback: git reset --hard <checkpoint-commit>
Auto-checkpoint optional (disabled by default)

Verification

Verification runs after task completion or on demand:

# Default: tests + build
uca verify <task-id>

# Custom types
uca verify <task-id> -t tests,build,lint,typecheck

Supported verification types:

tests - npm test, vitest, jest, pytest, go test, cargo test
build - npm run build, tsc, cargo build, go build
lint - npm run lint, eslint, prettier, ruff, go vet, cargo clippy
typecheck - npx tsc --noEmit, mypy, cargo check

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Lint
npm run lint

# Run CLI in development
npm run dev -- task create "Test task"

Project Structure

src/
├── cli/              # CLI commands
├── config/           # Configuration loading/validation
├── errors/           # Error classification & retry logic
├── git/              # Git repository inspection
├── logging/          # Structured logging (Winston)
├── provider/         # Provider abstraction & adapters
│   ├── base.ts       # BaseProviderAdapter, MockProviderAdapter
│   ├── registry.ts   # ProviderRegistry, factories
│   ├── types.ts      # Provider interfaces
│   └── nemotron.ts   # Nemotron 3 Ultra provider adapter
├── routing/          # Provider routing strategies
├── state/            # Persistent task state storage
├── task/             # Task models & lifecycle
│   ├── lifecycle.ts  # TaskLifecycleManager
│   ├── models.ts     # Task, Plan, Checkpoint types
│   └── storage.ts    # StateStorage
├── verification/     # Verification engine
└── index.ts          # Public exports

Phase 1 Status (Current)

✅ Completed

Project initialization with TypeScript
Configuration system (YAML + env vars)
Provider abstraction with interfaces
Mock provider for testing
Task models (Task, Plan, Checkpoint, History)
Persistent state storage (JSON files)
Task lifecycle management
Structured logging
Git repository inspection
Verification abstraction
Error classification & retry logic
Provider routing (5 strategies)
CLI with full command set
Unit tests for core logic

🚧 Phase 2.1: Nemotron 3 Ultra (Complete)

✅ Real Nemotron 3 Ultra provider adapter via NVIDIA API
✅ Authentication via NEMOTRON_API_KEY environment variable
✅ Error classification (rate limit, quota, auth, timeout, connection, server errors)
✅ Health checks with latency reporting
✅ Streaming and tool use support
✅ Routing integration (priority 100)
✅ Mock HTTP tests (no API key required)
✅ Optional smoke test (uca smoke-test) with NEMOTRON_API_KEY
✅ CLI integration (provider list, health, smoke-test)

🟡 Phase 2.2A: Execution Boundary (In Progress)

✅ Execution abstraction (src/execution/engine.ts) defining request, output, status, and engine interface
✅ OpenCode adapter (src/execution/opencode-adapter.ts) conforming to execution abstraction with working-directory safety, timeout, and cancellation support
✅ CLI task execution command (uca task execute <task-id>) using the execution engine
✅ Unit tests for execution abstraction, adapter configuration, working-directory safety, success/failure handling, timeout/cancellation, and secret redaction
✅ Exports from src/index.ts
⚠️ Mock/demo mode only - real OpenCode CLI not available in this environment; integration requires environment-specific configuration
⚠️ No real OpenCode execution performed; adapter demonstrates the integration boundary pattern

🟢 Phase 2.2B Plans (dependent on 2.2A verification)

Real OpenCode CLI integration with working-directory validation
Timeout and cancellation handling via OpenCode CLI
Verification integration after OpenCode execution
Checkpoint creation before/after execution
Failover between Nemotron and OpenCode providers

Phase 2.3 Plans (dependent on 2.2B verification)

OpenCode as primary execution layer alongside Nemotron
Escalation logic (weak → strong provider)
Cost tracking & budgets for execution
Web UI for execution monitoring
Plugin system for custom verifications

Security

No hardcoded secrets - all credentials via environment variables
.gitignore excludes .agent/, *.log, config with secrets
API keys never logged (redacted in logs)
State files contain no credentials

License

MIT

Name		Name	Last commit message	Last commit date
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
test_results.txt		test_results.txt
tsconfig.json		tsconfig.json
verify.bat		verify.bat
verify.ps1		verify.ps1
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Universal Coding Agent (UCA)

Overview

Architecture

Core Components

Provider Tiers

Tier 1: Primary

Tier 2: Strong Cloud

Tier 3: Other Cloud / Fast

Tier 4: Local Fallback

Installation

Quick Start

Configuration

Environment Variables

CLI Commands

Task Management

Provider Management

State Management

Verification

Demo

Smoke Test (Nemotron)

Task State Persistence

State Contents

Provider Switching

Routing Strategies

Error Classification

Git Safety

Verification

Development

Project Structure

Phase 1 Status (Current)

Phase 2.3 Plans (dependent on 2.2B verification)

Security

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Universal Coding Agent (UCA)

Overview

Architecture

Core Components

Provider Tiers

Tier 1: Primary

Tier 2: Strong Cloud

Tier 3: Other Cloud / Fast

Tier 4: Local Fallback

Installation

Quick Start

Configuration

Environment Variables

CLI Commands

Task Management

Provider Management

State Management

Verification

Demo

Smoke Test (Nemotron)

Task State Persistence

State Contents

Provider Switching

Routing Strategies

Error Classification

Git Safety

Verification

Development

Project Structure

Phase 1 Status (Current)

Phase 2.3 Plans (dependent on 2.2B verification)

Security

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages