Merge v4.0.0 into main

.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+npx lint-staged

.husky/pre-push

@@ -0,0 +1,110 @@
+#!/bin/sh
+
+# Highly optimized pre-push hook for KDM CLI
+# Ensures code quality, build integrity, and test coverage before commits are pushed to remote.
+
+# Allow bypassing via environment variables if explicitly desired
+if [ "${SKIP_PRE_PUSH}" = "1" ] || [ "${SKIP_HOOKS}" = "1" ]; then
+  echo "⏩ Skipping pre-push checks (SKIP_PRE_PUSH/SKIP_HOOKS enabled)"
+  exit 0
+fi
+
+z40="0000000000000000000000000000000000000000"
+
+has_pushable_commits=0
+run_ts_checks=0
+run_py_checks=0
+
+# Process standard input provided by git pre-push
+# Input lines format: <local_ref> <local_sha> <remote_ref> <remote_sha>
+while read -r local_ref local_sha remote_ref remote_sha; do
+  # If local ref is deleted (local_sha is all zeros), skip checks
+  if [ "$local_sha" = "$z40" ] || [ -z "$local_sha" ]; then
+    continue
+  fi
+
+  has_pushable_commits=1
+
+  # Check what files changed between remote and local ref
+  if [ "$remote_sha" = "$z40" ]; then
+    # Pushing a new branch: compare against origin/v4.0.0, origin/main, or HEAD~1
+    base_ref=""
+    if git rev-parse --verify origin/v4.0.0 >/dev/null 2>&1; then
+      base_ref="origin/v4.0.0"
+    elif git rev-parse --verify origin/main >/dev/null 2>&1; then
+      base_ref="origin/main"
+    elif git rev-parse --verify upstream/v4.0.0 >/dev/null 2>&1; then
+      base_ref="upstream/v4.0.0"
+    fi
+
+    if [ -n "$base_ref" ]; then
+      changed_files=$(git diff --name-only "$base_ref...$local_sha" 2>/dev/null || git diff --name-only HEAD~1 2>/dev/null)
+    else
+      changed_files=$(git diff --name-only HEAD~1 2>/dev/null)
+    fi
+  else
+    # Updating an existing branch: compare commits being pushed
+    changed_files=$(git diff --name-only "$remote_sha" "$local_sha" 2>/dev/null)
+  fi
+
+  # Fallback: if we cannot compute changed files, conservatively check everything
+  if [ -z "$changed_files" ]; then
+    run_ts_checks=1
+    run_py_checks=1
+    break
+  fi
+
+  # Check for TypeScript / CLI codebase changes
+  if echo "$changed_files" | grep -qE '^(src/|bin/|package\.json|tsconfig\.json|tsup\.config|\.lintstagedrc)'; then
+    run_ts_checks=1
+  fi
+
+  # Check for Python agent codebase changes
+  if echo "$changed_files" | grep -qE '^agents/'; then
+    run_py_checks=1
+  fi
+done
+
+# If no pushable commits (e.g. branch deletion), exit immediately
+if [ "$has_pushable_commits" = "0" ]; then
+  exit 0
+fi
+
+# Optimization: If only non-code files changed (docs, markdown, yaml configs), skip heavy checks
+if [ "$run_ts_checks" = "0" ] && [ "$run_py_checks" = "0" ]; then
+  echo "⚡ [pre-push] Only non-code/documentation changes detected. Skipping full build & test suite."
+  exit 0
+fi
+
+echo "🛡️  [pre-push] Running code quality verification before push..."
+
+# TypeScript / CLI quality checks
+if [ "$run_ts_checks" = "1" ]; then
+  echo "📦 [1/2] Verifying TypeScript build and type declaration generation..."
+  npm run build || {
+    echo "❌ [pre-push] Build failed ('npm run build'). Please fix compilation or type errors before pushing." >&2
+    exit 1
+  }
+
+  echo "🧪 [2/2] Running Vitest test suite..."
+  npm test || {
+    echo "❌ [pre-push] Unit tests failed ('npm test'). Please fix failing tests before pushing." >&2
+    exit 1
+  }
+fi
+
+# Python agent tests
+if [ "$run_py_checks" = "1" ]; then
+  if command -v pytest >/dev/null 2>&1; then
+    echo "🐍 Running Python agent tests (pytest agents/)..."
+    pytest agents/ || {
+      echo "❌ [pre-push] Python agent tests failed ('pytest agents/'). Please fix agent tests before pushing." >&2
+      exit 1
+    }
+  else
+    echo "ℹ️  [pre-push] pytest not found in PATH; skipping Python agent test suite."
+  fi
+fi
+
+echo "✅ [pre-push] All automated code quality checks passed! Pushing to remote..."
+exit 0

.lintstagedrc.js

@@ -0,0 +1,5 @@
+export default {
+  'src/**/*.{ts,tsx}': () => 'npm run check:types',
+  'src/__tests__/**/*.{test,spec}.{ts,tsx}': ['vitest run --pool=forks'],
+  'agents/**/*.py': ['python3 -m py_compile']
+};

CONTRIBUTING.md

@@ -46,6 +46,7 @@ To set up your development environment:
    ```bash
    npm install
    ```
+   *(This automatically initializes Husky Git hooks to ensure code quality standards on commit and push)*
 3. To start the development watcher:
    ```bash
    npm run dev

README.md

@@ -50,6 +50,7 @@ Unlike tools that focus on a single runtime ([k9s] for Kubernetes or [lazydocker
 | **Log Fetching** | Retrieve logs from containers or pods with automatic Docker-to-Kubernetes fallback |
 | **Alert Notifications** | Send alerts via Discord webhook or email SMTP on failures |
 | **Minikube Support** | Check Minikube profile status and connectivity |
+| **Multi-Agent SRE** | Autonomous multi-agent council with local Ollama models, live Ink TUI, and closed-loop remediation (`kdm analyze --multi-agent`) |
 | **AI Diagnostics** | Scan cluster workload configuration errors (`kdm analyze`) with AI explanations (`--explain`) |
 | **AI Providers** | Multi-backend credentials (`kdm auth`) supporting OpenAI, Anthropic, Gemini, WatsonX, Ollama, etc. |
 | **Local Cache** | Cache system (`kdm cache`) to save AI explanation API tokens and reduce network latency |
@@ -151,12 +152,102 @@ Scan your Kubernetes cluster for common workload issues (mismatched replicas, cr
 ```bash
 kdm analyze                          # Run cluster diagnostics and output color-coded report
 kdm analyze -n default               # Analyze resources in the 'default' namespace only
-kdm analyze --explain                # Run diagnostics and fetch AI explanation
+kdm analyze --multi-agent            # Run autonomous multi-agent SRE council with local Ollama models
+kdm analyze deployment/checkout-api --multi-agent # Target specific workload for multi-agent root-cause triaging
+kdm analyze --explain                # Run diagnostics and fetch single-prompt AI explanation
 kdm analyze --explain --backend ollama # Force specific active AI backend provider
 kdm analyze --explain --anonymize    # Anonymize resource names in prompt to protect sensitive data
 kdm analyze --output json            # Output results in structured JSON format
 ```
 
+### Multi-Agent SRE Architecture (`--multi-agent`)
+
+KDM v4.0.0 features an autonomous **Multi-Agent SRE Council** running 100% locally via Ollama. Instead of relying on a single static LLM prompt, KDM coordinates domain-specialist agents in parallel to collect evidence, evaluate deterministic failure rules, correlate observations, formulate root-cause hypotheses, and safely apply verified remediations.
+
+#### Complete Lifecycle Flow
+
+```mermaid
+flowchart TD
+    CLI["CLI Command: kdm analyze --multi-agent"] --> Collect["1. Evidence Collector\n(Pods, Events, Logs, Node Metrics)"]
+    Collect --> RuleEngine{"2. Deterministic Rule Engine\n(< 5ms fast-path check)"}
+    RuleEngine -- Conclusive Match --> Instant["Instant Diagnosis\n(Zero LLM Overhead)"]
+    RuleEngine -- Complex Failure --> Council["Specialist Agent Council\n(Parallel Execution)"]
+
+    subgraph Specialists["2. Specialist Council"]
+        Council --> Runtime["Runtime & Log Agent\n(Exit codes, panic traces, crashes)"]
+        Council --> Config["Config & Dependency Agent\n(Limits, probes, secrets, ConfigMaps)"]
+        Council --> Resource["Cluster & Resource Agent\n(Node memory/disk pressure, capacity)"]
+    end
+
+    Runtime --> Correlate["3. Correlate & Validate\n(Lead SRE Synthesizer)"]
+    Config --> Correlate
+    Resource --> Correlate
+
+    Correlate --> Validator{"Cross-Agent Validator\n(Contradiction Check)"}
+    Validator -- Validated --> Consensus["4. Consensus Diagnosis\n(Root Cause + High Confidence + Solution)"]
+    Instant --> Consensus
+
+    Consensus --> TUI["Live Ink TUI Dashboard"]
+    TUI --> SafetyGate{"5. Remediation Safety Gate [y/N]\n(Destructive Command Policy)"}
+    SafetyGate -- "Confirmed [y]" --> Executor["Parameterized Executor\n(Stdout/Stderr + Audit Trail)"]
+    SafetyGate -- "Aborted [n]" --> Aborted["Remediation Aborted Safely"]
+
+    Executor --> Verify["6. Post-Fix Verification\n(Pod Ready 1/1, Rollout, Zero Restarts)"]
+    Verify --> Done["Remediation Successful!"]
+```
+
+#### Expected Product Flow
+
+```text
+$ kdm analyze deployment/checkout-api --multi-agent
+
+1. COLLECT
+   ✓ Kubernetes evidence collected (14 items)
+
+2. INVESTIGATE
+   ✓ Runtime Agent (detected exit code 137)
+   ✓ Config Agent (checked limits and probes)
+   ✓ Resource Agent (checked node memory pressure)
+
+3. CORRELATE & VALIDATE
+   ✓ Lead Investigator formulated root-cause hypothesis
+   ✓ Validator confirmed: no contradictions
+
+4. DIAGNOSIS
+   Root Cause: Container exceeded 256Mi memory limit under peak load
+   Confidence: HIGH · 96%
+
+5. REMEDIATION
+   Action: Increase memory limit (256Mi → 512Mi)
+   Command: kubectl set resources deployment checkout-api --limits=memory=512Mi
+   Apply? [y/N]: y
+
+6. VERIFY
+   ✓ Deployment rolled out
+   ✓ Pod Ready: 1/1
+   ✓ No new restarts detected
+
+Remediation successful.
+```
+
+#### CLI Flags & Configuration Options
+
+| Option | Method | Description |
+|--------|--------|-------------|
+| `--multi-agent` | CLI Flag | Enables multi-agent council for `kdm analyze` |
+| `--model <model>` | CLI Flag | Selects local Ollama model (e.g. `llama3.1`, `qwen2.5-coder`) |
+| `multi_agent: true` | Config Store | Persist opt-in via `kdm config set multi_agent true` |
+| `KDM_MULTI_AGENT=true` | Environment | Set environment variable for CI/CD or non-interactive automation |
+
+#### Resilient 4-Step Graceful Degradation Ladder
+
+KDM is engineered for mission-critical reliability. If local Ollama, Python, or cloud backends fail or timeout, KDM automatically falls back down the degradation ladder without throwing unhandled exceptions:
+
+1. **Step 1: Multi-Agent Council** — Full parallel multi-agent triage with local Ollama models.
+2. **Step 2: Deterministic Rule Engine** — Evaluates rules in `< 5ms` with zero LLM overhead for canonical failure signatures (`OOMKilled`, `CrashLoopBackOff`, `ImagePullBackOff`, `ProbeFailure`, `Scheduling`).
+3. **Step 3: Legacy AI Client** — Single-prompt cloud provider completions (OpenAI, Claude, Azure).
+4. **Step 4: Raw Kubernetes Summary** — Structured, formatted workload error diagnostics with zero AI required.
+
 ### AI Providers (Auth)
 
 Manage AI backend settings and credentials. KDM supports **10+** AI providers including OpenAI, Anthropic, Gemini, Vertex, OCI GenAI, HuggingFace, Groq, WatsonX, and Ollama.
@@ -295,25 +386,30 @@ KDM automatically checks for failure conditions and sends notifications when con
 | [Commander.js] | CLI framework and argument parsing |
 | [dockerode] | Docker daemon API client |
 | [@kubernetes/client-node] | Kubernetes API client |
-| [Ink] + [React] | Interactive terminal UI (watch mode) |
+| [Python 3] + [Ollama] | Multi-agent SRE council and local LLM execution |
+| [Ink] + [React] | Interactive terminal UI (watch mode & council dashboard) |
 | [chalk] | Terminal string coloring |
 | [cli-table3] | Table rendering |
 | [conf] | Persistent configuration |
 | [nodemailer] | Email alerts |
 | [tsup] | High-performance bundler |
+| [Vitest] | Unit and end-to-end integration test runner |
 
 [TypeScript]: https://www.typescriptlang.org
 [Node.js]: https://nodejs.org
 [Commander.js]: https://github.com/tj/commander.js
 [dockerode]: https://github.com/apocas/dockerode
 [@kubernetes/client-node]: https://github.com/kubernetes-client/javascript
+[Python 3]: https://www.python.org
+[Ollama]: https://ollama.com
 [Ink]: https://github.com/vadimdemedes/ink
 [React]: https://react.dev
 [chalk]: https://github.com/chalk/chalk
 [cli-table3]: https://github.com/cli-table/cli-table3
 [conf]: https://github.com/sindresorhus/conf
 [nodemailer]: https://nodemailer.com
 [tsup]: https://tsup.egoist.dev
+[Vitest]: https://vitest.dev
 
 ---
 

agents/__init__.py

@@ -0,0 +1,21 @@
+"""
+KDM Multi-Agent Collaborative Analysis System — v4.0.0
+======================================================
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_AGENTS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _AGENTS_DIR not in sys.path:
+    sys.path.insert(0, _AGENTS_DIR)
+
+from council import AgentCouncil, resolve_model, run_council  # noqa: E402
+
+__all__ = [
+    "AgentCouncil",
+    "resolve_model",
+    "run_council",
+]

agents/conftest.py

@@ -0,0 +1,8 @@
+"""Pytest configuration for agents test suite."""
+
+import os
+import sys
+
+_AGENTS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _AGENTS_DIR not in sys.path:
+    sys.path.insert(0, _AGENTS_DIR)

agents/core/__init__.py

@@ -0,0 +1,57 @@
+"""
+KDM Core Evidence Layer
+=======================
+Provides the canonical, normalized evidence model that forms the single
+source of truth for all specialist agents and deterministic rules.
+
+Core Architectural Rule: KDM collects facts; agents reason over facts.
+"""
+
+from .context import AnalysisContext, AnalysisMetadata
+from .evidence import CollectionStatus, EvidenceBundle, EvidenceItem, Target
+from .events import (
+    REQUIRED_CONSENSUS_KEYS,
+    VALID_AGENT_ROLES,
+    emit_agent_complete,
+    emit_agent_failed,
+    emit_agent_progress,
+    emit_agent_start,
+    emit_agent_tool_call,
+    emit_agent_tool_result,
+    emit_analysis_start,
+    emit_diagnosis_ready,
+    emit_error,
+    emit_event,
+    emit_evidence_collected,
+    emit_rule_matched,
+)
+from .sanitizer import redact_sensitive_data
+from .store import EvidenceStore, FindingRecord, ToolCallRecord
+
+__all__ = [
+    "AnalysisContext",
+    "AnalysisMetadata",
+    "CollectionStatus",
+    "EvidenceBundle",
+    "EvidenceItem",
+    "EvidenceStore",
+    "FindingRecord",
+    "REQUIRED_CONSENSUS_KEYS",
+    "Target",
+    "ToolCallRecord",
+    "VALID_AGENT_ROLES",
+    "emit_agent_complete",
+    "emit_agent_failed",
+    "emit_agent_progress",
+    "emit_agent_start",
+    "emit_agent_tool_call",
+    "emit_agent_tool_result",
+    "emit_analysis_start",
+    "emit_diagnosis_ready",
+    "emit_error",
+    "emit_event",
+    "emit_evidence_collected",
+    "emit_rule_matched",
+    "redact_sensitive_data",
+]
+