[AUTO-DOCS-5] docs(milestone): Add v3.6.0 Advanced Concepts and v3.7.0 TUI documentation #9903
+152
-42
@@ -7,33 +7,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Atomic `load_from_metadata` for Autonomy Guardrails** (#7504): Fixed
|
||||
`AutonomyGuardrailService.load_from_metadata()` to validate both
|
||||
`AutonomyGuardrails` and `GuardrailAuditTrail` models before writing either
|
||||
to state, ensuring atomic updates. Previously, a validation failure on the
|
||||
audit trail after guardrails were already written would leave the system in
|
||||
an inconsistent state with partial updates. The method now uses a two-phase
|
||||
validate-then-write approach: all model validation occurs in Phase 1, and
|
||||
state mutations only happen in Phase 2 after all validations succeed.
|
||||
|
||||
- **ActorRegistry.add() spec-compliant YAML support** (#4466): The registry now
|
||||
accepts actor YAML using the spec's `actors:` map format with nested `config:`
|
||||
blocks, in addition to the legacy top-level `provider`/`model` format. The
|
||||
`unsafe` flag and graph descriptor from nested config are now correctly
|
||||
preserved during registration. Multi-actor YAML (>1 entry in `actors:`/`agents:`
|
||||
map) is now rejected by `add()` with a `ValidationError`. Nested
|
||||
`config.options` are now correctly preserved. The `unsafe` coercion now uses
|
||||
strict `is True or == 1` instead of `bool()` to prevent truthy non-boolean
|
||||
YAML values (e.g. `unsafe: "no"`) from being treated as unsafe.
|
||||
|
||||
- **UKO Runtime Layer 2 (Paradigm) Indexing** (#9351): Added missing `rdf:type
|
||||
uko-oo:Class` triple emission in `PythonAnalyzer._extract_class()` so that
|
||||
Python class definitions are now correctly classified at layer 2 (paradigm/OO)
|
||||
in addition to layer 3 (technology). Added the corresponding Behave scenario
|
||||
`Indexing a Python file populates layer 2 (paradigm)` to
|
||||
`features/uko_runtime.feature`, completing four-layer guarantee verification
|
||||
for the UKO runtime.
|
||||
|
||||
- **TDD Non-AssertionError Guard Visibility** (#8294): `apply_tdd_inversion` in
|
||||
`features/environment.py` now emits its non-assertion exception guard warning to
|
||||
both the structured logger and `stderr` via a new `_warning_with_stderr` helper.
|
||||
@@ -53,16 +26,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
crash (unhandled exception) is detected via an all-zero summary and the
|
||||
captured traceback is always surfaced.
|
||||
|
||||
- **Bug Hunt Pool Supervisor Non-Blocking Tracking**: Updated `bug-hunt-pool-supervisor` to make the automation tracking step non-blocking. The `automation-tracking-manager` call in step 5 is now best-effort — if it does not complete within a reasonable time or fails, the supervisor skips it and continues to the next cycle. Added explicit rule 9 clarifying that tracking must never block the main loop. Core functionality (module scanning and worker dispatch) takes priority over status reporting.
|
||||
|
||||
- **Name Validator Server-Qualified Format** (#9074): Updated actor, skill, and tool name
|
||||
validators to accept the spec-required `[[server:]namespace/]name` format. Previously,
|
||||
server-qualified names like `dev:freemo/custom-analysis` were incorrectly rejected.
|
||||
Added BDD scenarios for server-qualified name acceptance and rejection. All three
|
||||
validators (`ActorConfigSchema.validate_name`, `NAMESPACED_NAME_RE`,
|
||||
`_TOOL_NAME_PATTERN`) now correctly support optional server prefixes while maintaining
|
||||
backward compatibility with existing `namespace/name` names.
|
||||
|
||||
- **Automation Profile Silent Fallback** (#8232): `_resolve_profile_for_plan` in
|
||||
`PlanLifecycleService` now raises a clear `ValidationError` when a plan's
|
||||
automation profile name is not a known built-in profile, instead of silently
|
||||
@@ -97,7 +60,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
LLM-generated changes via `git merge` from an isolated worktree branch
|
||||
instead of flat `shutil.copy2`. Displays spec-aligned Apply Summary
|
||||
(plan ID, artifacts, insertions/deletions, project, timestamp), Sandbox
|
||||
Cleanup panel, and `✓ OK Changes applied` footer. Non-git projects fall
|
||||
Cleanup panel, and `OK Changes applied` footer. Non-git projects fall
|
||||
back to the original flat file copy.
|
||||
|
||||
- **Context Hydration Fix** (#4454): Fixed `ContextFragment` metadata types
|
||||
@@ -271,7 +234,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
- **SubplanExecutionService fail_fast cancellation** (#7582): Fixed a race condition where
|
||||
already-running parallel subplans were not cancelled when `fail_fast` fired. Previously,
|
||||
`Future.cancel()` only prevented queued futures from starting but had no effect on
|
||||
in-flight futures that completed after `stop_flag` was set -- their `COMPLETE` results
|
||||
in-flight futures that completed after `stop_flag` was set — their `COMPLETE` results
|
||||
were incorrectly included in the merge output. The fix adds a post-completion guard that
|
||||
overrides any non-`ERRORED`/non-`CANCELLED` result to `CANCELLED` when `stop_flag` is
|
||||
active, and clears the associated output to prevent it from entering the merge. Also
|
||||
@@ -312,7 +275,152 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
---
|
||||
|
||||
## [3.8.0] -- 2026-04-05
|
||||
## [3.7.0] — Unreleased (In Progress — ~42%)
|
||||
|
||||
### Added
|
||||
|
||||
- **TUI — MainScreen with Textual >= 1.0**: Implemented the primary `MainScreen` layout
|
||||
with a horizontal conversation/sidebar split. The conversation takes available space
|
||||
(flex: 1fr) and the sidebar is docked to the right (32-40 chars wide, max 45% of screen).
|
||||
A full-width rainbow-gradient throbber (height: 1) appears at the top during actor
|
||||
processing. Session tabs appear above the conversation when two or more sessions are open.
|
||||
See [ADR-044](adr/ADR-044-tui-architecture-and-framework.md) and `docs/tui.md`
|
||||
for full architecture documentation.
|
||||
|
||||
- **TUI — Three-State Sidebar**: The sidebar cycles through hidden to visible to
|
||||
fullscreen states via `shift+tab`. In hidden state the conversation takes full width;
|
||||
in visible state the sidebar shows Plans and Projects panels in collapsible containers;
|
||||
in fullscreen state the sidebar covers the entire screen for deep management operations.
|
||||
Pressing `escape` cascades back toward the main screen from any state.
|
||||
|
||||
- **TUI — Persona System**: Introduced the Persona abstraction (ADR-045) as a TUI-only
|
||||
concept that bundles an actor reference, base arguments, scoped projects/plans, and
|
||||
argument presets into a single switchable unit. Personas are stored as YAML files in
|
||||
`~/.config/cleveragents/personas/`. The `tab` key cycles through personas; `ctrl+tab`
|
||||
cycles through argument presets within the current persona. The PersonaBar below the
|
||||
prompt always shows the active persona name, actor, preset, scope, and session cost.
|
||||
|
||||
- **TUI — Reference and Command Input System**: Implemented three prompt input modes
|
||||
(ADR-046): normal mode with `@` inline references (triggers the Reference Picker overlay
|
||||
with fuzzy search across all projects, plans, and resources), `/` command mode (triggers
|
||||
the Slash Command overlay with tab completion for all TUI operations), and `!` shell mode
|
||||
(executes OS commands via subprocess with output displayed as `ShellResult` blocks).
|
||||
Resolved `@` references are translated into CRP directives for ACMS context assembly.
|
||||
|
||||
- **TUI — TuiMaterializer A2A Integration**: Implemented `TuiMaterializer` as a
|
||||
`MaterializationStrategy` that maps `ElementHandle` events to Textual widgets. All
|
||||
existing CLI command producers render in the TUI without modification. Supported mappings:
|
||||
`PanelHandle` to `Collapsible`+`Label`, `TableHandle` to `DataTable`, `TreeHandle` to
|
||||
`Tree`, `ProgressHandle` to `ProgressBar`/`Throbber`, `CodeHandle` to `TextArea`,
|
||||
`DiffHandle` to custom `DiffView`, and more.
|
||||
|
||||
- **TUI — Session Persistence**: TUI sessions are persisted to SQLite at
|
||||
`~/.local/state/cleveragents/tui.db`. Full conversation history, session metadata, and
|
||||
cost accumulation are stored across TUI restarts. Sessions are resumable via `ctrl+r`
|
||||
or `/session:list`.
|
||||
|
||||
- **TUI — Multi-Session Tabs**: Multiple concurrent sessions are supported, each with an
|
||||
independent persona, conversation history, and A2A Task binding. `ctrl+n` creates a new
|
||||
session; `ctrl+w` closes the current session; `ctrl+[`/`ctrl+]` navigate between tabs.
|
||||
|
||||
- **TUI — Settings and Session Management Screens**: Added `SettingsScreen` (accessible via
|
||||
`F2` or `/settings`) for theme selection, sidebar width, session persistence, and
|
||||
notification configuration. Added `SessionsScreen` (accessible via `ctrl+s`) for
|
||||
browsing, resuming, and managing all saved sessions.
|
||||
|
||||
- **TUI — Dracula Theme and Notification System**: Default theme is Dracula (all 17+
|
||||
Textual built-in themes supported, switchable via `/theme <name>`). The Flash bar
|
||||
(height: 1, above the prompt) displays transient info/warning/error/success notifications.
|
||||
Block cursor navigation in the conversation stream via `alt+up`/`alt+down`.
|
||||
|
||||
- **TUI — Content Pruning and Safety Behaviors**: Conversation stream auto-collapses old
|
||||
messages when the block count exceeds the configurable threshold (default: 500). Shell
|
||||
danger detection highlights destructive command patterns before execution. Inline
|
||||
`PermissionQuestionWidget` renders permission requests in the conversation stream for
|
||||
single-file operations; multi-file operations push the full `PermissionsScreen`.
|
||||
|
||||
---
|
||||
|
||||
## [3.6.0] — Unreleased (In Progress — ~33%)
|
||||
|
||||
### Added
|
||||
|
||||
- **Advanced Context Strategies**: Extended the ACMS pipeline with cross-project context
|
||||
merging, incremental context updates, semantic deduplication, adaptive tier promotion,
|
||||
and resource-type-aware budgeting. Added new CRP directive types: `focus_path`,
|
||||
`exclude_pattern`, `max_fragment_size`, and `semantic_group`. See
|
||||
`docs/advanced-concepts.md` for full documentation.
|
||||
|
||||
- **Additional LLM Backends**: Added first-class provider support for Google Gemini
|
||||
(`google/gemini-*`), Mistral AI (`mistral/*`), Ollama local inference (`ollama/*`),
|
||||
LM Studio (`lmstudio/*`), Azure OpenAI (`azure/*`), AWS Bedrock (`bedrock/*`), and
|
||||
Groq (`groq/*`). All providers support a common base argument set plus provider-specific
|
||||
extensions. Provider fallback chains allow automatic retry on rate limit or outage.
|
||||
|
||||
- **Additional Resource Types**: Added cloud infrastructure resource types (`aws-s3-bucket`,
|
||||
`aws-lambda-function`, `gcp-storage-bucket`, `azure-blob-container`, `terraform-workspace`,
|
||||
`pulumi-stack`), database resource types (`postgres-schema`, `mysql-database`,
|
||||
`sqlite-file`, `mongodb-collection`, `redis-keyspace`), and virtual resource types
|
||||
(`virtual-aggregate`, `virtual-diff`, `virtual-search-index`, `virtual-dependency-graph`).
|
||||
|
||||
- **ACP to A2A Module Rename**: Completed the rename of `cleveragents.acp` to
|
||||
`cleveragents.a2a`, aligning all symbols with the adopted A2A standard (ADR-047).
|
||||
A compatibility shim preserves backward compatibility until v4.0.0. Affected symbols:
|
||||
`AcpClient` to `A2AClient`, `AcpMessage` to `A2AMessage`, `AcpTask` to `A2ATask`,
|
||||
`AcpEvent` to `A2AEvent`, `acp_server_url` config key to `a2a_server_url`.
|
||||
|
||||
- **Container Tool Execution**: Added `ContainerToolExecutor` for running tools inside
|
||||
isolated container environments. Tools declare container requirements (image, mounts,
|
||||
environment) in their YAML definition. Supports devcontainer integration via the
|
||||
`devcontainer-instance` resource type (ADR-043) — when a project has
|
||||
`.devcontainer/devcontainer.json`, CleverAgents can use it as the execution environment
|
||||
for all tools in that project.
|
||||
|
||||
- **Pluggable Scope Chain Resolution**: Made the scope chain resolution system extensible
|
||||
via the `ScopeChainResolver` protocol. Built-in resolvers: `PersonaScopeResolver`,
|
||||
`ReferenceResolver`, `DependencyGraphResolver`, `RecentlyModifiedResolver`,
|
||||
`TestCoverageResolver`. Custom resolvers are registered via the plugin entry point system.
|
||||
|
||||
- **Cost and Session Budgets**: Added comprehensive cost tracking (input/output tokens,
|
||||
USD cost, model, session/plan attribution) stored in SQLite. Budget enforcement via
|
||||
`SafetyProfile` fields (`max_cost_per_plan`, `max_total_cost`). When a budget is exceeded,
|
||||
the plan transitions to `PAUSED` with `pause_reason = "budget_exceeded"` and is resumable
|
||||
after the budget is increased. New CLI commands: `agents session cost`,
|
||||
`agents plan cost <id>`.
|
||||
|
||||
- **Safety Profiles (Full Enforcement)**: Completed safety profile enforcement (ADR-041)
|
||||
in the plan lifecycle. Added six named built-in profiles: `strict`, `standard`,
|
||||
`permissive`, `read-only`, `cost-capped-1usd`, `cost-capped-5usd`. Safety profiles
|
||||
are now enforced at plan creation, execution, and apply phases.
|
||||
|
||||
- **E2E Workflow Specification Tests**: Added a new `e2e` nox session with Robot Framework
|
||||
and Behave test suites covering full plan lifecycle workflows, multi-project workflows,
|
||||
provider-specific behavior, safety profile enforcement, and budget enforcement.
|
||||
|
||||
- **Code Review Tool Examples**: Added example actors and skills for code review workflows
|
||||
in `examples/actors/` and `examples/skills/`: `code-reviewer`, `pr-summarizer`,
|
||||
`test-generator`, `doc-writer`, `security-scanner`, `style-checker`.
|
||||
|
||||
- **Plugin Architecture Extensions**: Formalized the plugin architecture with entry points
|
||||
for resource types, tool executors, scope resolvers, and LLM providers. The `PluginLoader`
|
||||
enforces module allowlists, entry point validation, and capability declarations.
|
||||
Added plugin development guide at `docs/development/plugin-development.md`.
|
||||
|
||||
- **Advanced Concepts Documentation** (`docs/advanced-concepts.md`): Added comprehensive
|
||||
documentation for all v3.6.0 features including advanced context strategies, additional
|
||||
LLM backends, new resource types, ACP-to-A2A migration guide, container tool execution,
|
||||
pluggable scope chain resolution, cost/session budgets, safety profiles, E2E tests,
|
||||
code review examples, and plugin architecture extensions.
|
||||
|
||||
- **TUI Documentation** (`docs/tui.md`): Added comprehensive documentation for the v3.7.0
|
||||
TUI implementation covering installation, getting started, main screen layout, sidebar
|
||||
states, persona system, reference and command input, session management, configuration,
|
||||
key bindings, theme and styling, TuiMaterializer integration, real-time A2A event
|
||||
subscription, content pruning, and safety behaviors.
|
||||
|
||||
---
|
||||
|
||||
## [3.8.0] — 2026-04-05
|
||||
|
||||
### Added
|
||||
|
||||
@@ -323,13 +431,15 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
`INVARIANT_VIOLATED` events. Post-correction reconciliation runs
|
||||
via `CORRECTION_APPLIED` event subscription (best-effort). Added
|
||||
`InvariantService` Singleton provider in the DI container.
|
||||
- **TUI -- Shell danger detection**: The TUI shell mode (`!` prefix) now detects
|
||||
- **TUI — Shell danger detection**: The TUI shell mode (`!` prefix) now detects
|
||||
dangerous command patterns before execution. A configurable pattern registry
|
||||
classifies commands by danger level (warning, critical) and surfaces a user
|
||||
warning overlay before proceeding. Patterns cover destructive filesystem
|
||||
operations, privilege escalation, network exfiltration, and more. (#1003)
|
||||
|
||||
- **TUI -- Permission Question Widget**: A new inline `PermissionQuestionWidget`
|
||||
- **TUI — Permission Question Widget**: A new inline `PermissionQuestionWidget`
|
||||
renders permission requests directly in the conversation stream for single-file
|
||||
operations. Users can allow/reject with single-key shortcuts (`a`/`A`/`r`/`R`),
|
||||
navigate with arrow keys, confirm with `Enter`, or press `v` to open the full
|
||||
`PermissionsScreen` for multi-file diff review. For multi-file operations,
|
||||
`PermissionsScreen` is pushed directly (no inline widget). (#1004)
|
||||
|
||||
@@ -24,3 +24,4 @@ Below are some of the specific details of various contributions.
|
||||
* This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc.
|
||||
* HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system.
|
||||
* HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559).
|
||||
* HAL 9000 has contributed comprehensive milestone documentation for v3.6.0 (Advanced Concepts & Deferred Features) and v3.7.0 (TUI Implementation) (PR #9903): split into sub-documents covering context strategies, LLM backends, resource types, A2A rename, container tool execution, scope chain resolution, cost/safety budgets, E2E workflow tests, code review examples, plugin architecture, TUI layout, persona system, reference/command input, session management, configuration, and TuiMaterializer integration.
|
||||
|
||||
@@ -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*
|
||||
@@ -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*
|
||||
@@ -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*
|
||||
@@ -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*
|
||||
@@ -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*
|
||||
@@ -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*
|
||||
@@ -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*
|
||||
@@ -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*
|
||||
+10
@@ -43,6 +43,16 @@ nav:
|
||||
- Custom Sandbox Strategy: development/custom_sandbox_strategy.md
|
||||
- Documentation Writer: development/docs-writer.md
|
||||
- Implementation Timeline: timeline.md
|
||||
- Advanced Concepts (v3.6.0):
|
||||
- Overview & Context Strategies: advanced-concepts/index.md
|
||||
- Resource Types & A2A Rename: advanced-concepts/resource-types.md
|
||||
- Container Tools, Scope Chain, Budgets & Safety: advanced-concepts/container-tools.md
|
||||
- E2E Tests, Code Review & Plugins: advanced-concepts/e2e-tests-and-plugins.md
|
||||
- TUI Guide (v3.7.0):
|
||||
- Overview & Main Screen: tui/index.md
|
||||
- Sidebar States & Persona System: tui/sidebar-and-personas.md
|
||||
- Reference/Command Input & Sessions: tui/input-and-sessions.md
|
||||
- Configuration, Key Bindings & Integration: tui/configuration-and-integration.md
|
||||
- FAQ: faq.md
|
||||
- Reference: reference/
|
||||
- Architecture Decision Records (ADRs):
|
||||
|
||||
Reference in New Issue
Block a user