lynkr 7.2.2 → 7.2.4

package/README.md

@@ -145,26 +145,70 @@ Configure Cursor IDE to use Lynkr:
 
 📖 **[Full Cursor Setup Guide](documentation/cursor-integration.md)** | **[Embeddings Configuration](documentation/embeddings.md)**
 ---
-## Codex CLI with Lynkr                                                                                                                                                                                                                    
-Configure Codex Cli to use Lynkr                                                                                                                                                                                                                                                
-  Option 1: **Environment Variable (simplest)**                                                                                                                                                                                                          
- ``` 
-export OPENAI_BASE_URL=http://localhost:8081/v1                                                                                                                                                                                                    
-export  OPENAI_API_KEY=dummy                                                                                                                                                                                                                        
-  codex 
-  ```
-                                                                                                                                                                                                                                                     
-  Option 2: **Config File (~/.codex/config.toml)**
-  ```
-  model_provider = "lynkr"
-
-  [model_providers.lynkr]
-  name = "Lynkr Proxy"
-  base_url = "http://localhost:8081/v1"
-  env_key = "OPENAI_API_KEY"
-  ```
-
-> **Note:** For multi-step tool workflows, ensure `POLICY_TOOL_LOOP_THRESHOLD` is set high enough (default: 10).
+## Codex CLI Integration
+
+Configure [OpenAI Codex CLI](https://github.com/openai/codex) to use Lynkr as its backend.
+
+### Option 1: Environment Variables (Quick Start)
+
+```bash
+export OPENAI_BASE_URL=http://localhost:8081/v1
+export OPENAI_API_KEY=dummy
+
+codex
+```
+
+### Option 2: Config File (Recommended)
+
+Edit `~/.codex/config.toml`:
+
+```toml
+# Set Lynkr as the default provider
+model_provider = "lynkr"
+model = "gpt-4o"
+
+# Define the Lynkr provider
+[model_providers.lynkr]
+name = "Lynkr Proxy"
+base_url = "http://localhost:8081/v1"
+wire_api = "responses"
+
+# Optional: Trust your project directories
+[projects."/path/to/your/project"]
+trust_level = "trusted"
+```
+
+### Configuration Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `model_provider` | Active provider name | `"lynkr"` |
+| `model` | Model to request (mapped by Lynkr) | `"gpt-4o"`, `"claude-sonnet-4-5"` |
+| `base_url` | Lynkr endpoint | `"http://localhost:8081/v1"` |
+| `wire_api` | API format (`responses` or `chat`) | `"responses"` |
+| `trust_level` | Project trust (`trusted`, `sandboxed`) | `"trusted"` |
+
+### Remote Lynkr Server
+
+To connect Codex to a remote Lynkr instance:
+
+```toml
+[model_providers.lynkr-remote]
+name = "Remote Lynkr"
+base_url = "http://192.168.1.100:8081/v1"
+wire_api = "responses"
+```
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Same response for all queries | Disable semantic cache: `SEMANTIC_CACHE_ENABLED=false` |
+| Tool calls not executing | Increase threshold: `POLICY_TOOL_LOOP_THRESHOLD=15` |
+| Slow first request | Keep Ollama loaded: `OLLAMA_KEEP_ALIVE=24h` |
+| Connection refused | Ensure Lynkr is running: `npm start` |
+
+> **Note:** Codex uses the OpenAI Responses API format. Lynkr automatically converts this to your configured provider's format.
 
 ---
 
@@ -197,8 +241,9 @@ Lynkr supports [ClawdBot](https://github.com/openclaw/openclaw) via its OpenAI-c
 - ⚙️ **[Provider Configuration](documentation/providers.md)** - Complete setup for all 9+ providers
 - 🎯 **[Quick Start Examples](documentation/installation.md#quick-start-examples)** - Copy-paste configs
 
-### IDE Integration
+### IDE & CLI Integration
 - 🖥️ **[Claude Code CLI Setup](documentation/claude-code-cli.md)** - Connect Claude Code CLI
+- 🤖 **[Codex CLI Setup](documentation/codex-cli.md)** - Configure OpenAI Codex CLI with config.toml
 - 🎨 **[Cursor IDE Setup](documentation/cursor-integration.md)** - Full Cursor integration with troubleshooting
 - 🔍 **[Embeddings Guide](documentation/embeddings.md)** - Enable @Codebase semantic search (4 options: Ollama, llama.cpp, OpenRouter, OpenAI)
 

package/documentation/README.md

@@ -14,11 +14,12 @@ New to Lynkr? Start here:
 
 ---
 
-## IDE Integration
+## IDE & CLI Integration
 
 Connect Lynkr to your development tools:
 
 - **[Claude Code CLI Setup](claude-code-cli.md)** - Configure Claude Code CLI to use Lynkr
+- **[Codex CLI Setup](codex-cli.md)** - Configure OpenAI Codex CLI with Lynkr (config.toml, wire_api, troubleshooting)
 - **[Cursor IDE Integration](cursor-integration.md)** - Full Cursor IDE setup with troubleshooting
 - **[Embeddings Configuration](embeddings.md)** - Enable @Codebase semantic search with 4 provider options (Ollama, llama.cpp, OpenRouter, OpenAI)
 
@@ -69,7 +70,7 @@ Get help and contribute:
 ## Quick Navigation by Topic
 
 ### Setup & Configuration
-- [Installation](installation.md) | [Providers](providers.md) | [Claude Code](claude-code-cli.md) | [Cursor](cursor-integration.md) | [Embeddings](embeddings.md)
+- [Installation](installation.md) | [Providers](providers.md) | [Claude Code](claude-code-cli.md) | [Codex CLI](codex-cli.md) | [Cursor](cursor-integration.md) | [Embeddings](embeddings.md)
 
 ### Features & Optimization
 - [Features](features.md) | [Memory System](memory-system.md) | [Token Optimization](token-optimization.md) | [Headroom](headroom.md) | [Tools](tools.md)
@@ -87,7 +88,7 @@ Get help and contribute:
 This documentation is organized into focused guides:
 
 1. **Getting Started** - Installation and basic configuration
-2. **IDE Integration** - Connect to Claude Code and Cursor
+2. **IDE & CLI Integration** - Connect to Claude Code, Codex CLI, and Cursor
 3. **Core Features** - Deep dives into capabilities
 4. **Deployment** - Production setup and operations
 5. **Support** - Troubleshooting and community resources

package/documentation/codex-cli.md

@@ -0,0 +1,397 @@
+# Codex CLI Integration
+
+This guide explains how to configure [OpenAI Codex CLI](https://github.com/openai/codex) to use Lynkr as its backend, enabling you to use any LLM provider (Ollama, Azure OpenAI, Bedrock, Databricks, etc.) with Codex.
+
+---
+
+## Overview
+
+Codex CLI is OpenAI's terminal-based AI coding assistant. By routing it through Lynkr, you can:
+
+- Use **local models** (Ollama, llama.cpp, LM Studio) for free, private coding assistance
+- Access **enterprise providers** (Azure OpenAI, Databricks, AWS Bedrock)
+- Benefit from Lynkr's **token optimization** and **caching** features
+- Switch between providers without changing Codex configuration
+
+---
+
+## Quick Start
+
+### Option 1: Environment Variables
+
+The fastest way to get started:
+
+```bash
+# Set Lynkr as the OpenAI endpoint
+export OPENAI_BASE_URL=http://localhost:8081/v1
+export OPENAI_API_KEY=dummy
+
+# Start Lynkr (in another terminal)
+cd /path/to/lynkr && npm start
+
+# Run Codex
+codex
+```
+
+### Option 2: Config File (Recommended)
+
+For persistent configuration, edit `~/.codex/config.toml`:
+
+```toml
+# Set Lynkr as the default provider
+model_provider = "lynkr"
+model = "gpt-4o"
+
+# Define the Lynkr provider
+[model_providers.lynkr]
+name = "Lynkr Proxy"
+base_url = "http://localhost:8081/v1"
+wire_api = "responses"
+
+# Optional: Trust your project directories for tool execution
+[projects."/path/to/your/project"]
+trust_level = "trusted"
+```
+
+---
+
+## Complete Configuration Reference
+
+### Full config.toml Example
+
+```toml
+# =============================================================================
+# Codex CLI Configuration for Lynkr
+# Location: ~/.codex/config.toml
+# =============================================================================
+
+# Active provider (must match a key in [model_providers])
+model_provider = "lynkr"
+
+# Model to request (Lynkr maps this to your configured provider)
+model = "gpt-4o"
+
+# Personality affects response style: default, pragmatic, concise, educational
+personality = "pragmatic"
+
+# =============================================================================
+# Lynkr Provider Definition
+# =============================================================================
+
+[model_providers.lynkr]
+name = "Lynkr Proxy"
+base_url = "http://localhost:8081/v1"
+wire_api = "responses"
+
+# Alternative: Use chat completions API instead of responses API
+# wire_api = "chat"
+
+# =============================================================================
+# Remote Lynkr Server (Optional)
+# =============================================================================
+
+[model_providers.lynkr-remote]
+name = "Remote Lynkr (GPU Server)"
+base_url = "http://192.168.1.100:8081/v1"
+wire_api = "responses"
+
+# =============================================================================
+# Project Trust Levels
+# =============================================================================
+# trusted    - Full tool execution allowed
+# sandboxed  - Restricted tool execution
+# untrusted  - No tool execution (default for new projects)
+
+[projects."/Users/yourname/work"]
+trust_level = "trusted"
+
+[projects."/Users/yourname/personal"]
+trust_level = "trusted"
+
+# =============================================================================
+# Agent Configuration (Optional)
+# =============================================================================
+
+[agent]
+enabled = true
+
+# =============================================================================
+# Skills Configuration (Optional)
+# =============================================================================
+
+[skills]
+enabled = true
+```
+
+---
+
+## Configuration Options
+
+### Provider Options
+
+| Option | Description | Values |
+|--------|-------------|--------|
+| `model_provider` | Active provider name | `"lynkr"`, `"openai"`, etc. |
+| `model` | Model to request | `"gpt-4o"`, `"claude-sonnet-4-5"`, etc. |
+| `personality` | Response style | `"default"`, `"pragmatic"`, `"concise"`, `"educational"` |
+
+### Model Provider Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `name` | Display name | `"Lynkr Proxy"` |
+| `base_url` | API endpoint URL | `"http://localhost:8081/v1"` |
+| `wire_api` | API format | `"responses"` (recommended) or `"chat"` |
+| `env_key` | Environment variable for API key | `"OPENAI_API_KEY"` |
+
+### Project Options
+
+| Option | Description | Values |
+|--------|-------------|--------|
+| `trust_level` | Tool execution permissions | `"trusted"`, `"sandboxed"`, `"untrusted"` |
+
+---
+
+## Wire API Formats
+
+Codex supports two API formats:
+
+### Responses API (Recommended)
+
+```toml
+wire_api = "responses"
+```
+
+- Uses OpenAI's newer Responses API format
+- Better support for multi-turn conversations
+- Recommended for Lynkr integration
+
+### Chat Completions API
+
+```toml
+wire_api = "chat"
+```
+
+- Uses standard OpenAI Chat Completions format
+- Broader compatibility with proxies
+- Use if you encounter issues with `responses`
+
+---
+
+## Remote Server Configuration
+
+Connect Codex to a Lynkr instance running on another machine:
+
+### On the Remote Server
+
+```bash
+# Edit .env to allow remote connections
+PORT=8081
+
+# Start Lynkr
+npm start
+```
+
+### On Your Local Machine
+
+```toml
+# ~/.codex/config.toml
+model_provider = "lynkr-remote"
+
+[model_providers.lynkr-remote]
+name = "Remote Lynkr"
+base_url = "http://192.168.1.100:8081/v1"
+wire_api = "responses"
+```
+
+---
+
+## Lynkr Configuration for Codex
+
+Optimize Lynkr for Codex usage by configuring these `.env` settings:
+
+### Recommended Settings
+
+```bash
+# =============================================================================
+# Lynkr .env Configuration for Codex
+# =============================================================================
+
+# Your LLM provider (Codex works with all Lynkr providers)
+MODEL_PROVIDER=azure-openai
+# MODEL_PROVIDER=ollama
+# MODEL_PROVIDER=bedrock
+
+# Tool execution mode - let Codex handle tools locally
+TOOL_EXECUTION_MODE=client
+
+# Increase tool loop threshold for complex multi-step tasks
+POLICY_TOOL_LOOP_THRESHOLD=15
+
+# Semantic cache (disable if getting repeated responses)
+SEMANTIC_CACHE_ENABLED=false
+
+# Or keep enabled with proper embeddings for faster responses
+# SEMANTIC_CACHE_ENABLED=true
+# OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
+```
+
+### Provider-Specific Examples
+
+**Azure OpenAI:**
+```bash
+MODEL_PROVIDER=azure-openai
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/openai/responses?api-version=2025-04-01-preview
+AZURE_OPENAI_API_KEY=your-key
+AZURE_OPENAI_DEPLOYMENT=gpt-4o
+```
+
+**Ollama (Local, Free):**
+```bash
+MODEL_PROVIDER=ollama
+OLLAMA_MODEL=qwen2.5-coder:latest
+OLLAMA_ENDPOINT=http://localhost:11434
+```
+
+**AWS Bedrock:**
+```bash
+MODEL_PROVIDER=bedrock
+AWS_BEDROCK_API_KEY=your-key
+AWS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Same response for all queries | Semantic cache matching on system prompt | Set `SEMANTIC_CACHE_ENABLED=false` in Lynkr `.env` |
+| Tool calls not executing | Tool loop threshold too low | Set `POLICY_TOOL_LOOP_THRESHOLD=15` |
+| Connection refused | Lynkr not running | Run `npm start` in Lynkr directory |
+| Slow first request | Cold start / model loading | Set `OLLAMA_KEEP_ALIVE=24h` for Ollama |
+| "Invalid API key" errors | API key not set | Set `OPENAI_API_KEY=dummy` (Lynkr doesn't validate) |
+| Streaming issues | Wire API mismatch | Try `wire_api = "chat"` instead of `"responses"` |
+
+### Debug Mode
+
+Enable verbose logging to diagnose issues:
+
+```bash
+# In Lynkr .env
+LOG_LEVEL=debug
+
+# Restart Lynkr and watch logs
+npm start
+```
+
+### Verify Connection
+
+Test that Codex can reach Lynkr:
+
+```bash
+curl http://localhost:8081/health
+# Expected: {"status":"ok",...}
+```
+
+---
+
+## Model Mapping
+
+When you specify a model in Codex, Lynkr maps it to your configured provider:
+
+| Codex Model | Lynkr Mapping |
+|-------------|---------------|
+| `gpt-4o` | Uses your `MODEL_PROVIDER` default model |
+| `gpt-4o-mini` | Maps to smaller/cheaper model variant |
+| `claude-sonnet-4-5` | Routes to Anthropic-compatible provider |
+| `claude-opus-4-5` | Routes to most capable model |
+
+The actual model used depends on your Lynkr provider configuration.
+
+---
+
+## Architecture
+
+```
+┌─────────────────┐
+│   Codex CLI     │  Terminal AI coding assistant
+│   (Your Machine)│
+└────────┬────────┘
+         │ OpenAI Responses API
+         │ http://localhost:8081/v1
+         ▼
+┌─────────────────┐
+│     Lynkr       │  Universal LLM proxy
+│   Port 8081     │
+│                 │
+│ • Format conv.  │  Converts between API formats
+│ • Token optim.  │  Reduces costs 60-80%
+│ • Caching       │  Semantic + prompt caching
+│ • Tool routing  │  Server or client execution
+└────────┬────────┘
+         │
+    ┌────┴────┬──────────┬──────────┐
+    ▼         ▼          ▼          ▼
+┌───────┐ ┌───────┐ ┌─────────┐ ┌─────────┐
+│Ollama │ │Azure  │ │Bedrock  │ │Databricks│
+│(Free) │ │OpenAI │ │(100+)   │ │         │
+└───────┘ └───────┘ └─────────┘ └─────────┘
+```
+
+---
+
+## Tips & Best Practices
+
+### 1. Use Trusted Projects
+
+For frequently used projects, set trust level to avoid repeated permission prompts:
+
+```toml
+[projects."/Users/yourname/main-project"]
+trust_level = "trusted"
+```
+
+### 2. Configure Personality
+
+Choose a personality that matches your workflow:
+
+- `pragmatic` - Direct, solution-focused responses
+- `concise` - Minimal explanations, code-focused
+- `educational` - Detailed explanations, good for learning
+- `default` - Balanced approach
+
+### 3. Keep Models Loaded
+
+Prevent slow first requests with Ollama:
+
+```bash
+# macOS
+launchctl setenv OLLAMA_KEEP_ALIVE "24h"
+
+# Linux/Windows
+export OLLAMA_KEEP_ALIVE=24h
+```
+
+### 4. Monitor Token Usage
+
+Check Lynkr metrics to monitor usage:
+
+```bash
+curl http://localhost:8081/metrics/token-usage
+```
+
+---
+
+## Related Documentation
+
+- **[Installation Guide](installation.md)** - Install and configure Lynkr
+- **[Provider Configuration](providers.md)** - Configure your LLM provider
+- **[Token Optimization](token-optimization.md)** - Reduce costs with Lynkr
+- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions
+
+---
+
+**Need help?** Visit [GitHub Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions) or check the [FAQ](faq.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkr",
-  "version": "7.2.2",
+  "version": "7.2.4",
   "description": "Self-hosted Claude Code & Cursor proxy with Databricks,AWS BedRock,Azure  adapters, openrouter, Ollama,llamacpp,LM Studio, workspace tooling, and MCP integration.",
   "main": "index.js",
   "bin": {
@@ -8,9 +8,9 @@
     "lynkr-setup": "./scripts/setup.js"
   },
   "scripts": {
-    "prestart": "docker compose --profile headroom up -d headroom 2>/dev/null || echo 'Headroom container not started (Docker may not be running)'",
+    "prestart": "node -e \"if(process.env.HEADROOM_ENABLED==='true'&&process.env.HEADROOM_DOCKER_ENABLED!=='false'){process.exit(0)}else{process.exit(1)}\" && docker compose --profile headroom up -d headroom 2>/dev/null || echo 'Headroom skipped (disabled or Docker not running)'",
     "start": "node index.js 2>&1 | npx pino-pretty --sync",
-    "stop": "docker compose --profile headroom down",
+    "stop": "node -e \"if(process.env.HEADROOM_ENABLED==='true'&&process.env.HEADROOM_DOCKER_ENABLED!=='false'){process.exit(0)}else{process.exit(1)}\" && docker compose --profile headroom down || echo 'Headroom skipped (disabled or Docker not running)'",
     "dev": "nodemon index.js",
     "lint": "eslint src index.js",
     "test": "npm run test:unit && npm run test:performance",

package/src/clients/retry.js

@@ -10,7 +10,7 @@ const DEFAULT_CONFIG = {
   backoffMultiplier: 2,
   jitterFactor: 0.1, // 10% jitter
   retryableStatuses: [429, 500, 502, 503, 504],
-  retryableErrors: ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ENETUNREACH'],
+  retryableErrors: ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ENETUNREACH', 'ECONNREFUSED'],
 };
 
 /**
@@ -44,6 +44,11 @@ function isRetryable(error, response, config) {
     return true;
   }
 
+  // Check nested cause (Node undici wraps connection errors as TypeError)
+  if (error && error.cause?.code && config.retryableErrors.includes(error.cause.code)) {
+    return true;
+  }
+
   // Check for network errors
   if (error && (error.name === 'FetchError' || error.name === 'AbortError')) {
     return true;

package/src/orchestrator/index.js

@@ -1694,7 +1694,33 @@ IMPORTANT TOOL USAGE RULES:
     });
   }
 
-  const databricksResponse = await invokeModel(cleanPayload);
+  let databricksResponse;
+  try {
+    databricksResponse = await invokeModel(cleanPayload);
+  } catch (modelError) {
+    const isConnectionError = modelError.cause?.code === 'ECONNREFUSED'
+      || modelError.message?.includes('fetch failed')
+      || modelError.code === 'ECONNREFUSED';
+    if (isConnectionError) {
+      logger.error(`Provider ${providerType} is unreachable (connection refused). Is it running?`);
+      return {
+        response: {
+          status: 503,
+          body: {
+            error: {
+              type: "provider_unreachable",
+              message: `Provider ${providerType} is unreachable. Is the service running?`,
+            },
+          },
+          terminationReason: "provider_unreachable",
+        },
+        steps,
+        durationMs: Date.now() - start,
+        terminationReason: "provider_unreachable",
+      };
+    }
+    throw modelError;
+  }
 
   // Extract and log actual token usage
   const actualUsage = databricksResponse.ok && config.tokenTracking?.enabled !== false

package/src/tools/smart-selection.js

@@ -9,6 +9,9 @@
 
 const logger = require('../logger');
 
+// Strip system-reminder blocks injected by the CLI before classification
+const SYSTEM_REMINDER_PATTERN = /<system-reminder>[\s\S]*?<\/system-reminder>/g;
+
 // Pre-compiled regex patterns for performance (avoid recompiling on every request)
 const GREETING_PATTERN = /^(hi|hello|hey|good morning|good afternoon|good evening|howdy|greetings|sup|yo)[\s\.\!\?]*$/i;
 const QUESTION_PATTERN = /^(what is|what's|how does|when|where|why|explain|define|tell me about|can you explain)/i;
@@ -190,7 +193,10 @@ function classifyRequestType(payload) {
     return { type: 'coding', confidence: 0.5, keywords: [] };
   }
 
-  const content = extractContent(lastMessage);
+  const rawContent = extractContent(lastMessage);
+  // Strip <system-reminder> blocks before classification to prevent
+  // CLI-injected keywords (search, explain, documentation) from polluting results
+  const content = rawContent.replace(SYSTEM_REMINDER_PATTERN, '').trim();
   const contentLower = content.toLowerCase();
   const messageCount = payload.messages?.length ?? 0;