cleveragents-core/docs/advanced-concepts/index.md

Advanced Concepts (v3.6.0)

Milestone: v3.6.0 — M7: Advanced Concepts & Deferred Features Status: In Progress (~33% complete as of 2026-04-15) Goal: Advanced capabilities that extend beyond the core MVP without requiring the TUI (M8) or Server (M9).

---

Overview

v3.6.0 builds on the stable foundation established by v3.0.0–v3.5.0 to introduce advanced capabilities that were intentionally deferred from the MVP. These features enrich the CleverAgents platform for power users and production deployments: richer context strategies, broader LLM provider support, additional resource types, a standardized A2A protocol, container tool execution, extensible scope chain resolution, cost and safety budgets, end-to-end workflow tests, and a plugin architecture.

None of these features require the TUI (v3.7.0) or the Server (v3.9.0) — they are fully usable from the CLI and programmatic API.

Sub-sections:

• Context Strategies & LLM Backends — this page
• Resource Types & A2A Rename
• Container Tools, Scope Chain, Budgets & Safety
• E2E Tests, Code Review Examples & Plugin Architecture

---

Advanced Context Strategies

The ACMS (Adaptive Context Management System) introduced in v3.4.0–v3.5.0 provides a four-stage pipeline: Gather → Prioritize → Assemble → Deliver. v3.6.0 extends this pipeline with advanced strategies for large-scale and multi-project workloads.

Beyond the Basic ACMS Pipeline

The basic pipeline assembles context from a single project's resources using a fixed priority order. Advanced strategies add:

Strategy	Description
Cross-project context merging	Assembles context from multiple projects simultaneously, respecting per-project budgets and cross-project relevance scores
Incremental context updates	Sends only the diff of context changes between turns rather than re-assembling the full context on every prompt
Semantic deduplication	Detects and removes semantically equivalent fragments before assembly, reducing token waste
Adaptive tier promotion	Automatically promotes frequently-accessed warm/cold fragments to hot tier based on access patterns across a session
Resource-type-aware budgeting	Allocates context budget by resource type (e.g., 40% source code, 30% tests, 20% docs, 10% config) rather than a flat priority queue

Context Request Protocol (CRP) Extensions

The CRP (defined in ADR-014) is extended with new directive types:

• focus_path — elevates a specific file path to the highest priority tier, overriding all other budget constraints
• exclude_pattern — excludes files matching a glob pattern from context assembly
• max_fragment_size — caps the size of any single fragment to prevent one large file from consuming the entire budget
• semantic_group — groups related fragments so they are either all included or all excluded (prevents partial inclusion of tightly coupled files)

---

Additional LLM Backends

v3.6.0 adds first-class support for additional LLM providers beyond the Anthropic and OpenAI backends available in v3.5.0.

Supported Providers (v3.6.0 additions)

Provider	Actor Namespace	Notes
Google Gemini	google/gemini-*	Gemini 1.5 Pro and Flash; supports long-context (1M tokens)
Mistral AI	mistral/*	Mistral Large, Codestral; strong code generation
Ollama (local)	ollama/*	Any model served by a local Ollama instance
LM Studio	lmstudio/*	OpenAI-compatible local inference
Azure OpenAI	azure/*	Azure-hosted OpenAI models with enterprise auth
AWS Bedrock	bedrock/*	Anthropic, Meta, and Mistral models via AWS
Groq	groq/*	Ultra-fast inference for Llama and Mixtral models

Provider Configuration

All providers are configured in ~/.config/cleveragents/config.toml under the [providers] section. Each provider supports a common set of base arguments (temperature, max_tokens, thinking_effort where applicable) plus provider-specific extensions.

[providers.google]
api_key = "${GOOGLE_API_KEY}"
default_model = "gemini-1.5-pro"

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "llama3.2"

Provider Fallback Chains

A new provider_fallback configuration allows defining ordered fallback chains for resilience:

[actor.default]
provider_fallback = [
  "anthropic/claude-4-sonnet",
  "google/gemini-1.5-pro",
  "ollama/llama3.2",
]

When the primary provider fails (rate limit, outage, or cost budget exceeded), the system automatically retries with the next provider in the chain.

---

Documentation for v3.6.0 — IN PROGRESS. Features described here reflect the planned scope as of 2026-04-15. Some features may be adjusted as implementation progresses.

Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot