From 3422f29927c8c43174436c3035baefc3e6e9a680 Mon Sep 17 00:00:00 2001 From: HAL 9000 Date: Thu, 16 Apr 2026 00:03:09 +0000 Subject: [PATCH 1/2] docs(milestone): add v3.6.0 Advanced Concepts and v3.7.0 TUI documentation [AUTO-DOCS-5] Added comprehensive documentation for milestones v3.6.0 (Advanced Concepts and Deferred Features, ~33% complete) and v3.7.0 (TUI Implementation, ~42% complete). New files: - docs/advanced-concepts.md: Covers advanced context strategies, additional LLM backends (Gemini, Mistral, Ollama, Azure, Bedrock, Groq), new resource types (cloud infra, database, virtual), ACP-to-A2A migration guide, container tool execution, pluggable scope chain resolution, cost/session budgets, safety profiles, E2E workflow tests, code review examples, and plugin architecture. - docs/tui.md: Covers TUI installation, first-run experience, MainScreen layout, three-state sidebar, persona system (ADR-045), reference/command input system (ADR-046), session management with SQLite persistence, configuration, key bindings, Dracula theme, TuiMaterializer integration, real-time A2A event subscription, content pruning, and safety behaviors. Updated files: - CHANGELOG.md: Extended with [3.7.0] and [3.6.0] unreleased sections documenting all planned features for both milestones. - mkdocs.yml: Added navigation entries Advanced Concepts (v3.6.0) and TUI Guide (v3.7.0) between Implementation Timeline and FAQ. Related previous docs PRs: #9853 (v3.0.0+v3.1.0), #9796 (v3.2.0+v3.3.0), --- CHANGELOG.md | 194 +++++++++--- docs/advanced-concepts.md | 554 +++++++++++++++++++++++++++++++++ docs/tui.md | 634 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 + 4 files changed, 1342 insertions(+), 42 deletions(-) create mode 100644 docs/advanced-concepts.md create mode 100644 docs/tui.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 46bd4bb64..5e56f4cda 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 `). 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 `. + +- **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) diff --git a/docs/advanced-concepts.md b/docs/advanced-concepts.md new file mode 100644 index 000000000..8d49f6a9e --- /dev/null +++ b/docs/advanced-concepts.md @@ -0,0 +1,554 @@ +# 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. + +--- + +## 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. + +--- + +## 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. + +--- + +## 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 # 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 ` + and resume the plan with `agents plan resume ` + +--- + +## 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 +``` + +--- + +## 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* diff --git a/docs/tui.md b/docs/tui.md new file mode 100644 index 000000000..d1a8409a4 --- /dev/null +++ b/docs/tui.md @@ -0,0 +1,634 @@ +# 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. + +### 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. + +--- + +## 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 `** — 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. + +--- + +## 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` + +--- + +## 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 + +--- + +## 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. + +--- + +## 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 | +| [ADR-046](adr/ADR-046-tui-reference-and-command-system.md) | TUI Reference and Command System | @ references, / commands, ! shell | +| [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 | +| [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* diff --git a/mkdocs.yml b/mkdocs.yml index 48a98aa71..65cfeec35 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,8 @@ nav: - Custom Sandbox Strategy: development/custom_sandbox_strategy.md - Documentation Writer: development/docs-writer.md - Implementation Timeline: timeline.md + - Advanced Concepts (v3.6.0): advanced-concepts.md + - TUI Guide (v3.7.0): tui.md - FAQ: faq.md - Reference: reference/ - Architecture Decision Records (ADRs): -- 2.52.0 From 42b25aed5ead5c142c54003a810cabf41f859608 Mon Sep 17 00:00:00 2001 From: HAL9000 Date: Sat, 25 Apr 2026 00:26:18 +0000 Subject: [PATCH 2/2] docs(milestone): split advanced-concepts and tui docs into sub-documents 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 --- CONTRIBUTORS.md | 1 + docs/advanced-concepts.md | 554 --------------- docs/advanced-concepts/container-tools.md | 248 +++++++ .../e2e-tests-and-plugins.md | 138 ++++ docs/advanced-concepts/index.md | 117 ++++ docs/advanced-concepts/resource-types.md | 112 ++++ docs/tui.md | 634 ------------------ docs/tui/configuration-and-integration.md | 209 ++++++ docs/tui/index.md | 166 +++++ docs/tui/input-and-sessions.md | 156 +++++ docs/tui/sidebar-and-personas.md | 158 +++++ mkdocs.yml | 12 +- 12 files changed, 1315 insertions(+), 1190 deletions(-) delete mode 100644 docs/advanced-concepts.md create mode 100644 docs/advanced-concepts/container-tools.md create mode 100644 docs/advanced-concepts/e2e-tests-and-plugins.md create mode 100644 docs/advanced-concepts/index.md create mode 100644 docs/advanced-concepts/resource-types.md delete mode 100644 docs/tui.md create mode 100644 docs/tui/configuration-and-integration.md create mode 100644 docs/tui/index.md create mode 100644 docs/tui/input-and-sessions.md create mode 100644 docs/tui/sidebar-and-personas.md diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index f7f84a8a7..f79bb5dd5 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -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. diff --git a/docs/advanced-concepts.md b/docs/advanced-concepts.md deleted file mode 100644 index 8d49f6a9e..000000000 --- a/docs/advanced-concepts.md +++ /dev/null @@ -1,554 +0,0 @@ -# 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. - ---- - -## 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. - ---- - -## 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. - ---- - -## 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 # 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 ` - and resume the plan with `agents plan resume ` - ---- - -## 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 -``` - ---- - -## 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* diff --git a/docs/advanced-concepts/container-tools.md b/docs/advanced-concepts/container-tools.md new file mode 100644 index 000000000..f4a3d19d8 --- /dev/null +++ b/docs/advanced-concepts/container-tools.md @@ -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 # 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 ` + and resume the plan with `agents plan resume ` + +--- + +## 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* diff --git a/docs/advanced-concepts/e2e-tests-and-plugins.md b/docs/advanced-concepts/e2e-tests-and-plugins.md new file mode 100644 index 000000000..7d3c35fd4 --- /dev/null +++ b/docs/advanced-concepts/e2e-tests-and-plugins.md @@ -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* diff --git a/docs/advanced-concepts/index.md b/docs/advanced-concepts/index.md new file mode 100644 index 000000000..6d70b87e3 --- /dev/null +++ b/docs/advanced-concepts/index.md @@ -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* diff --git a/docs/advanced-concepts/resource-types.md b/docs/advanced-concepts/resource-types.md new file mode 100644 index 000000000..dab8d470e --- /dev/null +++ b/docs/advanced-concepts/resource-types.md @@ -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* diff --git a/docs/tui.md b/docs/tui.md deleted file mode 100644 index d1a8409a4..000000000 --- a/docs/tui.md +++ /dev/null @@ -1,634 +0,0 @@ -# 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. - -### 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. - ---- - -## 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 `** — 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. - ---- - -## 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` - ---- - -## 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 - ---- - -## 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. - ---- - -## 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 | -| [ADR-046](adr/ADR-046-tui-reference-and-command-system.md) | TUI Reference and Command System | @ references, / commands, ! shell | -| [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 | -| [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* diff --git a/docs/tui/configuration-and-integration.md b/docs/tui/configuration-and-integration.md new file mode 100644 index 000000000..a665099b3 --- /dev/null +++ b/docs/tui/configuration-and-integration.md @@ -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* diff --git a/docs/tui/index.md b/docs/tui/index.md new file mode 100644 index 000000000..95ab5a5fd --- /dev/null +++ b/docs/tui/index.md @@ -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* diff --git a/docs/tui/input-and-sessions.md b/docs/tui/input-and-sessions.md new file mode 100644 index 000000000..659f55d18 --- /dev/null +++ b/docs/tui/input-and-sessions.md @@ -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* diff --git a/docs/tui/sidebar-and-personas.md b/docs/tui/sidebar-and-personas.md new file mode 100644 index 000000000..f533b4b15 --- /dev/null +++ b/docs/tui/sidebar-and-personas.md @@ -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 `** — 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* diff --git a/mkdocs.yml b/mkdocs.yml index 65cfeec35..bc1a2d3c2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,8 +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): advanced-concepts.md - - TUI Guide (v3.7.0): tui.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): -- 2.52.0