@terminusagents/agents 0.1.0

package/dist/cli/run.js

@@ -0,0 +1,98 @@
+// =============================================================================
+// TERMINUS AGENT - Run Command (Enhanced UX)
+// =============================================================================
+import chalk from 'chalk';
+import { loadConfig, configExists } from '../config/store.js';
+import { AgentClient } from '../network/client.js';
+const AGENT_EMOJIS = {
+    'travel-planner': '✈️',
+    'budget-planner': '💰',
+    'health-advisor': '🏥',
+    'fundamental-analyst': '📊',
+    'technical-analyst': '📈',
+    'crypto-advisor': '🪙',
+    'food-expert': '🍳',
+    'fitness-coach': '💪',
+    'legal-advisor': '⚖️',
+    'real-estate': '🏠',
+    'career-coach': '💼',
+    'event-planner': '🎉',
+    'tech-support': '🔧',
+    'shopping-assistant': '🛒',
+    'language-tutor': '🌍',
+};
+function printStartupBanner(config) {
+    if (!config)
+        return;
+    const emoji = AGENT_EMOJIS[config.agentType] || '🤖';
+    const provider = config.llmProvider || 'grok';
+    const providerIcon = provider === 'grok' ? '🌐' : provider === 'ollama' ? '🦙' : '🔧';
+    console.log();
+    console.log(chalk.cyan.bold('╔════════════════════════════════════════════════════════════╗'));
+    console.log(chalk.cyan.bold('║              🚀 TERMINUS AGENT STARTING                    ║'));
+    console.log(chalk.cyan.bold('╚════════════════════════════════════════════════════════════╝'));
+    console.log();
+    console.log(`   ${chalk.gray('Agent:')}          ${emoji}  ${chalk.white.bold(config.agentType)}`);
+    console.log(`   ${chalk.gray('Node ID:')}        ${chalk.cyan(config.nodeId)}`);
+    console.log(`   ${chalk.gray('Wallet:')}         ${config.wallet.slice(0, 10)}...${config.wallet.slice(-8)}`);
+    console.log(`   ${chalk.gray('LLM Provider:')}   ${providerIcon}  ${provider}${config.llmModel ? ` (${config.llmModel})` : ''}`);
+    console.log(`   ${chalk.gray('Profile:')}        ${config.networkProfile || 'local'}`);
+    console.log(`   ${chalk.gray('Control Plane:')} ${config.controlPlaneUrl}`);
+    console.log(chalk.gray('\n────────────────────────────────────────────────────────────\n'));
+    console.log(chalk.yellow('   ⏳ Connecting to Control Plane...\n'));
+}
+export async function runCommand() {
+    if (!configExists()) {
+        console.log();
+        console.log(chalk.red.bold('╔════════════════════════════════════════╗'));
+        console.log(chalk.red.bold('║         ❌ NOT CONFIGURED              ║'));
+        console.log(chalk.red.bold('╚════════════════════════════════════════╝'));
+        console.log();
+        console.log(chalk.gray('   No configuration found. Run setup first:\n'));
+        console.log(chalk.cyan('   npx terminus-agent init\n'));
+        process.exit(1);
+    }
+    const config = loadConfig();
+    if (!config) {
+        console.log(chalk.red('\n   ❌ Failed to load configuration.\n'));
+        console.log(chalk.gray('   Try reconfiguring:'));
+        console.log(chalk.cyan('   npx terminus-agent init\n'));
+        console.log(chalk.gray('   Or run diagnostics:'));
+        console.log(chalk.cyan('   npx terminus-agent doctor\n'));
+        process.exit(1);
+    }
+    if (config.networkProfile === 'mainnet' && !config.controlPlaneUrl.startsWith('wss://')) {
+        console.log(chalk.red('\n   ❌ Mainnet profile requires wss:// control-plane URL.\n'));
+        console.log(chalk.gray('   Fix with:'));
+        console.log(chalk.cyan('   npx terminus-agent init --profile mainnet\n'));
+        process.exit(1);
+    }
+    printStartupBanner(config);
+    if (!process.env.TERMINUS_WALLET_PRIVATE_KEY) {
+        console.log(chalk.yellow('   ⚠ TERMINUS_WALLET_PRIVATE_KEY is not set. Challenge-signature auth will fail in strict remote mode.\n'));
+    }
+    const client = new AgentClient(config);
+    // Handle graceful shutdown
+    process.on('SIGINT', () => {
+        console.log(chalk.yellow('\n\n   🛑 Shutting down gracefully...\n'));
+        client.disconnect();
+        console.log(chalk.gray('   Agent disconnected. Goodbye! 👋\n'));
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        console.log(chalk.yellow('\n\n   🛑 Received SIGTERM...\n'));
+        client.disconnect();
+        process.exit(0);
+    });
+    try {
+        await client.connect();
+    }
+    catch (error) {
+        console.log(chalk.red(`\n   ❌ Connection failed: ${error.message}\n`));
+        console.log(chalk.gray('   Check if Control Plane is running:'));
+        console.log(chalk.gray(`   ${config.controlPlaneUrl}\n`));
+        console.log(chalk.gray('   Run diagnostics:'));
+        console.log(chalk.cyan('   npx terminus-agent doctor\n'));
+        process.exit(1);
+    }
+}

package/dist/cli/status.d.ts

@@ -0,0 +1 @@
+export declare function statusCommand(): Promise<void>;

package/dist/cli/status.js

@@ -0,0 +1,104 @@
+// =============================================================================
+// TERMINUS AGENT - Status Command (Enhanced UX)
+// =============================================================================
+import chalk from 'chalk';
+import { loadConfig, configExists, getConfigPath } from '../config/store.js';
+import { checkOllamaAvailable } from '../llm/provider.js';
+const AGENT_EMOJIS = {
+    'travel-planner': '✈️',
+    'budget-planner': '💰',
+    'health-advisor': '🏥',
+    'fundamental-analyst': '📊',
+    'technical-analyst': '📈',
+    'crypto-advisor': '🪙',
+    'food-expert': '🍳',
+    'fitness-coach': '💪',
+    'legal-advisor': '⚖️',
+    'real-estate': '🏠',
+    'career-coach': '💼',
+    'event-planner': '🎉',
+    'tech-support': '🔧',
+    'shopping-assistant': '🛒',
+    'language-tutor': '🌍',
+};
+export async function statusCommand() {
+    console.log();
+    console.log(chalk.cyan.bold('╔════════════════════════════════════════╗'));
+    console.log(chalk.cyan.bold('║       📊 TERMINUS AGENT STATUS         ║'));
+    console.log(chalk.cyan.bold('╚════════════════════════════════════════╝'));
+    console.log();
+    if (!configExists()) {
+        console.log(chalk.red('   ❌ No configuration found.\n'));
+        console.log(chalk.gray('   Run this command to set up:'));
+        console.log(chalk.cyan('   npx terminus-agent init\n'));
+        return;
+    }
+    const config = loadConfig();
+    if (!config) {
+        console.log(chalk.red('   ❌ Failed to load configuration.\n'));
+        console.log(chalk.gray('   Try reconfiguring:'));
+        console.log(chalk.cyan('   npx terminus-agent init\n'));
+        return;
+    }
+    // Agent Info
+    console.log(chalk.yellow('┌─ Agent Configuration ─────────────────┐\n'));
+    const emoji = AGENT_EMOJIS[config.agentType] || '🤖';
+    console.log(`   ${chalk.gray('Agent Type:')}     ${emoji}  ${chalk.white.bold(config.agentType)}`);
+    console.log(`   ${chalk.gray('Node ID:')}        ${chalk.cyan(config.nodeId)}`);
+    console.log(`   ${chalk.gray('Config File:')}    ${chalk.gray(getConfigPath())}`);
+    // Wallet Info
+    console.log(chalk.yellow('\n┌─ Wallet ───────────────────────────────┐\n'));
+    const walletShort = `${config.wallet.slice(0, 10)}...${config.wallet.slice(-8)}`;
+    const runtimePrivateKey = process.env.TERMINUS_WALLET_PRIVATE_KEY?.trim();
+    console.log(`   ${chalk.gray('Address:')}        ${chalk.green(walletShort)}`);
+    console.log(`   ${chalk.gray('Private Key:')}    ${runtimePrivateKey ? chalk.green('✓ Runtime env configured') : chalk.gray('○ Missing (set TERMINUS_WALLET_PRIVATE_KEY)')}`);
+    // LLM Provider Info
+    console.log(chalk.yellow('\n┌─ LLM Provider ─────────────────────────┐\n'));
+    const provider = config.llmProvider || 'grok';
+    const providerIcon = provider === 'grok' ? '🌐' : provider === 'ollama' ? '🦙' : '🔧';
+    const providerName = provider === 'grok' ? 'Grok API (xAI Cloud)'
+        : provider === 'ollama' ? 'Ollama (Local)'
+            : 'OpenAI-Compatible';
+    console.log(`   ${chalk.gray('Provider:')}       ${providerIcon}  ${chalk.white(providerName)}`);
+    if (config.llmModel) {
+        console.log(`   ${chalk.gray('Model:')}          ${chalk.white(config.llmModel)}`);
+    }
+    if (config.llmBaseUrl) {
+        console.log(`   ${chalk.gray('Base URL:')}       ${chalk.gray(config.llmBaseUrl)}`);
+    }
+    // Provider Status Check
+    if (provider === 'ollama') {
+        const ollamaOk = await checkOllamaAvailable(config.llmBaseUrl);
+        console.log(`   ${chalk.gray('Status:')}         ${ollamaOk ? chalk.green('✓ Connected') : chalk.red('✗ Not reachable')}`);
+    }
+    else if (provider === 'grok') {
+        const hasRuntimeKey = Boolean(process.env.TERMINUS_GROK_API_KEY?.trim() || process.env.XAI_API_KEY?.trim());
+        const hasStoredKey = Boolean(config.apiKey?.trim() && config.apiKey !== '__ENV__');
+        const source = hasRuntimeKey ? 'Runtime env' : hasStoredKey ? 'Config file' : 'Missing';
+        console.log(`   ${chalk.gray('API Key:')}        ${hasRuntimeKey || hasStoredKey ? chalk.green(`✓ ${source}`) : chalk.red('✗ Missing')}`);
+    }
+    // Network Info
+    console.log(chalk.yellow('\n┌─ Network ──────────────────────────────┐\n'));
+    console.log(`   ${chalk.gray('Control Plane:')} ${chalk.cyan(config.controlPlaneUrl)}`);
+    // Test connection hint
+    const profile = config.networkProfile || (config.controlPlaneUrl.includes('localhost') ? 'local' : 'testnet');
+    if (profile === 'local') {
+        console.log(`   ${chalk.gray('Profile:')}        ${chalk.yellow('Local development')}`);
+    }
+    else if (profile === 'testnet') {
+        console.log(`   ${chalk.gray('Profile:')}        ${chalk.cyan('Base Sepolia testnet')}`);
+    }
+    else {
+        console.log(`   ${chalk.gray('Profile:')}        ${chalk.green('Base mainnet')}`);
+    }
+    if (profile === 'mainnet' && !config.controlPlaneUrl.startsWith('wss://')) {
+        console.log(`   ${chalk.gray('Transport:')}      ${chalk.red('Invalid for mainnet (requires wss://)')}`);
+    }
+    // Footer
+    console.log(chalk.gray('\n─────────────────────────────────────────\n'));
+    console.log(chalk.white.bold('📋 Quick Commands:\n'));
+    console.log(`   ${chalk.cyan('npx terminus-agent run')}    ${chalk.gray('Start the agent')}`);
+    console.log(`   ${chalk.cyan('npx terminus-agent init')}   ${chalk.gray('Reconfigure')}`);
+    console.log(`   ${chalk.cyan('npx terminus-agent doctor')} ${chalk.gray('Run readiness checks')}`);
+    console.log();
+}

package/dist/config/store.d.ts

@@ -0,0 +1,19 @@
+export type NetworkProfile = 'local' | 'testnet' | 'mainnet';
+export interface AgentConfig {
+    agentType: string;
+    wallet: string;
+    privateKey?: string;
+    apiKey: string;
+    controlPlaneUrl: string;
+    nodeId: string;
+    llmProvider?: 'grok' | 'ollama' | 'openai-compatible';
+    llmBaseUrl?: string;
+    llmModel?: string;
+    networkProfile?: NetworkProfile;
+}
+export declare function getConfigPath(): string;
+export declare function configExists(): boolean;
+export declare function loadConfig(): AgentConfig | null;
+export declare function validateConfig(config: AgentConfig): string[];
+export declare function saveConfig(config: AgentConfig): void;
+export declare function generateNodeId(agentType: string, wallet: string): string;

package/dist/config/store.js

@@ -0,0 +1,148 @@
+// =============================================================================
+// TERMINUS AGENT - Config Store
+// =============================================================================
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { randomUUID } from 'crypto';
+const CONFIG_DIR = join(homedir(), '.terminus');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+export function getConfigPath() {
+    return CONFIG_FILE;
+}
+export function configExists() {
+    return existsSync(CONFIG_FILE);
+}
+export function loadConfig() {
+    if (!existsSync(CONFIG_FILE)) {
+        return null;
+    }
+    securePermissions(CONFIG_DIR, DIR_MODE);
+    securePermissions(CONFIG_FILE, FILE_MODE);
+    try {
+        const content = readFileSync(CONFIG_FILE, 'utf-8');
+        const parsed = JSON.parse(content);
+        const normalized = normalizeConfig(parsed);
+        if (!normalized) {
+            return null;
+        }
+        const errors = validateConfig(normalized);
+        return errors.length === 0 ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function validateConfig(config) {
+    const errors = [];
+    if (!config.agentType || typeof config.agentType !== 'string') {
+        errors.push('agentType is required');
+    }
+    if (!isValidWallet(config.wallet)) {
+        errors.push('wallet must be a valid EVM address');
+    }
+    if (!config.controlPlaneUrl || !isWsUrl(config.controlPlaneUrl)) {
+        errors.push('controlPlaneUrl must start with ws:// or wss://');
+    }
+    if (!config.nodeId || typeof config.nodeId !== 'string') {
+        errors.push('nodeId is required');
+    }
+    const provider = config.llmProvider || 'grok';
+    if (provider === 'grok') {
+        const hasStoredKey = typeof config.apiKey === 'string' && config.apiKey.length > 0 && config.apiKey !== '__ENV__';
+        const hasRuntimeKey = Boolean(process.env.TERMINUS_GROK_API_KEY?.trim() || process.env.XAI_API_KEY?.trim());
+        if (!hasStoredKey && !hasRuntimeKey) {
+            errors.push('grok provider requires apiKey in config or TERMINUS_GROK_API_KEY/XAI_API_KEY env');
+        }
+    }
+    if (provider === 'openai-compatible' && !config.llmBaseUrl) {
+        errors.push('openai-compatible provider requires llmBaseUrl');
+    }
+    if (provider === 'ollama' && !config.llmBaseUrl) {
+        errors.push('ollama provider should include llmBaseUrl');
+    }
+    return errors;
+}
+export function saveConfig(config) {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: DIR_MODE });
+    }
+    securePermissions(CONFIG_DIR, DIR_MODE);
+    const provider = config.llmProvider || 'grok';
+    const normalizedApiKey = provider === 'grok'
+        ? (config.apiKey || '__ENV__')
+        : (config.apiKey || '');
+    const normalizedProfile = normalizeNetworkProfile(config.networkProfile);
+    const sanitized = {
+        agentType: config.agentType.trim(),
+        wallet: config.wallet.trim(),
+        apiKey: normalizedApiKey.trim(),
+        controlPlaneUrl: config.controlPlaneUrl.trim(),
+        nodeId: config.nodeId.trim(),
+        llmProvider: provider,
+        llmBaseUrl: config.llmBaseUrl?.trim() || undefined,
+        llmModel: config.llmModel?.trim() || undefined,
+        networkProfile: normalizedProfile,
+        privateKey: undefined,
+    };
+    const validationErrors = validateConfig(sanitized);
+    if (validationErrors.length > 0) {
+        throw new Error(`Invalid configuration: ${validationErrors.join('; ')}`);
+    }
+    writeFileSync(CONFIG_FILE, JSON.stringify(sanitized, null, 2), { mode: FILE_MODE });
+    securePermissions(CONFIG_FILE, FILE_MODE);
+}
+export function generateNodeId(agentType, wallet) {
+    // Stable readable prefix + entropy suffix for collision resistance across operators.
+    const walletPrefix = wallet.slice(2, 8).toLowerCase();
+    const suffix = randomUUID().split('-')[0];
+    return `${agentType}-${walletPrefix}-${suffix}`;
+}
+function normalizeConfig(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const value = raw;
+    const llmProvider = value.llmProvider;
+    const provider = llmProvider === 'ollama' || llmProvider === 'openai-compatible' || llmProvider === 'grok'
+        ? llmProvider
+        : 'grok';
+    const networkProfile = normalizeNetworkProfile(value.networkProfile);
+    const llmBaseUrl = typeof value.llmBaseUrl === 'string'
+        ? value.llmBaseUrl.trim()
+        : provider === 'ollama'
+            ? 'http://localhost:11434'
+            : undefined;
+    return {
+        agentType: typeof value.agentType === 'string' ? value.agentType.trim() : '',
+        wallet: typeof value.wallet === 'string' ? value.wallet.trim() : '',
+        apiKey: typeof value.apiKey === 'string' ? value.apiKey.trim() : '',
+        controlPlaneUrl: typeof value.controlPlaneUrl === 'string' ? value.controlPlaneUrl.trim() : '',
+        nodeId: typeof value.nodeId === 'string' ? value.nodeId.trim() : '',
+        llmProvider: provider,
+        llmBaseUrl,
+        llmModel: typeof value.llmModel === 'string' ? value.llmModel.trim() : undefined,
+        networkProfile,
+        privateKey: undefined,
+    };
+}
+function isWsUrl(url) {
+    return url.startsWith('ws://') || url.startsWith('wss://');
+}
+function isValidWallet(wallet) {
+    return /^0x[a-fA-F0-9]{40}$/.test(wallet);
+}
+function securePermissions(path, mode) {
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        // Some environments (e.g., Windows) may not apply POSIX modes.
+    }
+}
+function normalizeNetworkProfile(value) {
+    if (value === 'testnet' || value === 'mainnet')
+        return value;
+    return 'local';
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,61 @@
+// =============================================================================
+// TERMINUS AGENT - CLI Entry Point
+// =============================================================================
+import { program } from 'commander';
+import { initCommand } from './cli/init.js';
+import { runCommand } from './cli/run.js';
+import { statusCommand } from './cli/status.js';
+import { doctorCommand } from './cli/doctor.js';
+async function withCliErrorHandling(task) {
+    try {
+        await task();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        console.error(`\n❌ ${message}\n`);
+        process.exit(1);
+    }
+}
+program
+    .name('terminus-agent')
+    .description('Standalone agent runner for Terminus network')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('Initialize agent configuration')
+    .option('--agent-type <id>', 'Agent type id (example: travel-planner)')
+    .option('--wallet <address>', 'Wallet address for payouts')
+    .option('--llm-provider <provider>', 'grok | ollama | openai-compatible')
+    .option('--api-key <key>', 'API key for provider')
+    .option('--llm-base-url <url>', 'Provider base URL')
+    .option('--llm-model <name>', 'LLM model name')
+    .option('--control-plane-url <url>', 'Control plane websocket URL')
+    .option('--profile <profile>', 'local | testnet | mainnet')
+    .option('--yes', 'Non-interactive mode (use flags/env/defaults)')
+    .option('--force', 'Overwrite existing config without confirmation')
+    .action((options) => withCliErrorHandling(() => initCommand({
+    agentType: options.agentType,
+    wallet: options.wallet,
+    llmProvider: options.llmProvider,
+    apiKey: options.apiKey,
+    llmBaseUrl: options.llmBaseUrl,
+    llmModel: options.llmModel,
+    controlPlaneUrl: options.controlPlaneUrl,
+    profile: options.profile,
+    yes: Boolean(options.yes),
+    force: Boolean(options.force),
+})));
+program
+    .command('run')
+    .description('Start the agent and connect to Control Plane')
+    .action(() => withCliErrorHandling(runCommand));
+program
+    .command('status')
+    .description('Check agent status')
+    .action(() => withCliErrorHandling(statusCommand));
+program
+    .command('doctor')
+    .description('Run onboarding and runtime diagnostics')
+    .option('--full', 'Run connectivity/API checks in addition to static checks')
+    .action((options) => withCliErrorHandling(() => doctorCommand({ full: Boolean(options.full) })));
+program.parse();

package/dist/llm/provider.d.ts

@@ -0,0 +1,56 @@
+export interface LLMMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface LLMResponse {
+    content: string;
+    model: string;
+    tokensUsed?: number;
+}
+export interface LLMProviderConfig {
+    provider: 'grok' | 'ollama' | 'openai-compatible';
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+}
+export interface LLMProvider {
+    name: string;
+    chat(messages: LLMMessage[], options?: {
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<LLMResponse>;
+}
+export declare class GrokProvider implements LLMProvider {
+    name: string;
+    private apiKey;
+    private model;
+    constructor(apiKey: string, model?: string);
+    chat(messages: LLMMessage[], options?: {
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<LLMResponse>;
+}
+export declare class OllamaProvider implements LLMProvider {
+    name: string;
+    private baseUrl;
+    private model;
+    constructor(baseUrl?: string, model?: string);
+    chat(messages: LLMMessage[], options?: {
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<LLMResponse>;
+}
+export declare class OpenAICompatibleProvider implements LLMProvider {
+    name: string;
+    private baseUrl;
+    private apiKey;
+    private model;
+    constructor(baseUrl: string, model: string, apiKey?: string);
+    chat(messages: LLMMessage[], options?: {
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<LLMResponse>;
+}
+export declare function createLLMProvider(config: LLMProviderConfig): LLMProvider;
+export declare function checkOllamaAvailable(baseUrl?: string): Promise<boolean>;
+export declare function listOllamaModels(baseUrl?: string): Promise<string[]>;

package/dist/llm/provider.js

@@ -0,0 +1,181 @@
+// =============================================================================
+// TERMINUS AGENT - LLM Provider Interface
+// =============================================================================
+// Abstraction layer for different LLM backends.
+// Supports: xAI Grok (API), Ollama (local), OpenAI-compatible (local/cloud)
+// =============================================================================
+// =============================================================================
+// xAI Grok Provider
+// =============================================================================
+export class GrokProvider {
+    name = 'grok';
+    apiKey;
+    model;
+    constructor(apiKey, model = 'grok-4-1-fast-non-reasoning') {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async chat(messages, options) {
+        const response = await fetch('https://api.x.ai/v1/chat/completions', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: this.model,
+                messages,
+                max_tokens: options?.maxTokens ?? 1024,
+                temperature: options?.temperature ?? 0.7,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Grok API error: ${response.status} - ${error}`);
+        }
+        const data = await response.json();
+        return {
+            content: data.choices[0]?.message?.content || '',
+            model: this.model,
+            tokensUsed: data.usage?.total_tokens,
+        };
+    }
+}
+// =============================================================================
+// Ollama Provider (Local LLM)
+// =============================================================================
+export class OllamaProvider {
+    name = 'ollama';
+    baseUrl;
+    model;
+    constructor(baseUrl = 'http://localhost:11434', model = 'llama3') {
+        this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.model = model;
+    }
+    async chat(messages, options) {
+        // Ollama uses /api/chat endpoint
+        const response = await fetch(`${this.baseUrl}/api/chat`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: this.model,
+                messages,
+                stream: false,
+                options: {
+                    num_predict: options?.maxTokens ?? 1024,
+                    temperature: options?.temperature ?? 0.7,
+                },
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Ollama error: ${response.status} - ${error}`);
+        }
+        const data = await response.json();
+        return {
+            content: data.message?.content || '',
+            model: this.model,
+            tokensUsed: (data.eval_count || 0) + (data.prompt_eval_count || 0),
+        };
+    }
+}
+// =============================================================================
+// OpenAI-Compatible Provider (LM Studio, LocalAI, vLLM, etc.)
+// =============================================================================
+export class OpenAICompatibleProvider {
+    name = 'openai-compatible';
+    baseUrl;
+    apiKey;
+    model;
+    constructor(baseUrl, model, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.model = model;
+        const normalized = apiKey?.trim();
+        this.apiKey = normalized && normalized !== 'not-required' ? normalized : undefined;
+    }
+    async chat(messages, options) {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.apiKey) {
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        }
+        const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                model: this.model,
+                messages,
+                max_tokens: options?.maxTokens ?? 1024,
+                temperature: options?.temperature ?? 0.7,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`OpenAI-compatible API error: ${response.status} - ${error}`);
+        }
+        const data = await response.json();
+        return {
+            content: data.choices[0]?.message?.content || '',
+            model: this.model,
+            tokensUsed: data.usage?.total_tokens,
+        };
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+export function createLLMProvider(config) {
+    switch (config.provider) {
+        case 'grok':
+            {
+                const apiKey = resolveGrokApiKey(config.apiKey);
+                if (!apiKey) {
+                    throw new Error('Grok provider requires a key in config or TERMINUS_GROK_API_KEY/XAI_API_KEY env');
+                }
+                return new GrokProvider(apiKey, config.model);
+            }
+        case 'ollama':
+            return new OllamaProvider(config.baseUrl || 'http://localhost:11434', config.model || 'llama3');
+        case 'openai-compatible':
+            if (!config.baseUrl) {
+                throw new Error('OpenAI-compatible provider requires baseUrl');
+            }
+            return new OpenAICompatibleProvider(config.baseUrl, config.model || 'gpt-3.5-turbo', config.apiKey);
+        default:
+            throw new Error(`Unknown LLM provider: ${config.provider}`);
+    }
+}
+// =============================================================================
+// Helper to detect Ollama availability
+// =============================================================================
+export async function checkOllamaAvailable(baseUrl = 'http://localhost:11434') {
+    try {
+        const response = await fetch(`${baseUrl}/api/tags`, { method: 'GET' });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function listOllamaModels(baseUrl = 'http://localhost:11434') {
+    try {
+        const response = await fetch(`${baseUrl}/api/tags`, { method: 'GET' });
+        if (!response.ok)
+            return [];
+        const data = await response.json();
+        return data.models?.map(m => m.name) || [];
+    }
+    catch {
+        return [];
+    }
+}
+function resolveGrokApiKey(configApiKey) {
+    const key = configApiKey?.trim();
+    if (key && key !== '__ENV__')
+        return key;
+    const runtimeKey = process.env.TERMINUS_GROK_API_KEY?.trim() || process.env.XAI_API_KEY?.trim();
+    return runtimeKey || undefined;
+}