codehere 0.3.0 → 0.5.0-alpha.0

package/README.md

@@ -1,6 +1,10 @@
 # codehere
 
-> Enterprise-grade AI coding assistant with local embeddings and semantic search
+> A governed, measurable AI coding OS that plans, edits, validates, and measures its own reliability. Every change is traceable, reviewable, and scored – so you can trust it on real code.
+
+Codehere is a multi-agent coding system designed for solo developers and small teams. Unlike simple AI assistants, Codehere orchestrates specialized agents (Planning, Execution, Validation) to handle complex tasks while maintaining full transparency and control through review gates and trust metrics.
+
+**📖 [Documentation →](docs/OVERVIEW.md)** | **🗺️ [Roadmap →](docs/ROADMAP.md)**
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green)](https://nodejs.org/)
@@ -50,19 +54,69 @@ codehere index
 codehere "How does authentication work?"
 ```
 
+### Switching Providers
+
+Codehere supports multiple AI providers. By default, it uses **Cohere** (no configuration needed).
+
+**Quick Options:**
+
+**Default (Cohere):**
+```bash
+export COHERE_API_KEY=your-key
+codehere status
+```
+
+**OpenAI:**
+```bash
+export CODEHERE_AI_PROVIDER=openai
+export CODEHERE_OPENAI_API_KEY=sk-...
+codehere status
+```
+
+**OpenRouter (400+ Models):**
+```bash
+export CODEHERE_AI_PROVIDER=openrouter
+export OPENROUTER_API_KEY=sk-or-v1-...
+codehere status
+```
+
+**Local LLM (Ollama, LM Studio):**
+```bash
+export CODEHERE_AI_PROVIDER=local
+export CODEHERE_LOCAL_BASE_URL=http://localhost:11434
+codehere status
+```
+
+**Fake Mode (Testing/Demo):**
+```bash
+export CODEHERE_FAKE_AI=1
+codehere status  # No API calls, deterministic outputs
+```
+
+**Per-Operation Routing:**
+
+Create `.codehere/providers.json` to route different operations to different providers. See [docs/PROVIDERS_QUICKSTART.md](docs/PROVIDERS_QUICKSTART.md) for complete setup guide.
+
+**📖 [Complete Provider Guide →](docs/PROVIDERS_QUICKSTART.md)**
+
 **Using Codehere:**
 
 ```bash
 # Natural language queries (unified command)
 codehere "explain this function"
-codehere "add error handling to src/utils.ts"
-codehere "refactor user service to use dependency injection"
+codehere "add error handling to src/utils.ts" --review
+codehere "refactor user service to use dependency injection" --review
 
 # Or use explicit commands
 codehere ask "How does authentication work?"
 codehere explain src/utils.ts
 codehere plan "implement user authentication system"
-codehere orchestrate "add comprehensive logging"
+codehere orchestrate "add comprehensive logging" --review
+
+# Validation Mode: Review before applying changes
+codehere fix src/utils.ts "Add error handling" --review
+codehere orchestrate "Add authentication" --review
+codehere plan "Refactor to DI" --execute --review
 
 # Manage configuration
 codehere config                    # Show current configuration
@@ -74,57 +128,177 @@ codehere --help
 codehere help <command>
 ```
 
+> **💡 Tip**: Use `--review` on destructive operations (edit, orchestrate, plan --execute) to see summaries and approve changes before they're applied. This builds trust and prevents mistakes.
+
+### 🔍 Validation Mode & Trust Scores
+
+Validation Mode makes every agent operation traceable, reviewable, and measurable. Use `--review` to pause before applying changes, review structured summaries, and approve or reject. Every operation generates feedback that feeds into trust scores.
+
+**How it works:**
+- Run commands with `--review` to enable feedback capture
+- Review summaries show files changed, validation checks, and risk assessment
+- Feedback is stored locally in `data/feedback/agent-feedback.jsonl`
+- Trust scores are computed per agent: `(approved_success_runs / total_runs) × 100`
+
+**Example:**
+```bash
+# Enable review & feedback capture
+CODEHERE_AUTO_APPROVE=true codehere fix src/file.ts "add input validation" --review
+
+# View trust scores
+npm run analyze:feedback
+codehere status
+```
+
+**Optional:** Configure minimum trust thresholds via `config/trust-config.json` to highlight agents that need more validation (warnings only, non-blocking).
+
+**For CI/dashboards:** Export trust and feedback stats as JSON:
+- `npm run analyze:feedback -- --json`
+- `codehere status --json`
+
+**For CI gates:** Enforce minimum trust scores:
+- `npm run check:trust` - Fails if any agent is below its configured threshold
+
+**📖 [Complete Guide →](docs/VALIDATION_MODE.md)**
+
+### 💬 Feedback Collection
+
+Codehere collects feedback after operations to improve responses. In interactive mode, you'll see a prompt asking for feedback. In non-interactive mode (scripts, CI), you can provide feedback via environment variables:
+
+```bash
+# Positive feedback (thumbs up)
+CODEHERE_FEEDBACK=y codehere ask "What is main?"
+
+# Negative feedback (thumbs down)
+CODEHERE_FEEDBACK=n codehere ask "What is main?"
+
+# Request refinement with message
+CODEHERE_FEEDBACK=r CODEHERE_FEEDBACK_MESSAGE="Add more examples" codehere ask "What is main?"
+
+# Alternative values
+CODEHERE_FEEDBACK=positive codehere ask "What is main?"
+CODEHERE_FEEDBACK=negative codehere ask "What is main?"
+CODEHERE_FEEDBACK=yes codehere ask "What is main?"
+CODEHERE_FEEDBACK=no codehere ask "What is main?"
+```
+
+**Environment Variables:**
+- `CODEHERE_FEEDBACK`: `y`/`yes`/`positive` (thumbs up), `n`/`no`/`negative` (thumbs down), `r`/`refine`/`refinement` (request refinement)
+- `CODEHERE_FEEDBACK_MESSAGE`: Optional message for refinement requests
+
 ## ✨ Features
 
-### 🧠 Semantic Code Search
-- Builds local embedding index using Cohere's embedding API
-- Uses cosine similarity to find relevant code chunks
-- Enhanced context with file relationships and dependencies
+### 🎯 Why Codehere vs Other Coding Agents?
+
+- **Explicit Review Gates**: Unlike agents that apply changes immediately, Codehere uses `--review` to pause, show summaries, and request approval before modifying files
+- **Trust Scores & Analytics**: Every agent run is scored. Run `npm run analyze:feedback` to see which agents are most reliable in your workflow
+- **Full Traceability**: Every operation generates a structured TraceSummary showing files changed, reasoning steps, validation checks, and risk assessment
+- **Governed Multi-Agent System**: Specialized agents (Planning, Execution, Validation) work together with full instrumentation – not a black box
+- **Privacy-First Feedback**: All feedback stored locally in JSONL. No telemetry. Opt-out available. Your data stays yours
+
+### 🤖 Multi-Agent Orchestration
+
+- **Planning Agent**: Breaks complex tasks into hierarchical sub-plans with risk assessment
+- **Execution Agent**: Executes plans step-by-step, tracks file changes, handles rollbacks
+- **Validation Agent**: Runs compilation checks, tests, and quality analysis before completion
+- **Intelligent Router**: Automatically selects the right workflow (simple, ReAct, or multi-agent) based on query complexity
+- **Multi-Agent Orchestrator**: Coordinates all agents, aggregates summaries, provides unified traceability
+
+### 🛡️ Validation Mode & Review Gates
+
+- **`--review` Flag**: Pause before applying changes, review structured summaries, approve or reject
+- **TraceSummary Generation**: Every agent run produces a detailed summary (files, steps, checks, metrics, risk)
+- **Composite Summaries**: Multi-agent operations merge all agent summaries into one reviewable report
+- **Risk Assessment**: Automatic risk level calculation (low/medium/high/critical) with clear reasons
+- **Environment Controls**: `CODEHERE_AUTO_APPROVE=true` for CI/CD, `CODEHERE_FEEDBACK_OPT_OUT=true` for privacy
 
-### 🤖 AI-Powered Assistance
+### 📊 Trust & Reliability Metrics
+
+- **Agent Feedback Analytics**: Run `npm run analyze:feedback` to see trust scores, success rates, and operation breakdowns
+- **Trust Score Calculation**: `(approved_success_runs / total_runs) × 100` – measurable agent reliability
+- **Outcome Tracking**: Success, failure, partial_success, cancelled, error – complete visibility
+- **User Action Tracking**: Approved, rejected, modified – understand how users interact with agents
+
+### 🧠 Semantic Code Search & Context
+
+- Builds local embedding index using Cohere's embedding API
+- Enhanced context with file relationships and dependencies (15+ chunks)
 - Context-aware responses using retrieved code
-- Natural language code explanations
-- Intelligent code editing with unified diff generation
-- Enhanced context understanding (15+ chunks)
+- Natural language code explanations and intelligent editing
+
+### 🔒 Security & Privacy
 
-### 🛡️ Enterprise Safety
-- **Line limit enforcement** - Maximum 50 lines changed per edit
-- **Restricted folders** - Protect critical directories (infra/, billing/)
-- **Single-file edits** - Prevent accidental multi-file changes
-- **Audit logging** - Every operation logged to JSONL
+- **Local-first**: All embeddings and feedback stored locally in SQLite
+- **No code transmission**: Only chunks sent to API for embedding, never full files
+- **Audit trail**: Complete JSONL logging of all operations
+- **Policy enforcement**: Line limits, restricted folders, single-file safety checks
+- **Privacy controls**: Opt-out available, anonymization by default
 
 ### 🔧 Enterprise Reliability
-- **Automatic error recovery** - Retry with exponential backoff
-- **Circuit breaker** - Protects against API failures
-- **Health monitoring** - System health checks and metrics
-- **24/7 operation ready** - Robust error handling
 
-### 📦 Production Ready
-- Fully tested end-to-end
-- TypeScript for type safety
-- SQLite for local vector storage
-- Comprehensive error handling
+- **Automatic error recovery**: Retry with exponential backoff
+- **Circuit breaker**: Protects against API failures
+- **Health monitoring**: System health checks and metrics
+- **24/7 operation ready**: Robust error handling and graceful degradation
 
 ## 🏗️ Architecture
 
+### Multi-Agent System
+
 ```
-┌─────────────┐
-│   CLI Tool  │
-└──────┬──────┘
-       │
-       ├─→ Index: Scan → Chunk → Embed → Store (SQLite)
-       ├─→ Ask: Query → Embed → Search (15 chunks) → Chat
-       ├─→ Explain: Read → Chat
-       ├─→ Fix: Read → Generate Diff → Policy Check → Apply
-       └─→ Health: System Status → Metrics
+┌─────────────────────────────────────────────────┐
+│              Intelligent Router                  │
+│  (Routes queries to appropriate workflow)        │
+└───────────────┬─────────────────────────────────┘
+                │
+    ┌───────────┼───────────┐
+    │           │           │
+┌───▼───┐  ┌───▼────┐  ┌───▼──────────────┐
+│ Simple│  │ ReAct  │  │ Multi-Agent      │
+│ Work  │  │ Agent  │  │ Orchestrator     │
+└───────┘  └────────┘  └──────┬───────────┘
+                               │
+                    ┌──────────┼──────────┐
+                    │          │          │
+            ┌───────▼──┐  ┌───▼──────┐  ┌▼────────────┐
+            │ Planning │  │Execution │  │ Validation  │
+            │  Agent   │→ │  Agent   │→ │   Agent     │
+            └──────────┘  └──────────┘  └─────────────┘
+                    │          │          │
+                    └──────────┼──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │ Composite Summary   │
+                    │ + Review Gate       │
+                    │ + AgentFeedback     │
+                    └─────────────────────┘
 ```
 
+### Core Components
+
+- **Intelligent Router**: Analyzes query intent, selects optimal workflow
+- **Planning Agent**: Creates hierarchical plans with risk assessment
+- **Execution Agent**: Executes plans, tracks changes, handles rollbacks
+- **Validation Agent**: Compiles, tests, analyzes quality
+- **Multi-Agent Orchestrator**: Coordinates all agents, creates unified run context
+- **Validation Layer**: TraceSummary generation, AgentFeedback recording, review handler
+
+### Data Flow
+
+1. **Query** → Router determines intent
+2. **Planning** → Agent creates plan with complexity tracking
+3. **Execution** → Agent executes with file change tracking
+4. **Validation** → Agent runs checks with pass/fail tracking
+5. **Summary** → Composite summary aggregated from all agents
+6. **Review** → User reviews summary, approves/rejects
+7. **Feedback** → Outcome recorded to local JSONL, trust scores updated
+
 **Tech Stack:**
 - **TypeScript** - Type-safe development
-- **Cohere AI** - Embeddings and chat completion
-- **SQL.js** - In-memory SQLite for vector storage
+- **Cohere AI** - Embeddings, chat completion, reranking
+- **SQLite** - Local vector storage and feedback persistence
 - **Commander.js** - CLI interface
-- **Tiktoken** - Token counting and chunking
+- **Clean Architecture** - Domain, application, infrastructure layers
 
 ## 📊 Performance
 
@@ -133,12 +307,26 @@ codehere help <command>
 - **Chat:** ~2-5 seconds per query
 - **Storage:** ~13KB per chunk (1024-dim embeddings)
 
+## 🎯 Trust & Reliability Dashboard
+
+Codehere measures and reports its own reliability. Every operation with `--review` generates feedback that feeds into trust scores.
+
+### Run Analytics
+
+```bash
+npm run analyze:feedback
+```
+
+Shows trust scores per agent, success rates, and operation breakdowns. See `docs/VALIDATION_MODE_USAGE_GUIDE.md` for details.
+
 ## 🔒 Security & Privacy
 
-- **Local-first:** All embeddings stored locally in SQLite
-- **No code transmission:** Only chunks sent to API for embedding
-- **Audit trail:** Complete JSONL logging of all operations
-- **Policy enforcement:** Multiple safety checks before applying changes
+- **Local-first storage:** All embeddings and feedback stored locally in SQLite – nothing leaves your machine
+- **No code transmission:** Only chunks sent to API for embedding, never full files
+- **Privacy-first feedback:** All AgentFeedback stored locally in `data/feedback/agent-feedback.jsonl`. No telemetry. Opt out with `CODEHERE_FEEDBACK_OPT_OUT=true`
+- **Audit trail:** Complete JSONL logging of all operations with full traceability
+- **Policy enforcement:** Line limits, restricted folders, single-file safety checks
+- **Review gates:** Explicit approval required before applying destructive changes
 
 ## 📈 Use Cases
 

package/dist/application/agents/documentation-agent.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Application Agent: Documentation Agent
+ * Generates and maintains documentation (README, API docs)
+ */
+import type { IAIService } from '../../domain/interfaces/ai-service.interface.js';
+import type { MemoryStreamService } from '../../infrastructure/storage/memory-stream-service.js';
+import type { IAgent } from '../../domain/interfaces/agent.interface.js';
+import type { DocumentationRequest, DocumentationResponse } from '../../domain/entities/documentation.js';
+export declare class DocumentationAgent implements IAgent<DocumentationRequest, DocumentationResponse> {
+    private aiService;
+    private memoryStream?;
+    private cwd;
+    name: string;
+    type: "non-engineering";
+    constructor(aiService: IAIService, memoryStream?: MemoryStreamService | undefined, cwd?: string);
+    execute(request: DocumentationRequest): Promise<DocumentationResponse>;
+    private generateREADME;
+    private generateAPIDocs;
+    private analyzeFolderStructure;
+    private findSourceFiles;
+    private buildReadmePrompt;
+    private buildAPIDocsContent;
+}
+//# sourceMappingURL=documentation-agent.d.ts.map

package/dist/application/agents/documentation-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation-agent.d.ts","sourceRoot":"","sources":["../../../src/application/agents/documentation-agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iDAAiD,CAAC;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAC;AACjG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4CAA4C,CAAC;AACzE,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,wCAAwC,CAAC;AAOhD,qBAAa,kBAAmB,YAAW,MAAM,CAAC,oBAAoB,EAAE,qBAAqB,CAAC;IAK1F,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,YAAY,CAAC;IACrB,OAAO,CAAC,GAAG;IANb,IAAI,SAAyB;IAC7B,IAAI,EAAG,iBAAiB,CAAU;gBAGxB,SAAS,EAAE,UAAU,EACrB,YAAY,CAAC,EAAE,mBAAmB,YAAA,EAClC,GAAG,GAAE,MAAsB;IAG/B,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;YAuD9D,cAAc;YA2Gd,eAAe;IAgG7B,OAAO,CAAC,sBAAsB;IAwC9B,OAAO,CAAC,eAAe;IA8BvB,OAAO,CAAC,iBAAiB;YA2BX,mBAAmB;CA6DlC"}