cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(milestone): split advanced-concepts and tui docs into sub-documents
CI / benchmark-publish (pull_request) Has been skipped
Details
CI / lint (pull_request) Successful in 1m12s
Details
CI / quality (pull_request) Successful in 1m24s
Details
CI / push-validation (pull_request) Successful in 33s
Details
CI / helm (pull_request) Successful in 34s
Details
CI / typecheck (pull_request) Successful in 1m33s
Details
CI / build (pull_request) Successful in 1m13s
Details
CI / benchmark-regression (pull_request) Failing after 37s
Details
CI / security (pull_request) Successful in 2m25s
Details
CI / e2e_tests (pull_request) Successful in 4m31s
Details
CI / unit_tests (pull_request) Successful in 6m25s
Details
CI / integration_tests (pull_request) Successful in 6m24s
Details
CI / docker (pull_request) Successful in 1m36s
Details
CI / coverage (pull_request) Successful in 13m7s
Details
CI / coverage (push) Blocked by required conditions
Details
CI / docker (push) Blocked by required conditions
Details
CI / status-check (push) Blocked by required conditions
Details
CI / benchmark-publish (push) Waiting to run
Details
CI / benchmark-regression (push) Waiting to run
Details
CI / status-check (pull_request) Successful in 5s
Details
CI / push-validation (push) Successful in 31s
Details
CI / quality (push) Successful in 1m22s
Details
CI / lint (push) Successful in 1m28s
Details
CI / helm (push) Successful in 43s
Details
CI / build (push) Successful in 1m0s
Details
CI / security (push) Successful in 1m41s
Details
CI / typecheck (push) Successful in 2m5s
Details
CI / e2e_tests (push) Successful in 4m13s
Details
CI / integration_tests (push) Successful in 4m37s
Details
CI / unit_tests (push) Has been cancelled
Details

Browse Source 
Split docs/advanced-concepts.md (554 lines) into four sub-documents under
docs/advanced-concepts/ and docs/tui.md (634 lines) into four sub-documents
under docs/tui/, each under the 500-line limit per CONTRIBUTING.md.

Advanced Concepts sub-documents:
- docs/advanced-concepts/index.md: Overview, context strategies, LLM backends
- docs/advanced-concepts/resource-types.md: Resource types, A2A rename
- docs/advanced-concepts/container-tools.md: Container tools, scope chain, budgets, safety
- docs/advanced-concepts/e2e-tests-and-plugins.md: E2E tests, code review, plugins

TUI sub-documents:
- docs/tui/index.md: Overview, getting started, main screen layout
- docs/tui/sidebar-and-personas.md: Sidebar states, persona system
- docs/tui/input-and-sessions.md: Reference/command input, session management
- docs/tui/configuration-and-integration.md: Config, key bindings, theme, integration

Updated mkdocs.yml navigation to reflect new sub-document structure.
Updated CONTRIBUTORS.md with contribution entry for PR #9903.

ISSUES CLOSED: #10533
This commit was merged in pull request #10944.
This commit is contained in:
HAL 9000
2026-04-25 00:26:18 +00:00
committed by Forgejo
parent e8548ceae2
commit dde71cf8e2
10 changed files with 1316 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/advanced-concepts/container-tools.md
+248
View File
@@ -0,0 +1,248 @@
# Advanced Concepts: Container Tools, Scope Chain, Budgets & Safety (v3.6.0)
> **Milestone:** v3.6.0 — M7: Advanced Concepts & Deferred Features
> **Parent:** [Advanced Concepts Overview](index.md)
---
## Container Tool Execution
v3.6.0 adds first-class support for executing tools inside containers, building on the
container resource types introduced in ADR-039.
### Overview
Container tool execution allows actors to run tools in isolated container environments rather
than directly on the host. This provides:
- **Stronger isolation** — tool side effects are contained within the container
- **Reproducible environments** — tools run in a known, versioned environment
- **Language-agnostic tools** — tools can be written in any language supported by the container
- **Parallel execution** — multiple containers can run simultaneously for independent tool calls
### Container Tool Configuration
Tools declare their container requirements in their YAML definition:
```yaml
name: my-org/python-linter
type: container-tool
image: "python:3.12-slim"
command: ["python", "-m", "pylint"]
mounts:
- source: "{{resource.git_dir.path}}"
target: "/workspace"
readonly: true
environment:
PYTHONPATH: "/workspace/src"
timeout: 60
```
### Execution Model
Container tools follow the same `ToolRuntime` interface as host tools. The
`ContainerToolExecutor` handles:
1. **Image resolution** — pulls the image if not cached locally
2. **Mount binding** — maps resource paths to container mount points
3. **Execution** — runs the container with the specified command and arguments
4. **Output capture** — streams stdout/stderr back to the `ToolResult`
5. **Cleanup** — removes the container after execution (configurable)
### Devcontainer Integration
When a project has a `.devcontainer/devcontainer.json`, CleverAgents can use the devcontainer
as the execution environment for all tools in that project. This is configured via the
`devcontainer-instance` resource type (ADR-043):
```yaml
resources:
- name: dev_env
type: devcontainer-instance
devcontainer_path: ".devcontainer/devcontainer.json"
use_for_tools: true
```
---
## Pluggable Scope Chain Resolution Extensions
The scope chain resolution system determines which projects, plans, and resources are in scope
for a given actor invocation. v3.6.0 makes this system extensible via a plugin interface.
### Scope Chain Resolution Protocol
The `ScopeChainResolver` interface defines a single method:
```python
class ScopeChainResolver(Protocol):
def resolve(
self,
base_scope: Scope,
context: ResolutionContext,
) -> Scope:
"""
Extend or modify the base scope based on the resolution context.
Args:
base_scope: The scope as determined by the persona and explicit @ references.
context: The current resolution context (session, plan, actor, prompt).
Returns:
The resolved scope, which may add, remove, or reorder items from base_scope.
"""
...
```
### Built-in Resolvers
| Resolver | Description |
|----------|-------------|
| `PersonaScopeResolver` | Adds persona-scoped projects and plans (always active) |
| `ReferenceResolver` | Adds explicitly `@`-referenced resources (always active) |
| `DependencyGraphResolver` | Automatically includes resources that are dependencies of in-scope resources |
| `RecentlyModifiedResolver` | Adds recently modified files from in-scope projects |
| `TestCoverageResolver` | Adds test files that cover in-scope source files |
### Custom Resolver Registration
Custom resolvers are registered via the plugin system:
```python
from cleveragents.scope import ScopeChainResolver, register_resolver
@register_resolver(name="my-org/git-blame-resolver", priority=50)
class GitBlameResolver:
def resolve(self, base_scope, context):
# Add files recently modified by the current git user
...
```
---
## Cost and Session Budgets
v3.6.0 introduces comprehensive cost tracking and budget enforcement across sessions and plans.
### Cost Tracking
Every LLM invocation is tracked with:
- **Input tokens** and **output tokens** (provider-reported)
- **Cost in USD** (computed from provider pricing tables, updated monthly)
- **Model used** (for multi-provider fallback chains)
- **Session ID** and **plan ID** for attribution
Cost data is stored in the SQLite database and queryable via:
```bash
agents session cost # Total cost for current session
agents session cost --all # All sessions with costs
agents plan cost <plan-id> # Cost breakdown for a specific plan
agents config get billing.total_spent # Lifetime total
```
### Budget Configuration
Budgets are configured at multiple levels (plan > action > project > global):
```toml
[billing]
max_cost_per_session = 5.00 # USD; hard limit per session
max_cost_per_plan = 2.00 # USD; hard limit per plan
max_total_cost = 100.00 # USD; lifetime hard limit
warn_at_percent = 80 # Warn when 80% of any budget is consumed
```
These settings correspond to the `SafetyProfile` fields defined in ADR-041:
| Config Key | SafetyProfile Field |
|-----------|-------------------|
| `max_cost_per_plan` | `SafetyProfile.max_cost_per_plan` |
| `max_total_cost` | `SafetyProfile.max_total_cost` |
### Budget Enforcement
When a budget limit is reached:
1. The current LLM invocation is **not** started (pre-flight check)
2. A `BudgetExceededError` is raised with the budget type, limit, and current spend
3. The plan transitions to `PAUSED` state with `pause_reason = "budget_exceeded"`
4. The user is notified via the CLI output or TUI notification system
5. The user can increase the budget via `agents config set billing.max_cost_per_plan <new_limit>`
and resume the plan with `agents plan resume <plan-id>`
---
## Safety Profiles
Safety profiles (ADR-041) provide fine-grained control over what actions an actor is permitted
to take. v3.6.0 completes the safety profile implementation with full enforcement in the plan
lifecycle.
### SafetyProfile Fields
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `require_sandbox` | `bool` | `True` | Require sandbox isolation for all file writes |
| `require_checkpoints` | `bool` | `True` | Require checkpoints before destructive operations |
| `allow_unsafe_tools` | `bool` | `False` | Allow tools marked as `unsafe: true` |
| `require_human_approval` | `bool` | `False` | Require human approval before each action step |
| `allowed_skill_categories` | `list[str]` | `[]` (all) | Restrict to specific skill categories |
| `max_cost_per_plan` | `float or None` | `None` | Maximum cost per plan in USD |
| `max_total_cost` | `float or None` | `None` | Maximum lifetime cost in USD |
| `max_retries_per_step` | `int` | `3` | Maximum retries per action step (0-100) |
### Built-in Safety Profiles
v3.6.0 ships with named safety profiles that can be referenced by name:
| Profile | Description |
|---------|-------------|
| `strict` | All safety flags enabled; no unsafe tools; human approval required |
| `standard` | Sandbox and checkpoints required; unsafe tools blocked; no human approval |
| `permissive` | Sandbox required; checkpoints optional; unsafe tools allowed |
| `read-only` | No file writes permitted; all tools restricted to read operations |
| `cost-capped-1usd` | Standard safety + $1.00 per-plan cost cap |
| `cost-capped-5usd` | Standard safety + $5.00 per-plan cost cap |
### Applying Safety Profiles
Safety profiles can be applied at multiple levels:
```bash
# Global default
agents config set safety.profile strict
# Per-project
agents project set-safety my-project --profile standard
# Per-plan (at creation time)
agents plan use my-action --safety-profile permissive
```
```yaml
# action.yaml
name: my-action
safety_profile:
require_sandbox: true
allow_unsafe_tools: false
max_cost_per_plan: 2.00
```
---
## Related ADRs
| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-039](../adr/ADR-039-container-resource-types.md) | Container Resource Types | Container tool execution |
| [ADR-041](../adr/ADR-041-safety-profile-extraction.md) | Safety Profile Extraction | Safety profiles and cost budgets |
| [ADR-043](../adr/ADR-043-devcontainer-integration.md) | Devcontainer Integration | Devcontainer tool execution |
---
*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*
docs/advanced-concepts/e2e-tests-and-plugins.md
+138
View File
@@ -0,0 +1,138 @@
# Advanced Concepts: E2E Tests, Code Review Examples & Plugin Architecture (v3.6.0)
> **Milestone:** v3.6.0 — M7: Advanced Concepts & Deferred Features
> **Parent:** [Advanced Concepts Overview](index.md)
---
## End-to-End Workflow Specification Tests
v3.6.0 introduces a new category of tests: **E2E workflow specification tests**. These tests
verify complete multi-step workflows from the user's perspective, exercising the full stack
from CLI input through plan execution to file output.
### Test Categories
| Category | Description | Framework |
|----------|-------------|-----------|
| `e2e/workflow` | Full plan lifecycle: create to strategize to execute to apply | Robot Framework |
| `e2e/multi-project` | Workflows spanning multiple projects | Robot Framework |
| `e2e/provider` | Provider-specific behavior (rate limits, fallback, cost tracking) | Behave |
| `e2e/safety` | Safety profile enforcement under various conditions | Behave |
| `e2e/budget` | Budget enforcement and plan pause/resume | Behave |
### Running E2E Tests
```bash
nox -s e2e # Run all E2E tests
nox -s e2e -- --tags workflow # Run only workflow tests
nox -s e2e -- --tags provider # Run only provider tests
```
E2E tests require a configured LLM provider. Set `E2E_PROVIDER=anthropic` (or another
supported provider) in your environment before running.
---
## Code Review Tool Examples
v3.6.0 ships a set of example actors and skills specifically designed for code review
workflows. These serve as both functional tools and reference implementations for the actor
and skill systems.
### Included Examples
| Example | Location | Description |
|---------|----------|-------------|
| `code-reviewer` | `examples/actors/code-reviewer.yaml` | Full code review actor with diff analysis, style checking, and security scanning |
| `pr-summarizer` | `examples/actors/pr-summarizer.yaml` | Summarizes pull request changes for review |
| `test-generator` | `examples/actors/test-generator.yaml` | Generates BDD test scenarios from source code |
| `doc-writer` | `examples/actors/doc-writer.yaml` | Generates and updates documentation from code |
| `security-scanner` | `examples/skills/security-scanner.yaml` | Skill that runs security analysis tools |
| `style-checker` | `examples/skills/style-checker.yaml` | Skill that runs linting and formatting checks |
### Using the Code Reviewer
```bash
# Register the example actor
agents actor register examples/actors/code-reviewer.yaml
# Create a code review plan
agents plan use code-review \
--project local/my-project \
--arg diff_source=git \
--arg base_branch=main
```
---
## Plugin Architecture Extensions
v3.6.0 formalizes and extends the plugin architecture, making it easier to add custom
resource types, tool executors, scope resolvers, and LLM providers.
### Plugin Entry Points
Plugins are registered via Python package entry points:
```toml
# pyproject.toml
[project.entry-points."cleveragents.plugins"]
my-plugin = "my_package.plugin:MyPlugin"
[project.entry-points."cleveragents.resource_types"]
my-resource = "my_package.resources:MyResourceType"
[project.entry-points."cleveragents.tool_executors"]
my-executor = "my_package.executors:MyToolExecutor"
[project.entry-points."cleveragents.scope_resolvers"]
my-resolver = "my_package.resolvers:MyScopeResolver"
[project.entry-points."cleveragents.providers"]
my-provider = "my_package.providers:MyLLMProvider"
```
### Plugin Security
The `PluginLoader` (hardened in v3.5.0) enforces:
- **Module allowlist** — only modules from registered, trusted packages may be loaded
- **Entry point validation** — entry point targets are parsed and validated before import
- **Sandbox isolation** — plugins run in a restricted execution environment
- **Capability declaration** — plugins must declare their required capabilities at registration
See ADR-037 (Tool Reachability & Access Projection) for the full security model.
### Plugin Development Guide
A plugin development guide is available at `docs/development/plugin-development.md` (added
in v3.6.0). It covers:
1. Creating a minimal plugin package
2. Registering resource types, tool executors, and scope resolvers
3. Testing plugins with the CleverAgents test harness
4. Publishing plugins to PyPI
---
## Related ADRs
The following Architecture Decision Records are directly relevant to v3.6.0 features:
| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-008](../adr/ADR-008-resource-system.md) | Resource System | Foundation for additional resource types |
| [ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md) | Resource DAG Operational Semantics | DAG model for new resource types |
| [ADR-039](../adr/ADR-039-container-resource-types.md) | Container Resource Types | Container tool execution |
| [ADR-041](../adr/ADR-041-safety-profile-extraction.md) | Safety Profile Extraction | Safety profiles and cost budgets |
| [ADR-042](../adr/ADR-042-resource-type-inheritance.md) | Resource Type Inheritance | Custom resource type extensions |
| [ADR-043](../adr/ADR-043-devcontainer-integration.md) | Devcontainer Integration | Devcontainer tool execution |
| [ADR-047](../adr/ADR-047-acp-standard-adoption.md) | A2A Standard Adoption | ACP to A2A rename |
---
*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*
docs/advanced-concepts/index.md
+117
View File
@@ -0,0 +1,117 @@
# 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](index.md) — this page
- [Resource Types & A2A Rename](resource-types.md)
- [Container Tools, Scope Chain, Budgets & Safety](container-tools.md)
- [E2E Tests, Code Review Examples & Plugin Architecture](e2e-tests-and-plugins.md)
---
## 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.
```toml
[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:
```toml
[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*
docs/advanced-concepts/resource-types.md
+112
View File
@@ -0,0 +1,112 @@
# Advanced Concepts: Resource Types & A2A Rename (v3.6.0)
> **Milestone:** v3.6.0 — M7: Advanced Concepts & Deferred Features
> **Parent:** [Advanced Concepts Overview](index.md)
---
## Additional Resource Types
v3.6.0 extends the resource type system (ADR-008, ADR-036, ADR-039, ADR-042) with new
resource types for cloud infrastructure, databases, and virtual/composite resources.
### Cloud Infrastructure Resources
| Type | Description | Key Properties |
|------|-------------|----------------|
| `aws-s3-bucket` | Amazon S3 bucket | `bucket_name`, `region`, `prefix` |
| `aws-lambda-function` | AWS Lambda function | `function_name`, `region`, `runtime` |
| `gcp-storage-bucket` | Google Cloud Storage bucket | `bucket_name`, `project_id` |
| `azure-blob-container` | Azure Blob Storage container | `account_name`, `container_name` |
| `terraform-workspace` | Terraform workspace (state + config) | `workspace_dir`, `backend_type` |
| `pulumi-stack` | Pulumi stack | `stack_name`, `project_dir` |
### Database Resources
| Type | Description | Key Properties |
|------|-------------|----------------|
| `postgres-schema` | PostgreSQL schema (tables, views, functions) | `connection_string`, `schema_name` |
| `mysql-database` | MySQL database | `connection_string`, `database_name` |
| `sqlite-file` | SQLite database file | `file_path` |
| `mongodb-collection` | MongoDB collection | `connection_string`, `database`, `collection` |
| `redis-keyspace` | Redis keyspace | `connection_string`, `key_prefix` |
### Virtual Resource Types
Virtual resources do not correspond to a physical storage location — they are computed
aggregates or logical groupings:
| Type | Description |
|------|-------------|
| `virtual-aggregate` | A named union of other resources, treated as a single context source |
| `virtual-diff` | The diff between two resource snapshots (e.g., before/after a plan apply) |
| `virtual-search-index` | A pre-built semantic search index over a set of resources |
| `virtual-dependency-graph` | The dependency graph of a codebase (imports, calls, inheritance) |
### Resource Type Inheritance
The resource type inheritance system (ADR-042) allows custom resource types to extend built-in
types. v3.6.0 adds the `@extends` directive in resource YAML:
```yaml
type: my-org/custom-git-repo
extends: git-checkout
properties:
ci_config_path:
type: string
default: ".github/workflows"
deploy_branch:
type: string
default: "main"
```
---
## ACP to A2A Module Rename and Symbol Standardization
v3.6.0 completes the rename of the internal `acp` module to `a2a`, aligning the codebase with
the adopted A2A standard (ADR-047).
### What Changed
| Before (ACP) | After (A2A) |
|-------------|------------|
| `cleveragents.acp` | `cleveragents.a2a` |
| `AcpClient` | `A2AClient` |
| `AcpMessage` | `A2AMessage` |
| `AcpTask` | `A2ATask` |
| `AcpEvent` | `A2AEvent` |
| `acp_server_url` config key | `a2a_server_url` config key |
### Migration Guide
Existing code that imports from `cleveragents.acp` will continue to work via a compatibility
shim until v4.0.0. A deprecation warning is emitted on first import. To migrate:
```python
# Before
from cleveragents.acp import AcpClient, AcpMessage
# After
from cleveragents.a2a import A2AClient, A2AMessage
```
The CLI commands are unaffected — they use the public API which was already A2A-named.
---
## Related ADRs
| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-008](../adr/ADR-008-resource-system.md) | Resource System | Foundation for additional resource types |
| [ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md) | Resource DAG Operational Semantics | DAG model for new resource types |
| [ADR-042](../adr/ADR-042-resource-type-inheritance.md) | Resource Type Inheritance | Custom resource type extensions |
| [ADR-047](../adr/ADR-047-acp-standard-adoption.md) | A2A Standard Adoption | ACP to A2A rename |
---
*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*
docs/tui/configuration-and-integration.md
+209
View File
@@ -0,0 +1,209 @@
# TUI: Configuration, Key Bindings, Theme & Integration (v3.7.0)
> **Milestone:** v3.7.0 — M8: TUI Implementation
> **Parent:** [TUI Overview](index.md)
---
## Configuration
### Settings Screen
The Settings screen (`F2` or `/settings`) provides a GUI for all TUI configuration:
- **Theme** — select from 17+ Textual built-in themes (default: Dracula)
- **Sidebar width** — configure the visible sidebar width (default: 32 chars)
- **Session persistence** — enable/disable session history persistence
- **Cost display** — configure cost display precision and currency
- **Notification duration** — configure how long Flash notifications stay visible
- **Keybindings** — view all keybindings (editing not yet supported in v3.7.0)
### Configuration File
TUI settings are stored in `~/.config/cleveragents/config.toml` under `[tui]`:
```toml
[tui]
theme = "dracula"
sidebar_width = 32
session_db_path = "~/.local/state/cleveragents/tui.db"
notification_duration = 3.0 # seconds
cost_display_precision = 2 # decimal places
```
TUI state (last persona, sidebar state, window dimensions) is stored separately in
`~/.config/cleveragents/tui-state.yaml`:
```yaml
last_persona: "feature-dev"
last_preset: "think: high"
last_session_id: "01HXM8C2..."
sidebar_state: "visible"
theme_override: null
window_width: 180
window_height: 50
```
---
## Key Bindings
### Global Bindings
| Key | Action |
|-----|--------|
| `ctrl+q` | Quit the TUI |
| `F1` | Open context-sensitive help panel |
| `F2` / `ctrl+,` | Open Settings screen |
| `ctrl+s` | Open Sessions screen |
| `ctrl+n` | New session tab |
| `ctrl+w` | Close current session tab |
| `ctrl+[` | Previous session tab |
| `ctrl+]` | Next session tab |
### Conversation Bindings
| Key | Action |
|-----|--------|
| `alt+up` | Move block cursor up |
| `alt+down` | Move block cursor down |
| `enter` / `space` | Expand/collapse focused block |
| `ctrl+b` | Focus sidebar (when visible) |
### Prompt Bindings
| Key | Action |
|-----|--------|
| `tab` | Cycle to next persona |
| `ctrl+tab` | Cycle to next argument preset |
| `shift+tab` | Cycle sidebar state (hidden → visible → fullscreen) |
| `shift+enter` / `ctrl+j` | Insert newline (multi-line mode) |
| `escape` | Dismiss overlay / exit multi-line mode / navigate toward main screen |
### Sidebar Bindings (when focused)
| Key | Action |
|-----|--------|
| `up` / `down` | Navigate plan/project list |
| `enter` | Open detail modal for selected item |
| `escape` | Return focus to prompt |
---
## Theme and Styling
The TUI uses Textual's CSS (TCSS) system with semantic color tokens. The default theme is
**Dracula**. All 17+ Textual built-in themes are supported and switchable via:
```bash
/theme dracula # Switch to Dracula theme
/theme nord # Switch to Nord theme
/theme monokai # Switch to Monokai theme
/theme # Show current theme
```
Or via the Settings screen (`F2`).
### Throbber
A rainbow gradient animated bar spans the full width of the screen at the top, visible only
when the actor is processing. The gradient cycles through a 12-color spectrum at 15fps.
When idle, the throbber row collapses to zero height.
### Notification System
The Flash bar (height: 1, above the prompt) displays transient notifications:
- **Info** — blue, 3 seconds
- **Warning** — yellow, 5 seconds
- **Error** — red, 10 seconds (or until dismissed with `escape`)
- **Success** — green, 3 seconds
---
## TuiMaterializer — Output Rendering Integration
The `TuiMaterializer` bridges the existing `OutputSession` / `ElementHandle` pipeline
(ADR-021) to Textual widgets. All existing CLI command producers render in the TUI without
modification — the same code that renders Rich tables in the CLI renders interactive Textual
widgets in the TUI.
| ElementHandle Type | Textual Widget |
|--------------------|----------------|
| `PanelHandle` | `Static` container with key-value `Label` pairs in a `Collapsible` |
| `TableHandle` | `DataTable` widget |
| `TreeHandle` | `Tree` widget |
| `ProgressHandle` | `ProgressBar` (determinate) or `Throbber` (indeterminate) |
| `StatusHandle` | `Label` with semantic CSS class |
| `CodeHandle` | Read-only `TextArea` with tree-sitter syntax highlighting |
| `DiffHandle` | Custom `DiffView` widget (unified and side-by-side modes) |
| `SeparatorHandle` | `Rule` widget |
| `ActionHintHandle` | `Static` with muted text and command references |
---
## Real-Time A2A Event Subscription
The TUI subscribes to A2A events for real-time visibility into system activity:
| Event | TUI Effect |
|-------|-----------|
| `plan.phase_changed` | Sidebar PlansPanel: update phase indicator |
| `plan.state_changed` | Sidebar PlansPanel: update state badge |
| `plan.decision_made` | Sidebar PlansPanel: update depth counter |
| `tool.invoked` | Conversation: mount ToolCall widget (pending) |
| `tool.completed` | Conversation: update ToolCall widget (done/fail) |
| `validation.completed` | Conversation: append validation result |
| `plan.apply_completed` | Sidebar: update terminal state; Flash: show completion |
| `plan.error` | Flash: show error; Sidebar: mark plan as errored |
| `session.message` | Conversation: stream ActorResponse content |
In local mode, events arrive via RxPY observables. In server mode, events arrive via A2A
`TaskStatusUpdateEvent` / `TaskArtifactUpdateEvent` via SSE.
---
## Content Pruning and Safety Behaviors
### Content Pruning
When the conversation stream exceeds the configurable threshold (default: 500 message blocks),
old messages are automatically collapsed (not deleted) to maintain rendering performance.
Collapsed messages remain in the session history and can be expanded by scrolling up.
Configure the pruning threshold:
```toml
[tui]
conversation_prune_threshold = 500
```
### Safety Behaviors
The TUI enforces safety behaviors from the active persona's safety profile:
- **Shell danger detection** — commands matching destructive patterns are highlighted in red
with a confirmation overlay before execution
- **Permission questions** — single-file tool operations render an inline `PermissionQuestionWidget`
in the conversation stream; multi-file operations push the full `PermissionsScreen`
- **Cost warnings** — when session cost approaches the configured budget, a persistent warning
appears in the Flash bar
- **Loading states** — the throbber and per-block loading indicators prevent user confusion
during long-running operations
---
## Related ADRs
| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) | TUI Architecture and Framework | Core TUI design decisions |
| [ADR-021](../adr/ADR-021-cli-and-output-rendering.md) | CLI and Output Rendering | TuiMaterializer integration |
| [ADR-026](../adr/ADR-026-agent-client-protocol.md) | Agent-to-Agent Protocol (A2A) | TUI-to-application communication |
---
*Documentation for v3.7.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*
docs/tui/index.md
+166
View File
@@ -0,0 +1,166 @@
# Text User Interface (TUI) — v3.7.0
> **Milestone:** v3.7.0 — M8: TUI Implementation
> **Status:** In Progress (~42% complete as of 2026-04-15)
> **Goal:** Implement the comprehensive Text User Interface using Textual >= 1.0 and all TUI-dependent features.
>
> **Key ADRs:** [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) (TUI Architecture),
> [ADR-045](../adr/ADR-045-tui-persona-system.md) (Persona System),
> [ADR-046](../adr/ADR-046-tui-reference-and-command-system.md) (Reference & Command System)
---
## Overview
The CleverAgents TUI is a full-screen terminal application built with
[Textual](https://textual.textualize.io/) >= 1.0. It provides a rich, keyboard-driven
interface for interacting with actors, managing plans and projects, and monitoring real-time
plan execution — capabilities that are impractical in the stateless CLI.
The TUI is the second Presentation-layer surface in the CleverAgents multi-frontend
architecture (CLI, **TUI**, Web, IDE Plugin, A2A Server). All five surfaces communicate
exclusively through the A2A protocol (ADR-026) — the TUI never imports directly from the
Domain or Infrastructure layers.
**Sub-sections:**
- [Overview & Main Screen Layout](index.md) — this page
- [Sidebar States & Persona System](sidebar-and-personas.md)
- [Reference/Command Input & Session Management](input-and-sessions.md)
- [Configuration, Key Bindings, Theme & Integration](configuration-and-integration.md)
### Installation
The TUI is an optional extra to keep the base installation lightweight:
```bash
pip install cleveragents[tui]
```
### Launching the TUI
```bash
agents tui # Launch with default persona
agents tui --persona feature-dev # Launch with a specific persona
agents tui --server https://my-server:8080 # Connect to a remote A2A server
```
---
## Getting Started
### First Run
On first launch (no personas configured), the TUI opens to the main chat screen with a
centered actor selection overlay:
1. The overlay lists all registered actors discovered from the Actor Registry via A2A
2. Select an actor with arrow keys + `enter`, or type `/` to search
3. Selection creates a default persona named `"default"` with the chosen actor and
auto-generated argument presets
4. The overlay dismisses and you can begin chatting immediately
### Subsequent Launches
The TUI restores the last active persona and session automatically. Your conversation
history, sidebar state, and theme preference are all preserved.
---
## Main Screen Layout
The MainScreen is the primary interface. It uses a horizontal layout with the conversation
taking available space and the sidebar docked to the right:
```
┌──────────────────────────────────────────────────────┬──────────────────────┐
│ Throbber (height: 1, full width, visible when busy) │ │
│ SessionTabs (height: auto, visible when >= 2 sessions)│ │
├──────────────────────────────────────────────────────┤ SideBar │
│ │ (dock: right) │
│ Conversation │ (width: 32-40) │
│ (flex: 1fr) │ (max-width: 45%) │
│ │ ┌────────────────┐ │
│ ┌─ ContentsGrid ─────────────────────────────────┐ │ │ PlansPanel │ │
│ │ Cursor │ Contents stream │ │ │ (collapsible) │ │
│ │ (1ch) │ - Welcome / UserInput / ActorResponse│ │ │ │ │
│ │ │ - ToolCall / PlanProgress / DiffView │ │ ├────────────────┤ │
│ │ │ - TerminalEmbed / Note / Warning │ │ │ ProjectsPanel │ │
│ └────────┴───────────────────────────────────────┘ │ │ (collapsible) │ │
│ │ │ │ │
│ Flash (notification bar, height: 1) │ └────────────────┘ │
│ │ │
│ ┌─ Prompt ────────────────────────────────────────┐ │ │
│ │ ReferencePickerOverlay (overlay, triggered by @)│ │ │
│ │ SlashCommandOverlay (overlay, triggered by /) │ │ │
│ │ ┌─ PromptContainer ─────────────────────────┐ │ │ │
│ │ │ [>] PromptTextArea │ │ │ │
│ │ └───────────────────────────────────────────┘ │ │ │
│ │ PersonaBar: name | actor | preset | cost │ │ │
│ └─────────────────────────────────────────────────┘ │ │
├──────────────────────────────────────────────────────┴──────────────────────┤
│ Footer: F1 Help | shift+tab Sidebar | tab Persona | ctrl+q Quit │
└─────────────────────────────────────────────────────────────────────────────┘
```
### Conversation Stream
The conversation displays a chronological stream of typed message blocks:
| Block Type | Description | Source |
|------------|-------------|--------|
| `Welcome` | ASCII art + first-run instructions | App startup (first message only) |
| `UserInput` | Your prompt, rendered as Markdown | User submission |
| `ActorResponse` | Streaming Markdown with syntax-highlighted code | Actor response events |
| `ActorThought` | Actor reasoning (italic, muted, collapsible) | Actor thinking events |
| `ToolCall` | Expandable tool invocation with status and output | Tool execution events |
| `PlanProgress` | Grid layout with status icons per step | Plan phase changes |
| `DiffView` | Unified or side-by-side diff with syntax highlighting | Tool results with diffs |
| `TerminalEmbed` | Bordered terminal output | Shell commands or tool terminal output |
| `ShellResult` | Shell command output | User `!` shell commands |
| `Note` | Semantic info/warning/error notifications | System notifications |
The conversation uses a 2-column grid: a 1-character cursor column (left) navigable with
`alt+up`/`alt+down`, and the content stream (right). Press `enter` or `space` on a block
to expand/collapse it.
---
## Architecture Notes
The TUI is implemented in `src/cleveragents/tui/` and follows the layered architecture
(ADR-001):
```
src/cleveragents/tui/
├── app.py # CleverAgentsApp root
├── cleveragents.tcss # Global app styles
├── screens/ # Screen classes and TCSS
│ ├── main.py # MainScreen
│ ├── sidebar_full.py # SidebarFullScreen
│ ├── plan_detail.py # PlanDetailModal
│ ├── project_detail.py # ProjectDetailModal
│ ├── persona_editor.py # PersonaEditorModal
│ ├── settings.py # SettingsScreen
│ ├── sessions.py # SessionsScreen
│ └── permissions.py # PermissionsScreen
├── widgets/ # Custom Textual widgets
│ ├── conversation.py # Conversation stream widgets
│ ├── prompt.py # Prompt area and overlays
│ ├── sidebar.py # Sidebar panels
│ └── throbber.py # Rainbow throbber
├── materializer.py # TuiMaterializer implementation
├── persona.py # Persona loading and management
└── session_db.py # SQLite session persistence
```
Import-linter rules enforce that `src/cleveragents/tui/` imports only from
`src/cleveragents/cli/output/` (for `TuiMaterializer` integration) and A2A client
interfaces — never from Domain or Infrastructure layers directly.
---
*Documentation for v3.7.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*
docs/tui/input-and-sessions.md
+156
View File
@@ -0,0 +1,156 @@
# TUI: Reference/Command Input & Session Management (v3.7.0)
> **Milestone:** v3.7.0 — M8: TUI Implementation
> **Parent:** [TUI Overview](index.md)
---
## Reference and Command Input
The TUI prompt supports three input modes, each activated by a distinct prefix character.
This system is defined in ADR-046.
### Input Modes
| First Character | Mode | Prompt Symbol | Sent To |
|-----------------|------|---------------|---------|
| *(any other)* | Normal | `>` | Actor via A2A |
| `@` *(inline)* | Normal + Reference | `>` | Actor (with CRP directives) |
| `/` | Command | `/` | TUI command processor |
| `!` | Shell | `$` | Host OS subprocess |
### @ Reference System
Type `@` anywhere in a normal-mode prompt to open the **Reference Picker** overlay. This
provides real-time fuzzy search across all registered projects, plans, and resources.
```
@project:cleveragents # Reference an entire project
@project:cleveragents:src/foo.py # Reference a specific file
@plan:01HXM8C2 # Reference a plan by ULID
@plan:01HXM8C2:decision/D3 # Reference a specific decision
@handler.py # Fuzzy match (expands to canonical form)
```
Resolved `@` references are translated into CRP (Context Request Protocol) directives that
direct the ACMS to prioritize the referenced resources in context assembly. They are not
merely display annotations — they have real semantic effect on what the actor sees.
#### Reference Picker Overlay
```
+- Reference Picker -----------------------------------------------+
| @hand |
| ---------------------------------------------------------------- |
| PROJECT api-service:src/auth/handler.py |
| local/api-service * Python * 245 lines |
| |
| PROJECT cleveragents:git_dir/src/cli/commands/handler.py |
| local/cleveragents * Python * 189 lines |
| |
| PLAN fix-auth-handler (01HXM8C2...) |
| Phase: Execute * Actor: claude-4-sonnet |
| |
| enter Select | tab Tree | ctrl+p Projects | ctrl+l Plans |
+------------------------------------------------------------------+
```
Navigation: `up`/`down` to move, `enter` to select, `tab` to switch to tree browser mode,
`escape` to dismiss.
### / Command System
Type `/` at the start of the prompt to open the **Slash Command** overlay with tab completion.
Commands cover all TUI operations and mirror the CLI command set.
Key command namespaces:
| Namespace | Examples |
|-----------|---------|
| `/session:*` | `create`, `list`, `switch`, `close`, `export`, `import` |
| `/persona:*` | `list`, `set`, `create`, `edit`, `delete`, `export`, `import` |
| `/scope:*` | `add`, `remove`, `clear`, `show` |
| `/plan:*` | `use`, `list`, `status`, `tree`, `execute`, `apply`, `cancel`, `diff`, `correct` |
| `/project:*` | `list`, `create`, `show`, `delete`, `inspect` |
| `/actor:*` | `list`, `show`, `set-default` |
| `/resource:*` | `list`, `show`, `tree`, `inspect` |
| `/config:*` | `list`, `get`, `set` |
| TUI utilities | `/clear`, `/theme`, `/settings`, `/help`, `/about`, `/debug` |
### ! Shell Mode
Type `!` at the start of the prompt to enter shell mode. Commands execute on the host OS
and output appears as `ShellResult` blocks in the conversation stream.
```
! git status # Run git status
! ls -la src/ # List directory
! python -m pytest # Run tests
```
Shell mode features:
- Separate command history (navigable with `up`/`down`)
- File/directory tab completion
- Dangerous command detection (destructive patterns highlighted in red with confirmation)
- Real-time output streaming for long-running commands
- `ctrl+c` sends SIGINT to the subprocess
---
## Session Management
Each session tab represents an independent domain `Session` (ADR-020) with its own
conversation history, persona binding, and A2A Task.
### Session Tabs
Session tabs appear at the top of the screen when two or more sessions are open:
| Key | Action |
|-----|--------|
| `ctrl+n` | Create a new session tab with the current persona |
| `ctrl+w` | Close the current session tab (confirms if conversation exists) |
| `ctrl+[` | Switch to the previous session tab |
| `ctrl+]` | Switch to the next session tab |
| `ctrl+r` | Resume a previous session from the Sessions screen |
Session tab state indicators:
- `⌛` — actor is working
- `>` — awaiting user input
- *(plain)* — idle
### Session Persistence
Sessions are persisted to SQLite at `~/.local/state/cleveragents/tui.db`. This includes:
- Full conversation history (all message blocks)
- Session metadata (persona, actor, creation time, last activity)
- Session cost accumulation
Sessions persist across TUI restarts. Use `ctrl+r` or `/session:list` to resume a previous
session.
### Sessions Screen
The Sessions screen (`ctrl+s` or `/session:list`) provides a full-screen view of all sessions:
- Sortable by name, date, cost, or message count
- Search/filter by persona, actor, or keyword
- Bulk operations: delete multiple sessions, export session history
- Resume any session with `enter`
---
## Related ADRs
| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-046](../adr/ADR-046-tui-reference-and-command-system.md) | TUI Reference and Command System | @ references, / commands, ! shell |
| [ADR-020](../adr/ADR-020-session-model.md) | Session Model | Session persistence and management |
---
*Documentation for v3.7.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*
docs/tui/sidebar-and-personas.md
+158
View File
@@ -0,0 +1,158 @@
# TUI: Sidebar States & Persona System (v3.7.0)
> **Milestone:** v3.7.0 — M8: TUI Implementation
> **Parent:** [TUI Overview](index.md)
---
## Sidebar States
The sidebar cycles through three states via `shift+tab`:
| State | Layout | Input Focus | Content |
|-------|--------|-------------|---------|
| **Hidden** | Sidebar has `display: none`; conversation takes full width | Prompt retains focus | No sidebar content visible |
| **Visible** | Sidebar docked right, 32-40 chars wide | Prompt retains focus; `ctrl+b` focuses sidebar | Plans and Projects panels in collapsible containers; read-only status |
| **Fullscreen** | Sidebar covers entire screen | Sidebar takes input focus | Extended plan/project details, persona management, selection mode |
State transitions:
```
Hidden --shift+tab--> Visible --shift+tab--> Fullscreen
^ |
+-------------- escape (x1-2) ----------------+
```
In fullscreen mode, `escape` returns to visible; another `escape` returns to hidden. This
cascading escape behavior is consistent across all TUI states — pressing `escape` always
moves toward the main screen.
### Plans Panel
The Plans panel (visible and fullscreen sidebar) shows:
- Active plans with their current phase and state
- Phase indicator: `Strategize` / `Execute` / `Apply` / `Complete` / `Error`
- State badge: `Running` / `Paused` / `Waiting` / `Complete`
- Decision depth counter (number of decisions made)
- Real-time updates via A2A event subscription
### Projects Panel
The Projects panel shows:
- All registered projects with their resource counts
- Scoped projects (from the active persona) highlighted with a pin indicator
- Recently accessed projects sorted to the top
---
## Persona System
Personas are TUI-only abstractions that bundle an actor, its configuration, project/plan
scope, and argument presets into a single switchable unit. They are defined in ADR-045.
### What a Persona Contains
```yaml
# ~/.config/cleveragents/personas/feature-dev.yaml
name: "feature-dev"
description: "Feature development with Claude on main projects"
actor: "anthropic/claude-4-sonnet"
color: "$primary"
base_arguments:
thinking_effort: "medium"
temperature: 0.7
max_tokens: 16384
scoped_projects:
- "local/cleveragents"
- "local/api-service"
scoped_plans: []
argument_presets:
- name: "default"
display: "default"
overrides: {}
- name: "think-more"
display: "think: high"
overrides:
thinking_effort: "high"
- name: "quick"
display: "quick"
overrides:
thinking_effort: "low"
max_tokens: 4096
cycle_order: 1
```
### Switching Personas
- **`tab`** — cycle forward through personas in the configured cycle list
- **`/persona:set <name>`** — switch to a specific persona by name
- **Fullscreen sidebar** — select from the full persona list
When you switch personas, the PersonaBar updates immediately and subsequent prompts use the
new persona's actor and scope. Previous conversation history is retained.
### Argument Presets
**`ctrl+tab`** cycles through the current persona's argument presets:
```
default --> think: high --> think: max --> quick --> default --> ...
```
The active preset's display name appears in the PersonaBar. Effective arguments are computed
as `merge(base_arguments, active_preset.overrides)`.
### PersonaBar
The PersonaBar sits below the prompt input and is always visible:
```
feature-dev | anthropic/claude-4-sonnet | think: high | 2 projects | $0.12
```
| Segment | Updates When |
|---------|-------------|
| Persona name | `tab` cycle |
| Actor name | `tab` cycle |
| Preset label | `ctrl+tab` cycle |
| Scope indicator | Persona change or `/scope:add/remove` |
| Session cost | After each actor response |
### Managing Personas
```bash
/persona:list # List all personas
/persona:create # Open PersonaEditorModal
/persona:edit feature-dev # Edit an existing persona
/persona:delete old-persona # Delete a persona
/persona:export feature-dev # Export to YAML file
/persona:import ./shared.yaml # Import from YAML file
```
Personas are stored as YAML files in `~/.config/cleveragents/personas/` and are portable
between machines via export/import.
---
## Related ADRs
| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) | TUI Architecture and Framework | Core TUI design decisions |
| [ADR-045](../adr/ADR-045-tui-persona-system.md) | TUI Persona System | Persona data model and lifecycle |
---
*Documentation for v3.7.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*