feat: Add OpenRouter API support for cloud-based AI models

[konard]

Summary

This PR implements OpenRouter API support for Hasyx, enabling access to a wide variety of cloud-based AI models from different providers (Google, Anthropic, Mistral AI, etc.) through a single unified API.

Closes #22

Problem

Issue #22 requested OpenRouter API support as part of the broader AI integration (issue #19). The OpenRouter provider implementation was already present in the codebase but was not exported from the main library, making it impossible for applications to import and use this functionality.

Solution

Added comprehensive exports to lib/server.ts for the complete AI module, enabling public access to OpenRouter and other AI providers.

Changes

1. AI Module Exports (lib/server.ts):

   • Core components: AI, Dialog, DialogParser, Tool, Tooler
   • AI Providers: OllamaProvider, OpenRouterProvider, ApiRouteProvider
   • AI Tools: ExecJSTool, ExecTsxTool, TerminalTool
   • Utilities: createSystemPrompt, printConsole, terminal/telegram helpers
   • Handlers: api-dialog

2. Cleanup:

   • Removed accidentally committed CLAUDE.md temporary file

Implementation Details

OpenRouter Provider Features

The OpenRouter provider (lib/ai/providers/openrouter.ts) includes:

• Rate Limiting: Intelligent rate limiting based on OpenRouter API headers and tier information
• Sequential Request Queue: Promise-based queue system to prevent rate limit errors
• Automatic Retry: Exponential backoff for 429 errors with configurable retries
• Streaming Support: Full streaming API support for real-time responses
• Timeout Handling: Configurable request timeouts with abort controller
• Free Tier Support: Optimized defaults for free tier usage (deepseek/deepseek-chat-v3-0324:free)

CLI Integration

The ask command (lib/ask.ts) already supports OpenRouter:

# Use OpenRouter with default model
npm run ask -- -e "Your question here"

# Use specific model
npm run ask -- -e "Your question" --model anthropic/claude-3.5-sonnet

# Interactive mode
npm run ask

Programmatic Usage

Applications can now import and use the AI module:

import { Dialog, OpenRouterProvider, ExecJSTool, TerminalTool } from 'hasyx/lib/server';

const dialog = new Dialog({
  provider: new OpenRouterProvider({ 
    token: process.env.OPENROUTER_API_KEY,
    model: 'deepseek/deepseek-chat-v3-0324:free'
  }),
  tools: [new ExecJSTool(), new TerminalTool()],
  systemPrompt: 'You are a helpful AI assistant.',
  onChange: (event) => {
    console.log('[AI Event]', event.type);
  }
});

await dialog.ask({ role: 'user', content: 'Calculate factorial of 5' });

Testing

The OpenRouter provider includes comprehensive tests:

• Unit tests for initialization, rate limiting, and configuration
• Integration tests with real OpenRouter API (skipped when API key unavailable)
• Tests for rate limit handling, streaming, and error handling

Test file: lib/ai/providers/openrouter.test.ts

Documentation

Complete documentation is available:

• OPENROUTER.md - OpenRouter setup and usage
• AI.md - AI module architecture
• ASK.md - Ask CLI usage

Configuration

To use OpenRouter, configure via npx hasyx config:

1. Run npx hasyx config
2. Set OPENROUTER_API_KEY with your OpenRouter API key
3. The .env file is auto-generated (do not edit manually)

Impact

This change enables:

• Access to 100+ AI models through a single API
• Both local (Ollama) and cloud (OpenRouter) model support
• Event-driven AI workflows with tool execution
• Custom AI assistants with Hasyx

Related Issues

• AI #19 - AI (umbrella issue for AI module)
• Ask #20 - Ask CLI tool
• Ollama #21 - Ollama provider support
• OpenRouter #22 - OpenRouter provider support (this PR)

---

🤖 Generated with Claude Code

[vercel]

@konard is attempting to deploy a commit to the ivansglazunov's projects Team on Vercel.

A member of the Team first needs to authorize it.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

📎 Log file uploaded as GitHub Gist (391KB)
🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.