Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 CleverAgents Bot
|
90336a5290 | ||
 HAL9000
|
07175518dc |
@@ -3,8 +3,6 @@ name: CI
|
||||
on:
|
||||
push:
|
||||
branches: [master, develop]
|
||||
pull_request:
|
||||
branches: [master, develop]
|
||||
|
||||
vars:
|
||||
docker_prefix: "http://harbor.cleverthis.com/docker/"
|
||||
|
||||
@@ -209,7 +209,7 @@ Evaluate the PR against the following 10 categories, in order of importance. Loa
|
||||
|
||||
1. **CORRECTNESS** — Does the code do what the linked issue says it should? Do all acceptance criteria pass? Are edge cases handled?
|
||||
|
||||
2. **SPECIFICATION ALIGNMENT** — Does the code align with `docs/specification.md`? If code departs from spec, it is wrong — request correction.
|
||||
2. **SPECIFICATION ALIGNMENT** — Does the code align with `docs/specification/` (see `docs/specification/index.md`)? If code departs from spec, it is wrong — request correction.
|
||||
|
||||
3. **TEST QUALITY** — Are there Behave BDD scenarios for all new behavior? Are integration tests updated if component interfaces changed? Are edge cases AND error/failure paths covered? Does coverage stay >= 97%? For bug fixes: does a `@tdd_issue_N` regression test exist? Are Gherkin scenarios well-named and readable as living documentation?
|
||||
|
||||
|
||||
@@ -85,7 +85,7 @@ Some examples of things covered by this skill:
|
||||
- Plan lifecycle migration (agents plan use vs agents tell, ULID format, separate
|
||||
storage backends, no migration path)
|
||||
- Backwards compatibility policy (none pre-v3.0.0)
|
||||
- docs/specification.md as authoritative source
|
||||
- docs/specification/ as authoritative source (see docs/specification/index.md)
|
||||
- Hatch + pyproject.toml toolchain
|
||||
- Pre-commit hooks via scripts/setup-dev.sh.
|
||||
|
||||
@@ -639,16 +639,16 @@ Issue creation — complete requirements:
|
||||
```
|
||||
Before touching any production code:
|
||||
│
|
||||
├─ STEP 1: READ docs/specification.md FIRST (mandatory)
|
||||
│ ├─ Find the sections relevant to your task
|
||||
│ ├─ Read them completely — understand the intended design
|
||||
├─ STEP 1: READ docs/specification/ FIRST (mandatory)
|
||||
│ ├─ Open docs/specification/index.md to find the relevant sub-document
|
||||
│ ├─ Read the relevant sections completely — understand the intended design
|
||||
│ ├─ If the spec and the current codebase disagree:
|
||||
│ │ → The SPEC is correct. Align the code to the spec.
|
||||
│ │ → NEVER adjust the spec to match broken code
|
||||
│ └─ Architectural changes → ADR process required BEFORE writing any code
|
||||
│ 1. Write the ADR document (see "Am I documenting something?" for format)
|
||||
│ 2. Submit for review and approval via PR
|
||||
│ 3. Once approved → update docs/specification.md
|
||||
│ 3. Once approved → update docs/specification/ with the new decision
|
||||
│ 4. THEN write the code
|
||||
│
|
||||
├─ STEP 2: Does a verified issue exist for this work?
|
||||
@@ -896,7 +896,7 @@ Code review — what to assess and how to decide:
|
||||
│ │ └─ Are there edge cases not covered that could cause production failures?
|
||||
│ │
|
||||
│ ├─ SPECIFICATION ALIGNMENT
|
||||
│ │ ├─ Does it align with docs/specification.md?
|
||||
│ │ ├─ Does it align with docs/specification/ (see docs/specification/index.md)?
|
||||
│ │ └─ If code departs from spec → it is wrong; request correction
|
||||
│ │
|
||||
│ ├─ TEST QUALITY
|
||||
@@ -1007,7 +1007,7 @@ File placement rules for this project (every path is exact — no variations):
|
||||
├─ Is this DOCUMENTATION?
|
||||
│ └─ → /docs/
|
||||
│ ├─ Must be written in MkDocs-compatible markdown
|
||||
│ ├─ docs/specification.md → THE authoritative architecture spec
|
||||
│ ├─ docs/specification/ → THE authoritative architecture spec (see docs/specification/index.md)
|
||||
│ │ ⚠️ Only modify via ADR process, never to match broken code
|
||||
│ └─ Build with: nox -s docs
|
||||
│
|
||||
@@ -1471,7 +1471,7 @@ Diagnosing CI failures in this project:
|
||||
Documentation standards for this project:
|
||||
│
|
||||
├─ WHERE DOES DOCUMENTATION LIVE?
|
||||
│ ├─ Architecture and design decisions → docs/specification.md
|
||||
│ ├─ Architecture and design decisions → docs/specification/ (see docs/specification/index.md)
|
||||
│ │ (modify only via ADR process — see below)
|
||||
│ ├─ User-facing guides, API docs, how-tos → docs/ (MkDocs format)
|
||||
│ ├─ Code documentation → docstrings/inline comments in source files
|
||||
@@ -1532,12 +1532,12 @@ Documentation standards for this project:
|
||||
│ ├─ PROCESS:
|
||||
│ │ 1. Create the ADR document in docs/adr/ (ADR-NNN-title.md)
|
||||
│ │ 2. Submit for review via PR (labeled as an ADR)
|
||||
│ │ 3. Approved → update docs/specification.md with the new decision
|
||||
│ │ 3. Approved → update docs/specification/ with the new decision
|
||||
│ │ 4. THEN write the code
|
||||
│ └─ ⚠️ Never edit docs/specification.md to match incorrect code
|
||||
│ └─ ⚠️ Never edit docs/specification/ to match incorrect code
|
||||
│
|
||||
├─ DOCS/SPECIFICATION.MD (the most important doc)
|
||||
│ ├─ Read this BEFORE starting any task — relevant sections
|
||||
├─ DOCS/SPECIFICATION/ (the most important docs)
|
||||
│ ├─ Read relevant sub-documents BEFORE starting any task (see docs/specification/index.md)
|
||||
│ ├─ When code and spec disagree → code is wrong; align code to spec
|
||||
│ ├─ Proposing a spec change → ADR process required first
|
||||
│ └─ Never edit to reflect incorrect code — only to reflect approved decisions
|
||||
@@ -1564,7 +1564,7 @@ CleverAgents plan workflow — two mutually exclusive systems:
|
||||
│ ├─ Identifiers: ULID — 26-character Crockford base32
|
||||
│ │ e.g. 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||||
│ ├─ Storage: PlanLifecycleService
|
||||
│ └─ Authority: this is the authoritative workflow per docs/specification.md
|
||||
│ └─ Authority: this is the authoritative workflow per docs/specification/core-concepts.md
|
||||
│
|
||||
├─ LEGACY SYSTEM — DEPRECATED, DO NOT START NEW WORK HERE
|
||||
│ ├─ Commands:
|
||||
@@ -1777,7 +1777,7 @@ Development environment setup for this project:
|
||||
│ ├─ npm install -g commitizen@2.8.6 cz-customizable@4.0.0
|
||||
│ └─ Use git cz instead of git commit going forward
|
||||
│
|
||||
├─ STEP 6: Read docs/specification.md
|
||||
├─ STEP 6: Read docs/specification/ (see docs/specification/index.md)
|
||||
│ └─ Before touching ANY code, read the relevant specification sections
|
||||
│
|
||||
├─ COMPLETE TOOL INVENTORY FOR THIS PROJECT
|
||||
@@ -2081,7 +2081,7 @@ Design patterns in this project — use liberally, ad-hoc is NOT acceptable:
|
||||
| TDD assertion type | **`AssertionError` ONLY** | `assert` or `raise AssertionError(...)` |
|
||||
| TDD permanent tags | **`@tdd_issue`, `@tdd_issue_N`** | Never removed after merging |
|
||||
| TDD temporary tag | **`@tdd_expected_fail`** | Removed by bug fix developer |
|
||||
| Architecture spec | **`docs/specification.md`** | Authoritative — code aligns to it, not vice versa |
|
||||
| Architecture spec | **`docs/specification/`** | Authoritative — code aligns to it, not vice versa (see docs/specification/index.md) |
|
||||
| Commit first line | **Verbatim from issue Metadata** | When issue prescribes one — copy exactly |
|
||||
| PR dep direction | **PR → blocks → issue** | NEVER reversed — causes unresolvable deadlock |
|
||||
| Multi-level testing | **Unit + Integration + Benchmarks** | Every task must address all three |
|
||||
|
||||
@@ -24,7 +24,7 @@ entire lifecycle of that plan.
|
||||
|
||||
## v3 Workflow (Always Use This)
|
||||
|
||||
Per `docs/specification.md`, the v3 plan lifecycle is the authoritative workflow.
|
||||
Per `docs/specification/core-concepts.md`, the v3 plan lifecycle is the authoritative workflow.
|
||||
All new development uses v3 commands exclusively.
|
||||
|
||||
```bash
|
||||
|
||||
@@ -26,7 +26,7 @@ cleveragents/ ← repository root
|
||||
│ └─ *.resource
|
||||
│
|
||||
├─ docs/ ← ALL documentation (MkDocs format)
|
||||
│ ├─ specification.md ← authoritative architecture spec
|
||||
│ ├─ specification/ ← authoritative architecture spec (see specification/index.md)
|
||||
│ └─ *.md
|
||||
│
|
||||
├─ config/ ← configuration files
|
||||
@@ -108,15 +108,15 @@ real databases, real message queues. No test doubles permitted.
|
||||
- Markdown files in MkDocs-compatible format
|
||||
- Images, diagrams, and supporting assets
|
||||
|
||||
#### `docs/specification.md` — Authoritative Architecture Spec
|
||||
#### `docs/specification/` — Authoritative Architecture Spec
|
||||
|
||||
This file is **the authoritative source of truth** for all architectural and
|
||||
design decisions. Rules:
|
||||
This directory is **the authoritative source of truth** for all architectural and
|
||||
design decisions. See `docs/specification/index.md` for navigation. Rules:
|
||||
|
||||
- Read the relevant sections **before beginning any task**
|
||||
- Read the relevant sub-document sections **before beginning any task**
|
||||
- When code contradicts specification → **fix the code, not the spec**
|
||||
- Spec changes → ADR process required first; approved ADR → spec update → code update
|
||||
- Never edit `docs/specification.md` to match broken code
|
||||
- Never edit `docs/specification/` to match broken code
|
||||
|
||||
### `/config/` — Configuration Files
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ name: cleveragents-spec
|
||||
description: |
|
||||
Complete specification skill for CleverAgents — covering every architectural
|
||||
concept, entity, workflow, CLI command, and design decision from
|
||||
docs/specification.md. This skill explains WHAT the system is intended to
|
||||
docs/specification/. This skill explains WHAT the system is intended to
|
||||
build, and HOW all its parts fit together.
|
||||
|
||||
Use this skill whenever you need to know: what a Plan is and how its four
|
||||
@@ -69,7 +69,7 @@ references:
|
||||
> code to it (testing, nox, CI, branch naming), use the `cleveragents-contributing`
|
||||
> skill. For company-wide policies and process, use `cleverthis-guidelines`.
|
||||
>
|
||||
> **Source of truth**: `docs/specification.md`. When implementation and this skill
|
||||
> **Source of truth**: `docs/specification/` (see `docs/specification/index.md`). When implementation and this skill
|
||||
> disagree, the specification is authoritative. Align code to spec, not vice versa.
|
||||
|
||||
---
|
||||
|
||||
@@ -203,7 +203,7 @@ What are you about to do?
|
||||
Before writing any code:
|
||||
│
|
||||
├─ SPECIFICATION FIRST (mandatory step)
|
||||
│ ├─ Open docs/specification.md
|
||||
│ ├─ Open docs/specification/ (see docs/specification/index.md)
|
||||
│ ├─ Read ALL sections relevant to your task
|
||||
│ ├─ Understand the intended architecture and design
|
||||
│ └─ If code ≠ specification → ALWAYS align code to specification
|
||||
@@ -1100,11 +1100,11 @@ Architectural Decision Record (ADR) process:
|
||||
├─ ADR process:
|
||||
│ ├─ Capture proposed change in an ADR document
|
||||
│ ├─ Submit for review and approval
|
||||
│ ├─ Once approved → incorporate into specification (docs/specification.md)
|
||||
│ ├─ Once approved → incorporate into specification (docs/specification/)
|
||||
│ └─ Implementation ONLY after specification is updated
|
||||
│
|
||||
├─ Source of truth priority:
|
||||
│ ├─ docs/specification.md is AUTHORITATIVE
|
||||
│ ├─ docs/specification/ is AUTHORITATIVE (see docs/specification/index.md)
|
||||
│ ├─ When code ≠ specification → align code to specification
|
||||
│ └─ Never adjust specification to match incorrect code
|
||||
│
|
||||
@@ -1241,7 +1241,7 @@ Documentation standards (all code-related docs):
|
||||
│ └─ Avoid duplicate or parallel documentation for the same content
|
||||
│
|
||||
├─ SPECIFICATION vs. CODE
|
||||
│ ├─ docs/specification.md is THE authoritative source of truth
|
||||
│ ├─ docs/specification/ is THE authoritative source of truth (see docs/specification/index.md)
|
||||
│ ├─ Before any task: review relevant specification sections
|
||||
│ ├─ When code ≠ spec → code is wrong, align code to spec
|
||||
│ └─ Spec changes: go through ADR process, not ad-hoc edits
|
||||
@@ -1419,7 +1419,7 @@ File organization — every file has a canonical home:
|
||||
│
|
||||
├─ /docs/
|
||||
│ ├─ Documentation and markdown files (project: MkDocs format)
|
||||
│ ├─ docs/specification.md → THE authoritative architecture specification
|
||||
│ ├─ docs/specification/ → THE authoritative architecture specification (see docs/specification/index.md)
|
||||
│ └─ API docs, user guides, architecture docs, changelog
|
||||
│
|
||||
├─ /config/
|
||||
@@ -1482,7 +1482,7 @@ Development environment setup (new contributor checklist):
|
||||
│
|
||||
├─ STEP 5: Read key documents
|
||||
│ ├─ CONTRIBUTING.md → all project rules (top priority)
|
||||
│ ├─ docs/specification.md → architecture and design decisions
|
||||
│ ├─ docs/specification/ → architecture and design decisions (see docs/specification/index.md)
|
||||
│ └─ This skill file → procedural decision trees
|
||||
│
|
||||
├─ VERIFICATION CHECKLIST (examples use Python/nox)
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
|
||||
## General Principles
|
||||
|
||||
1. **Specification-First Development**: `docs/specification.md` is authoritative. Code discrepancies → align code to spec (never adjust spec to match code). Architectural changes require ADR process first.
|
||||
1. **Specification-First Development**: `docs/specification/` is authoritative (see `docs/specification/index.md`). Code discrepancies → align code to spec (never adjust spec to match code). Architectural changes require ADR process first.
|
||||
2. **Modern Tooling**: Use modern, idiomatic build tools and workflows for the project's language ecosystem. Avoid legacy approaches such as Makefiles or wrapper shell scripts. All tooling should be from the current ecosystem and used as designed — not wrapped in custom scripts.
|
||||
3. **Prefer Existing Tooling**: Don't add new dependencies when existing tools suffice. Keep the toolchain simple and consistent.
|
||||
4. **Modular Design**: Files under 500 lines. Break large files into focused, cohesive modules.
|
||||
|
||||
+17
-3
@@ -1157,10 +1157,24 @@ All files must be organized in the following project directories:
|
||||
|
||||
### Specification
|
||||
|
||||
`docs/specification.md` is the authoritative source of truth for architectural decisions and
|
||||
`docs/specification/` is the authoritative source of truth for architectural decisions and
|
||||
design details. Before beginning any task, always review the relevant parts of the specification
|
||||
to understand the fine architectural details. When there is a discrepancy between the current
|
||||
codebase and the specification document, always assume the specification document is correct.
|
||||
codebase and the specification, always assume the specification is correct.
|
||||
|
||||
The specification is organized into logical sub-documents:
|
||||
|
||||
- [`docs/specification/index.md`](docs/specification/index.md) — Navigation index
|
||||
- [`docs/specification/overview.md`](docs/specification/overview.md) — Overview and glossary
|
||||
- [`docs/specification/cli.md`](docs/specification/cli.md) — CLI command reference
|
||||
- [`docs/specification/core-concepts.md`](docs/specification/core-concepts.md) — Core domain concepts
|
||||
- [`docs/specification/behavior.md`](docs/specification/behavior.md) — Automation profiles and guardrails
|
||||
- [`docs/specification/tui.md`](docs/specification/tui.md) — TUI architecture
|
||||
- [`docs/specification/configuration.md`](docs/specification/configuration.md) — Configuration reference
|
||||
- [`docs/specification/examples.md`](docs/specification/examples.md) — Workflow examples
|
||||
- [`docs/specification/architecture.md`](docs/specification/architecture.md) — System architecture
|
||||
- [`docs/specification/milestones.md`](docs/specification/milestones.md) — Milestone plan
|
||||
- [`docs/specification/acms.md`](docs/specification/acms.md) — ACMS v1 specification
|
||||
|
||||
### BDD Framework
|
||||
|
||||
@@ -1488,7 +1502,7 @@ commands (`agents tell`, `agents build`, `agents continue`, `agents current`, `a
|
||||
|
||||
### The V3 Plan Lifecycle Workflow
|
||||
|
||||
The v3 plan lifecycle is the authoritative workflow per `docs/specification.md`. All development
|
||||
The v3 plan lifecycle is the authoritative workflow per `docs/specification/core-concepts.md`. All development
|
||||
uses v3 commands exclusively:
|
||||
|
||||
| Operation | Command | Notes |
|
||||
|
||||
@@ -1158,10 +1158,12 @@ All files must be organized in the following project directories:
|
||||
|
||||
### Specification
|
||||
|
||||
`docs/specification.md` is the authoritative source of truth for architectural decisions and
|
||||
`docs/specification/` is the authoritative source of truth for architectural decisions and
|
||||
design details. Before beginning any task, always review the relevant parts of the specification
|
||||
to understand the fine architectural details. When there is a discrepancy between the current
|
||||
codebase and the specification document, always assume the specification document is correct.
|
||||
codebase and the specification, always assume the specification is correct.
|
||||
|
||||
The specification is organized into logical sub-documents — see [`docs/specification/index.md`](specification/index.md) for navigation.
|
||||
|
||||
### BDD Framework
|
||||
|
||||
@@ -1508,7 +1510,7 @@ with an explicit error message explaining the incompatibility.
|
||||
|
||||
### The v3 Workflow (Recommended)
|
||||
|
||||
The v3 plan lifecycle is the authoritative workflow per `docs/specification.md`. All new
|
||||
The v3 plan lifecycle is the authoritative workflow per `docs/specification/core-concepts.md`. All new
|
||||
development should use v3 commands exclusively:
|
||||
|
||||
```bash
|
||||
|
||||
+23
-48071
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,747 @@
|
||||
## ACMS v1 — Advanced Context Management System (Milestone v3.4.0)
|
||||
|
||||
### Overview
|
||||
|
||||
The **Advanced Context Management System (ACMS) v1** is the context intelligence layer of
|
||||
CleverAgents. It provides a principled, scalable mechanism for indexing project knowledge,
|
||||
assembling budget-constrained context views, and delivering scoped context payloads to actors
|
||||
for LLM calls. ACMS v1 is the primary deliverable of milestone **v3.4.0 — ACMS v1 + Context
|
||||
Scaling**.
|
||||
|
||||
ACMS is built on two foundational subsystems:
|
||||
|
||||
- **UKO (Unified Knowledge Ontology)** — a layered RDF/Turtle ontology that indexes project
|
||||
files, symbols, relationships, and semantic concepts into a queryable knowledge graph.
|
||||
- **CRP (Context Request Protocol)** — a structured protocol through which actors declare
|
||||
what information they need, at what level of detail, and with what scope, triggering a
|
||||
context assembly cycle in the ACMS pipeline.
|
||||
|
||||
Together, UKO and CRP power a **10-component context assembly pipeline** that transforms raw
|
||||
retrieval results into a budget-constrained, coherently ordered context window for each actor.
|
||||
|
||||
**Design goals for ACMS v1:**
|
||||
|
||||
- Support projects with 10,000+ files without timeout or memory exhaustion.
|
||||
- Respect hard token budget ceilings derived from the actor's model context window.
|
||||
- Enable multiple complementary retrieval strategies (keyword, semantic, graph, LLM-driven).
|
||||
- Provide tiered context lifecycle management (hot/warm/cold) with per-actor visibility.
|
||||
- Expose a clean CLI interface for context inspection, simulation, and policy management.
|
||||
|
||||
---
|
||||
|
||||
### Architecture
|
||||
|
||||
#### UKO — Unified Knowledge Ontology
|
||||
|
||||
UKO is the indexing layer. It transforms project resources into a queryable hierarchy of
|
||||
knowledge nodes, each with multiple detail depths enabling progressive disclosure.
|
||||
|
||||
**Layer structure:**
|
||||
|
||||
| Layer | Prefix(es) | IRI Namespace | Purpose |
|
||||
|-------|------------|---------------|---------|
|
||||
| 0 | `uko:` | `https://cleveragents.ai/ontology/uko#` | Universal foundation — base information unit types and core relationships |
|
||||
| 1 | `uko-code:`, `uko-doc:`, `uko-data:`, `uko-infra:` | `https://cleveragents.ai/ontology/uko/code#` etc. | General software — modules, callables, types, tests, imports |
|
||||
| 2 | `uko-oo:`, `uko-func:`, `uko-proc:` | `https://cleveragents.ai/ontology/uko/oo#` etc. | Paradigm-specific — OO classes, interfaces, methods, attributes |
|
||||
| 3 | `uko-py:`, `uko-ts:`, `uko-rs:`, `uko-java:` | `https://cleveragents.ai/ontology/uko/py#` etc. | Technology-specific — DetailLevelMap insertions |
|
||||
|
||||
**Layer 0 root types:**
|
||||
|
||||
- `InformationUnit` — root of every UKO node; anything that can appear in an actor's context.
|
||||
- `Container` — an information unit that contains other units (file, module, class, section).
|
||||
- `Atom` — a leaf-level information unit (function body, paragraph, config value).
|
||||
- `Annotation` — metadata attached to another unit (comment, docstring, attribute).
|
||||
- `Boundary` — an interface point between containers (export, API endpoint, public method signature).
|
||||
|
||||
**Core relationship properties:**
|
||||
|
||||
- `contains` — parent contains child.
|
||||
- `references` — weak reference (e.g. a function mentions a type in a docstring).
|
||||
- `dependsOn` — strong dependency (import, inheritance, call).
|
||||
|
||||
**Detail depths** enable progressive disclosure:
|
||||
|
||||
| Depth | Question Answered | What Gets Included |
|
||||
|-------|-------------------|--------------------|
|
||||
| 0 | *What exists?* | Name/identifier only |
|
||||
| 1 | *How is it organized?* | Names of immediate children |
|
||||
| 2 | *What are the key relationships?* | Children + dependency/reference edges |
|
||||
| 3 | *What is each thing's purpose?* | + Short descriptions/summaries |
|
||||
| 4 | *What is the structural shape?* | + Type info, size/count metadata |
|
||||
| 5-8 | *How does it work?* | Progressively more content |
|
||||
| 9 | *Everything.* | Complete content — nothing omitted |
|
||||
|
||||
When context budget is tight, fragments are downgraded to shallower depths rather than omitted
|
||||
entirely (depth fallback).
|
||||
|
||||
**Provenance properties** on every UKO node:
|
||||
|
||||
- `sourceResource` — the CleverAgents Resource (by ULID) this node was extracted from.
|
||||
- `sourcePath` — file path within the resource.
|
||||
- `sourceRange` — byte or line range within the source file (e.g. `42:1-87:0`).
|
||||
|
||||
**Temporal properties** support versioned knowledge:
|
||||
|
||||
- `validFrom`, `validUntil`, `isCurrent`, `isRevisionOf`.
|
||||
|
||||
#### CRP — Context Request Protocol
|
||||
|
||||
CRP is the structured vocabulary through which actors declare context needs. Each
|
||||
`ContextRequest` triggers a context assembly cycle in the ACMS pipeline.
|
||||
|
||||
**ContextRequest fields:**
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `query` | `str \| None` | `None` | Natural language query |
|
||||
| `entities` | `list[str]` | `[]` | Named entities to focus on |
|
||||
| `uko_types` | `list[str]` | `[]` | UKO types to filter |
|
||||
| `focus` | `list[str]` | `[]` | URIs or identifiers to focus on |
|
||||
| `breadth` | `int` | `2` | Dependency hops outward (>= 0) |
|
||||
| `depth` | `int \| str` | `3` | Detail depth — integer or named level |
|
||||
| `depth_gradient` | `bool` | `True` | Items closer to focus get more detail |
|
||||
| `temporal` | `TemporalScope` | `CURRENT` | Temporal scope for retrieval |
|
||||
| `max_tokens` | `int \| None` | `None` | Maximum token budget (>= 0) |
|
||||
| `preferred_strategies` | `list[str]` | `[]` | Preferred context strategies |
|
||||
| `required_backends` | `list[str]` | `[]` | Required data backends |
|
||||
| `priority` | `float` | `0.5` | 0.0 = background, 1.0 = critical |
|
||||
| `purpose` | `str` | `""` | Why this context is needed |
|
||||
|
||||
**DetailLevelMap** maps named detail levels to integer depths for a UKO domain. Inheritance
|
||||
allows child maps to include all entries from their parent map and insert additional levels.
|
||||
|
||||
Built-in named levels (universal Layer 0):
|
||||
|
||||
| Name | Depth |
|
||||
|------|-------|
|
||||
| `MODULE_LISTING` | 0 |
|
||||
| `SIGNATURES` | 4 |
|
||||
| `FULL_SOURCE` | 9 |
|
||||
|
||||
#### Context Pipeline
|
||||
|
||||
The ACMS pipeline transforms a `ContextRequest` into an `AssembledContext` through five
|
||||
high-level stages:
|
||||
|
||||
1. **Indexing** — Project files are indexed into the UKO ontology by `RepoIndexingService`.
|
||||
Language-specific analyzers extract structural elements (functions, classes, modules, types)
|
||||
into UKO nodes with multiple detail depths. The index is persisted in SQLite and refreshed
|
||||
incrementally on file changes.
|
||||
|
||||
2. **Assembly** — A `ContextRequest` triggers the 10-component assembly pipeline.
|
||||
Strategies run in parallel; their results are fused, deduplicated, scored, and packed.
|
||||
|
||||
3. **Scoping** — Context is filtered by the project's `ProjectContextPolicy`. Each plan phase
|
||||
(`default` -> `strategize` -> `execute` -> `apply`) may override the policy view, controlling
|
||||
which resources and file paths are visible.
|
||||
|
||||
4. **Budget Enforcement** — `ContextBudgetEnforcer` applies `max_file_size` and
|
||||
`max_total_size` constraints. The token budget is a hard ceiling:
|
||||
|
||||
```
|
||||
budget = model_context_window - response_reserve (4096) - tool_definitions - skeleton_allocation
|
||||
```
|
||||
|
||||
Budget refresh is triggered when available budget changes by more than
|
||||
`context.budget.refresh-threshold` (default: 0.30).
|
||||
|
||||
5. **Delivery** — The assembled `AssembledContext` (or `ContextPayload`) is delivered to the
|
||||
actor for its LLM call. Child plans inherit a compressed skeleton of their parent's context
|
||||
(default: 15% of child's budget via `SkeletonCompressor`).
|
||||
|
||||
#### Storage Tiers
|
||||
|
||||
ACMS v1 manages context fragments across three storage tiers:
|
||||
|
||||
| Tier | Backend | Latency | Capacity | Actor Visibility |
|
||||
|------|---------|---------|----------|-----------------|
|
||||
| **Hot** | In-memory cache | Low | Token-budget (`max_tokens_hot`, default: 8,000) | All roles |
|
||||
| **Warm** | SQLite (fast disk) | Medium | Decision-count (`max_decisions_warm`, default: 500) | Strategist, Executor |
|
||||
| **Cold** | File archive (compressed) | High | Decision-count (`max_decisions_cold`, default: 5,000) | Strategist only |
|
||||
|
||||
**Actor roles and tier visibility:**
|
||||
|
||||
| Role | Sees |
|
||||
|------|------|
|
||||
| `strategist` | hot + warm + cold |
|
||||
| `executor` | hot + warm |
|
||||
| `reviewer` | hot only |
|
||||
|
||||
**Tier operations:**
|
||||
|
||||
- `promote(fragment_id)` — cold->warm or warm->hot.
|
||||
- `demote(fragment_id)` — hot->warm or warm->cold (with optional summarisation).
|
||||
- `evict_lru(tier, count)` — evict least-recently-used fragments from a tier.
|
||||
|
||||
> **v1 Note:** In v1, tier labels on `ContextFragment` are sort-priority labels used for
|
||||
> ranking during assembly (`hot > warm > cold`). Full storage-tier semantics with retention
|
||||
> policies, promotion/demotion, and eviction are implemented in `ContextTierService`.
|
||||
|
||||
---
|
||||
|
||||
### Module Definitions
|
||||
|
||||
ACMS v1 follows the project's layered architecture (Domain -> Application -> Infrastructure ->
|
||||
Presentation).
|
||||
|
||||
#### Domain Layer
|
||||
|
||||
Domain models are pure Pydantic v2 frozen dataclasses with ULID identifiers and UTC datetimes.
|
||||
No infrastructure dependencies.
|
||||
|
||||
| Class | Module | Description |
|
||||
|-------|--------|-------------|
|
||||
| `ContextFragment` | `cleveragents.domain.models.core.context_fragment` | Atomic unit of context with UKO node, content, depth, token count, relevance, provenance, and tier |
|
||||
| `FragmentProvenance` | `cleveragents.domain.models.core.context_fragment` | Links a fragment back to its originating resource and location |
|
||||
| `ContextBudget` | `cleveragents.domain.models.core.context_fragment` | Token budget with max and reserved tokens |
|
||||
| `ContextPayload` | `cleveragents.domain.models.core.context_fragment` | Assembled payload with fragments, token count, budget usage, context hash, and provenance map |
|
||||
| `ContextView` | `cleveragents.domain.models.core.context_policy` | Per-phase view controlling resource/path filters and size limits |
|
||||
| `ProjectContextPolicy` | `cleveragents.domain.models.core.context_policy` | Per-project policy with phase-based view inheritance |
|
||||
| `ContextRequest` | `cleveragents.domain.models.acms.crp` | Structured context request issued by an actor via CRP |
|
||||
| `DetailLevelMap` | `cleveragents.domain.models.acms.crp` | Maps named detail levels to integer depths for a UKO domain |
|
||||
| `AssembledContext` | `cleveragents.domain.models.acms.crp` | Fused, budget-respecting context payload delivered to an actor |
|
||||
| `TieredFragment` | `cleveragents.domain.models.acms.context_tiers` | Extends `ContextFragment` with tier placement and access tracking metadata |
|
||||
| `TierBudget` | `cleveragents.domain.models.acms.context_tiers` | Controls capacity per tier |
|
||||
| `ActorContextView` | `cleveragents.domain.models.acms.context_tiers` | Per-actor filtered view configuration with role-based default tiers |
|
||||
| `TierMetrics` | `cleveragents.domain.models.acms.context_tiers` | Hit/miss counters and population counts per tier |
|
||||
| `FileRecord` | `cleveragents.domain.models.acms.context_indexing` | Per-file metadata stored during indexing |
|
||||
| `IndexMetadata` | `cleveragents.domain.models.acms.context_indexing` | Summary record for a repository index |
|
||||
| `RepoIndex` | `cleveragents.domain.models.acms.context_indexing` | Composite object returned by index and refresh operations |
|
||||
|
||||
#### Application Layer
|
||||
|
||||
Application services orchestrate domain models and delegate to infrastructure adapters.
|
||||
They are registered as singletons in the DI container.
|
||||
|
||||
| Class | Module | Description |
|
||||
|-------|--------|-------------|
|
||||
| `ACMSPipeline` | `cleveragents.application.services.acms_service` | Orchestrates the 10-component context assembly pipeline |
|
||||
| `ContextTierService` | `cleveragents.application.services.context_tiers` | Manages fragment lifecycle across hot/warm/cold tiers with LRU eviction |
|
||||
| `RepoIndexingService` | `cleveragents.application.services.context_indexing` | Scans repository resources and builds persistent file-level indexes |
|
||||
| `ContextBudgetEnforcer` | `cleveragents.application.services.acms_service` | Enforces `max_file_size` and `max_total_size` constraints on assembled context |
|
||||
| `ContextStrategyRegistry` | `cleveragents.application.services.context_strategies` | Manages pluggable retrieval strategies; validates capabilities and handles fallback degradation |
|
||||
| `UKOLoader` | `cleveragents.application.services.uko_loader` | Parses `docs/ontology/uko.ttl` into an in-memory ontology graph; resolves inheritance chains |
|
||||
|
||||
#### Infrastructure Layer
|
||||
|
||||
Infrastructure adapters implement persistence and external integrations.
|
||||
|
||||
| Class | Module | Description |
|
||||
|-------|--------|-------------|
|
||||
| `UKOStore` | `cleveragents.infrastructure.acms.uko_store` | RDF storage adapter for UKO ontology nodes; supports query and index operations |
|
||||
| `ContextTierManager` | `cleveragents.infrastructure.acms.context_tier_manager` | Manages hot (in-memory), warm (SQLite), and cold (file) storage backends |
|
||||
| `ContextPersistenceAdapter` | `cleveragents.infrastructure.acms.context_persistence` | SQLAlchemy-backed persistence for `repo_indexes` and `indexed_files` tables |
|
||||
| `TextBackend` | `cleveragents.infrastructure.acms.backends` | Full-text search via Tantivy or SQLite FTS5 |
|
||||
| `VectorBackend` | `cleveragents.infrastructure.acms.backends` | Vector similarity search via FAISS or Qdrant |
|
||||
| `GraphBackend` | `cleveragents.infrastructure.acms.backends` | Graph traversal over UKO structural relationships |
|
||||
| `TemporalBackend` | `cleveragents.infrastructure.acms.backends` | Temporal/cold-tier data access for historical context |
|
||||
|
||||
#### Presentation Layer
|
||||
|
||||
CLI commands expose ACMS functionality to users.
|
||||
|
||||
| Class | Module | Description |
|
||||
|-------|--------|-------------|
|
||||
| `ContextCLI` | `cleveragents.presentation.cli.context` | `agents context list/add/show/clear` commands |
|
||||
| `ProjectContextCLI` | `cleveragents.presentation.cli.project_context` | `agents project context set/show/inspect/simulate` commands |
|
||||
|
||||
---
|
||||
|
||||
### Data Models
|
||||
|
||||
#### ContextFragment
|
||||
|
||||
The atomic unit of context returned by strategies and consumed by the assembly pipeline.
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `fragment_id` | `str` | auto ULID | Stable unique identifier |
|
||||
| `uko_node` | `str` | required | UKO URI of the source node |
|
||||
| `content` | `str` | required | Rendered text content (max 1,000,000 chars) |
|
||||
| `detail_depth` | `int` | `0` | Resolved depth: 0 (MODULE_LISTING) through 9 (FULL_SOURCE) |
|
||||
| `token_count` | `int` | required | Actual token count of content (>= 0) |
|
||||
| `relevance_score` | `float` | `0.5` | Score from 0.0 to 1.0 |
|
||||
| `provenance` | `FragmentProvenance` | required | Provenance trace |
|
||||
| `tier` | `str` | `"warm"` | Priority tier: `"hot"`, `"warm"`, `"cold"` |
|
||||
| `metadata` | `dict[str, str]` | `{}` | Arbitrary key-value metadata (max 64 entries) |
|
||||
| `created_at` | `datetime` | auto UTC | Creation timestamp |
|
||||
|
||||
#### ContextBudget
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `max_tokens` | `int` | `4096` | Maximum total tokens (>= 1) |
|
||||
| `reserved_tokens` | `int` | `512` | Tokens reserved for system prompt (>= 0, < `max_tokens`) |
|
||||
| `available_tokens` | `int` | computed | `max_tokens - reserved_tokens` |
|
||||
|
||||
#### ProjectContextPolicy
|
||||
|
||||
Controls what context is available during each ACMS phase via view inheritance:
|
||||
|
||||
```
|
||||
default -> strategize -> execute -> apply
|
||||
```
|
||||
|
||||
Each phase resolves to the first explicitly-set `ContextView` walking up the chain.
|
||||
|
||||
**ContextView fields:**
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `include_resources` | `list[str]` | `[]` | Resource names/patterns to include (empty = all) |
|
||||
| `exclude_resources` | `list[str]` | `[]` | Resource names/patterns to exclude |
|
||||
| `include_paths` | `list[str]` | `[]` | File path globs to include (empty = all) |
|
||||
| `exclude_paths` | `list[str]` | `[]` | File path globs to exclude |
|
||||
| `max_file_size` | `int \| None` | `None` | Max file size in bytes (None = no limit) |
|
||||
| `max_total_size` | `int \| None` | `None` | Max total context size in bytes (None = no limit) |
|
||||
|
||||
Exclusions always take precedence over inclusions.
|
||||
|
||||
#### AssembledContext / ContextPayload
|
||||
|
||||
The fused, budget-respecting context payload delivered to an actor.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `payload_id` | `str` | ULID identifier |
|
||||
| `plan_id` | `str` | Plan this payload was assembled for |
|
||||
| `fragments` | `tuple[ContextFragment, ...]` | Ordered context fragments |
|
||||
| `total_tokens` | `int` | Sum of fragment `token_count` values |
|
||||
| `budget` | `ContextBudget` | Budget used for assembly |
|
||||
| `budget_used` | `float` | Fraction of budget consumed (0.0-1.0) |
|
||||
| `strategies_used` | `tuple[str, ...]` | Strategy names that contributed |
|
||||
| `context_hash` | `str` | SHA-256 hash of assembled content |
|
||||
| `preamble` | `str \| None` | Optional structure summary (max 200 tokens) |
|
||||
| `provenance_map` | `dict[str, Any]` | Fragment ID -> provenance mapping |
|
||||
| `assembled_at` | `datetime` | UTC timestamp |
|
||||
|
||||
**Properties:**
|
||||
|
||||
- `is_within_budget` — `True` if total tokens do not exceed available budget.
|
||||
- `remaining_tokens` — Tokens still available in the budget.
|
||||
|
||||
#### IndexMetadata
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `index_id` | `str` | ULID identifier for this index snapshot |
|
||||
| `resource_id` | `str` | ULID of the linked resource |
|
||||
| `indexed_at` | `datetime` | When indexing completed (UTC) |
|
||||
| `file_count` | `int` | Total files in the index |
|
||||
| `token_estimate` | `int` | Sum of all file token counts |
|
||||
| `primary_language` | `str` | Most common language by token count |
|
||||
| `status` | `IndexStatus` | `pending`, `indexing`, `ready`, `stale`, `error` |
|
||||
| `error_message` | `str \| None` | Error details when `status == error` |
|
||||
|
||||
---
|
||||
|
||||
### Key Interfaces
|
||||
|
||||
#### ContextAssemblyService (ACMSPipeline)
|
||||
|
||||
```python
|
||||
class ACMSPipeline:
|
||||
def assemble(
|
||||
self,
|
||||
plan_id: str,
|
||||
fragments: Sequence[ContextFragment],
|
||||
budget: ContextBudget,
|
||||
strategy: str = "relevance",
|
||||
) -> ContextPayload: ...
|
||||
|
||||
def register_strategy(self, name: str, strategy: ContextStrategy) -> None: ...
|
||||
```
|
||||
|
||||
The pipeline applies a named strategy to rank and filter fragments, then runs all 10
|
||||
pipeline components to produce the final `ContextPayload`.
|
||||
|
||||
#### ContextBudgetEnforcer
|
||||
|
||||
```python
|
||||
class ContextBudgetEnforcer:
|
||||
def enforce(
|
||||
self,
|
||||
view: ContextView,
|
||||
policy: ContextPolicy,
|
||||
) -> ContextView: ...
|
||||
```
|
||||
|
||||
Applies `max_file_size` and `max_total_size` constraints from the policy to the assembled
|
||||
view, excluding or summarising fragments that exceed limits.
|
||||
|
||||
#### UKOStore
|
||||
|
||||
```python
|
||||
class UKOStore:
|
||||
def query(
|
||||
self,
|
||||
ontology: UKOOntology,
|
||||
query: str,
|
||||
) -> list[ContextFragment]: ...
|
||||
|
||||
def index(
|
||||
self,
|
||||
project: Project,
|
||||
) -> UKOOntology: ...
|
||||
```
|
||||
|
||||
RDF storage adapter for UKO ontology nodes. Supports SPARQL-like queries and full project
|
||||
indexing.
|
||||
|
||||
#### ContextTierService
|
||||
|
||||
```python
|
||||
class ContextTierService:
|
||||
def store(self, fragment: TieredFragment) -> None: ...
|
||||
def get(self, fragment_id: str) -> TieredFragment | None: ...
|
||||
def promote(self, fragment_id: str) -> None: ... # cold->warm or warm->hot
|
||||
def demote(self, fragment_id: str) -> None: ... # hot->warm or warm->cold
|
||||
def evict_lru(self, tier: ContextTier, count: int) -> int: ...
|
||||
def get_for_actor(
|
||||
self,
|
||||
role: ActorRole,
|
||||
project_names: list[str],
|
||||
) -> list[TieredFragment]: ...
|
||||
def get_scoped_view(self, project_names: list[str]) -> ScopedBackendView: ...
|
||||
def get_metrics(self) -> TierMetrics: ...
|
||||
```
|
||||
|
||||
#### RepoIndexingService
|
||||
|
||||
```python
|
||||
class RepoIndexingService:
|
||||
def index_resource(
|
||||
self,
|
||||
resource_id: str,
|
||||
root_path: str | Path,
|
||||
*,
|
||||
include_globs: tuple[str, ...] = (),
|
||||
exclude_globs: tuple[str, ...] = (),
|
||||
max_file_size: int | None = None,
|
||||
max_total_size: int | None = None,
|
||||
) -> RepoIndex: ...
|
||||
|
||||
def refresh_index(self, resource_id: str, root_path: str | Path, **kwargs) -> RepoIndex: ...
|
||||
def get_index(self, resource_id: str) -> RepoIndex | None: ...
|
||||
def get_index_status(self, resource_id: str) -> IndexMetadata | None: ...
|
||||
def remove_index(self, resource_id: str) -> bool: ...
|
||||
def cleanup_stale_indexing(self) -> int: ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10-Component Pipeline Architecture
|
||||
|
||||
The ACMS pipeline runs three phases, each containing specific components. All 10 components
|
||||
have explicit Protocol definitions and injectable Default implementations.
|
||||
|
||||
**Phase 1 — Strategy Orchestration:**
|
||||
|
||||
| # | Component | Responsibility |
|
||||
|---|-----------|---------------|
|
||||
| 1 | `StrategySelector` | Decides which strategies to invoke and with what confidence. Polls `can_handle()` on each registered strategy. |
|
||||
| 2 | `BudgetAllocator` | Distributes the token budget across selected strategies proportionally. |
|
||||
| 3 | `StrategyExecutor` | Runs strategies in parallel with timeouts (default: 30s), circuit breakers (threshold: 3 failures), and configurable max workers (default: 4). |
|
||||
|
||||
**Phase 2 — Fragment Fusion:**
|
||||
|
||||
| # | Component | Responsibility |
|
||||
|---|-----------|---------------|
|
||||
| 4 | `FragmentDeduplicator` | Removes duplicate fragments via content-hash, UKO-identity, or semantic similarity. |
|
||||
| 5 | `DetailDepthResolver` | Resolves conflicts when the same UKO node appears at different detail depths (keeps the most appropriate depth for the budget). |
|
||||
| 6 | `FragmentScorer` | Computes composite relevance scores using weighted factors: relevance (0.4), hierarchy position (0.3), strategy quality (0.2), recency (0.1). |
|
||||
| 7 | `BudgetPacker` | Fits scored fragments into the token budget using a greedy knapsack algorithm with depth fallback (steps: `[9, 4, 2, 0]`). Minimum fragment size: 10 tokens. |
|
||||
| 8 | `FragmentOrderer` | Orders packed fragments for optimal coherence in the context window. |
|
||||
|
||||
**Phase 3 — Context Finalization:**
|
||||
|
||||
| # | Component | Responsibility |
|
||||
|---|-----------|---------------|
|
||||
| 9 | `PreambleGenerator` | Generates provenance summaries prepended to assembled context (max tokens: 200). |
|
||||
| 10 | `SkeletonCompressor` | Compresses parent plan context into skeleton form for child plan inheritance (budget ratio: `context.budget.skeleton-ratio`, default: 0.15). |
|
||||
|
||||
Each component is pluggable via `context.pipeline.*` configuration keys specifying
|
||||
`"module:ClassName"`. All 10 components must execute for every context assembly; components
|
||||
may produce empty output but must not be skipped.
|
||||
|
||||
**v1 defaults:** Phase 1 uses single-strategy selection, full-budget allocation, and
|
||||
synchronous execution. Phase 2 components are pass-through stubs. Phase 3 components are
|
||||
no-op (no preamble, identity compression). Production implementations are planned for future
|
||||
milestones.
|
||||
|
||||
---
|
||||
|
||||
### Context Strategies
|
||||
|
||||
Strategies implement the `ContextStrategy` protocol and are registered in the
|
||||
`ContextStrategyRegistry`.
|
||||
|
||||
**Built-in strategies:**
|
||||
|
||||
| Strategy | Quality | Backends | Description |
|
||||
|----------|---------|----------|-------------|
|
||||
| `simple-keyword` | 0.3 | Text | Full-text search via Tantivy or SQLite FTS5 |
|
||||
| `semantic-embedding` | 0.6 | Vector | Vector similarity search via FAISS or Qdrant |
|
||||
| `breadth-depth-navigator` | 0.85 | Graph | Graph traversal from focus nodes, expanding by `request.breadth` hops |
|
||||
| `arce` | 0.95 | All | Multi-modal: text (40%) + vector (40%) + graph (20%); results merged and deduplicated |
|
||||
| `temporal-archaeology` | 0.5 | Graph + Cold | Two-phase: cold-tier historical nodes + graph traversal |
|
||||
| `plan-decision-context` | 0.7 | Warm/Cold | Walks parent/ancestor plan hierarchy, retrieving decision records |
|
||||
|
||||
Default enabled: `["simple-keyword", "semantic-embedding", "breadth-depth-navigator"]`
|
||||
|
||||
**Fallback degradation path** (when backends are unavailable):
|
||||
|
||||
```
|
||||
arce -> breadth-depth-navigator -> semantic-embedding -> simple-keyword
|
||||
```
|
||||
|
||||
**StrategyCapabilities fields:**
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `uses_text` | `bool` | `False` | Requires TextBackend |
|
||||
| `uses_vector` | `bool` | `False` | Requires VectorBackend |
|
||||
| `uses_graph` | `bool` | `False` | Requires GraphBackend |
|
||||
| `uses_temporal` | `bool` | `False` | Requires temporal/cold-tier data |
|
||||
| `quality_score` | `float` | `0.5` | Intrinsic quality score (0.0-1.0) |
|
||||
| `supports_depth_breadth` | `bool` | `False` | Supports depth/breadth projection |
|
||||
| `supports_plan_hierarchy` | `bool` | `False` | Supports plan hierarchy traversal |
|
||||
|
||||
---
|
||||
|
||||
### CLI Commands
|
||||
|
||||
#### `agents context` — Context Entry Management
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `agents context list` | List context entries for the current project |
|
||||
| `agents context add` | Add a context entry |
|
||||
| `agents context show <id>` | Show details of a specific context entry |
|
||||
| `agents context clear` | Clear all context entries for the current project |
|
||||
|
||||
#### `agents project context` — Project Context Policy and ACMS Management
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `agents project context set PROJECT [OPTIONS]` | Persist a context policy view and ACMS pipeline configuration for a project |
|
||||
| `agents project context show PROJECT [OPTIONS]` | Display the context policy and ACMS pipeline configuration |
|
||||
| `agents project context inspect PROJECT [OPTIONS]` | Inspect the effective context state (tier metrics, fragment distribution, actor visibility) |
|
||||
| `agents project context simulate PROJECT [OPTIONS]` | Run a dry-run context window assembly |
|
||||
|
||||
**`agents project context set` key options:**
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `--view` | `default` | Phase view: default, strategize, execute, apply |
|
||||
| `--include-resource` | — | Resource pattern to include (repeatable) |
|
||||
| `--exclude-resource` | — | Resource pattern to exclude (repeatable) |
|
||||
| `--include-path` | — | File path glob to include (repeatable) |
|
||||
| `--exclude-path` | — | File path glob to exclude (repeatable) |
|
||||
| `--max-file-size` | `None` | Max file size in bytes |
|
||||
| `--max-total-size` | `None` | Max total context size in bytes |
|
||||
| `--hot-max-tokens` | `8000` | Max tokens for the hot tier context window |
|
||||
| `--warm-max-decisions` | `500` | Max decisions for the warm tier |
|
||||
| `--cold-max-decisions` | `5000` | Max decisions for the cold tier |
|
||||
| `--strategy` | — | Preferred context strategy (repeatable) |
|
||||
| `--default-breadth` | `2` | Default breadth for context retrieval |
|
||||
| `--default-depth` | `3` | Default depth (integer or named level) |
|
||||
| `--skeleton-ratio` | `0.2` | Skeleton compression ratio (0.0-1.0) |
|
||||
| `--temporal-scope` | `current` | Temporal scope: current, recent, or all |
|
||||
| `--auto-refresh/--no-auto-refresh` | `True` | Auto-refresh context on resource changes |
|
||||
|
||||
---
|
||||
|
||||
### Integration Points
|
||||
|
||||
#### Plan Lifecycle Integration
|
||||
|
||||
Context assembly is triggered at each plan phase transition (see ADR-006). The ACMS pipeline
|
||||
runs before the actor's LLM call for each phase:
|
||||
|
||||
1. `strategize` — full context assembly with `breadth-depth-navigator` + `semantic-embedding`.
|
||||
2. `execute` — focused context assembly scoped to the current task.
|
||||
3. `apply` — minimal context assembly; primarily hot-tier fragments.
|
||||
|
||||
Child plans inherit a compressed skeleton of their parent's context via `SkeletonCompressor`.
|
||||
|
||||
#### Resource System Integration
|
||||
|
||||
When a resource is linked to a project via `agents project link-resource`, the
|
||||
`RepoIndexingService` is triggered to index the resource's filesystem tree. The index is
|
||||
stored in SQLite and refreshed incrementally on file changes (see ADR-008).
|
||||
|
||||
#### Actor and Agent Integration
|
||||
|
||||
Actors consume assembled context via the `builtin/context` skill, which provides three tools:
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `request_context` | Request specific context during reasoning |
|
||||
| `query_history` | Query historical context about past decisions |
|
||||
| `get_context_budget` | Check remaining context token budget |
|
||||
|
||||
#### Configuration System Integration
|
||||
|
||||
ACMS behaviour is controlled via `config.toml` under the `[context]` namespace (see ADR-024).
|
||||
|
||||
**Key configuration keys:**
|
||||
|
||||
| Key | Default | Description |
|
||||
|-----|---------|-------------|
|
||||
| `context.hot.max-tokens` | `16000` | Hot tier token budget |
|
||||
| `context.warm.max-decisions` | `100` | Warm tier max decisions |
|
||||
| `context.warm.retention-hours` | `24` | Warm tier retention period |
|
||||
| `context.cold.max-decisions` | `500` | Cold tier max decisions |
|
||||
| `context.cold.retention-days` | `90` | Cold tier retention period |
|
||||
| `context.strategies.enabled` | `["simple-keyword", "semantic-embedding", "breadth-depth-navigator"]` | Enabled strategies |
|
||||
| `context.strategies.arce.max-rounds` | `3` | ARCE max refinement rounds |
|
||||
| `context.strategies.breadth-depth-navigator.max-hops` | `4` | Max graph traversal hops |
|
||||
| `context.query.min-relevance` | `0.3` | Minimum relevance score threshold |
|
||||
| `context.file.max-size` | `1048576` | Max file size in bytes (1 MB) |
|
||||
| `context.file.max-total-size` | `52428800` | Max total file size (50 MB) |
|
||||
| `context.budget.refresh-threshold` | `0.30` | Budget change threshold for refresh |
|
||||
| `context.budget.min-useful-budget` | `500` | Minimum useful budget (tokens) |
|
||||
| `context.budget.skeleton-ratio` | `0.15` | Skeleton compression ratio |
|
||||
| `context.pipeline.*` | — | Pluggable pipeline component overrides (`"module:ClassName"`) |
|
||||
|
||||
#### DI Container Integration
|
||||
|
||||
All ACMS services are registered as singletons in the DI container:
|
||||
|
||||
```python
|
||||
from cleveragents.application.container import get_container
|
||||
|
||||
container = get_container()
|
||||
acms_pipeline = container.acms_pipeline()
|
||||
tier_service = container.context_tier_service()
|
||||
indexing_service = container.repo_indexing_service()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Database Schema
|
||||
|
||||
ACMS v1 adds two tables to the SQLite database:
|
||||
|
||||
#### `repo_indexes`
|
||||
|
||||
| Column | Type | Constraints |
|
||||
|--------|------|-------------|
|
||||
| `index_id` | `String(26)` | PK |
|
||||
| `resource_id` | `String(26)` | NOT NULL, UNIQUE, INDEXED |
|
||||
| `indexed_at` | `String(40)` | NOT NULL (ISO-8601 UTC) |
|
||||
| `file_count` | `Integer` | NOT NULL, DEFAULT 0 |
|
||||
| `token_estimate` | `Integer` | NOT NULL, DEFAULT 0 |
|
||||
| `primary_language` | `String(50)` | NOT NULL, DEFAULT "unknown" |
|
||||
| `status` | `String(20)` | NOT NULL, CHECK IN (`pending`, `indexing`, `ready`, `stale`, `error`) |
|
||||
| `error_message` | `Text` | NULLABLE |
|
||||
| `created_at` | `String(40)` | NOT NULL (ISO-8601 UTC) |
|
||||
|
||||
#### `indexed_files`
|
||||
|
||||
| Column | Type | Constraints |
|
||||
|--------|------|-------------|
|
||||
| `index_id` | `String(26)` | PK (composite), FK -> `repo_indexes.index_id` ON DELETE CASCADE |
|
||||
| `path` | `String(1024)` | PK (composite) |
|
||||
| `content_hash` | `String(64)` | NOT NULL |
|
||||
| `token_count` | `Integer` | NOT NULL, DEFAULT 0 |
|
||||
| `size_bytes` | `Integer` | NOT NULL, DEFAULT 0 |
|
||||
| `language` | `String(50)` | NOT NULL, DEFAULT "unknown" |
|
||||
| `last_modified` | `String(40)` | NOT NULL |
|
||||
|
||||
---
|
||||
|
||||
### v1 Known Limitations
|
||||
|
||||
The following are accepted deviations from the full specification in v1, with a planned path
|
||||
to spec conformance in future milestones:
|
||||
|
||||
| Area | v1 Behaviour | Spec Target | Planned |
|
||||
|------|-------------|-------------|---------|
|
||||
| Pipeline components | All 10 Protocol + Default classes defined; defaults are pass-through stubs | Production implementations (parallel execution, dedup, scoring, compression) | Future milestone |
|
||||
| `ContextStrategy` signatures | `can_handle(request: dict)`, `assemble(fragments, budget)` | `can_handle(request: ContextRequest, backends: BackendSet)`, `assemble(request, backends, budget, plan_context)` | M6 strategy registry |
|
||||
| `StrategyCapabilities` fields | `supports_semantic_search`, `supports_graph_navigation`, `max_fragments` | `uses_text`, `uses_vector`, `uses_graph`, `uses_temporal`, `quality_score` | M6 strategy registry |
|
||||
| Tiers | Sort-priority labels for ranking | Storage tiers with retention policies, promotion/demotion | `ContextTierService` future milestone |
|
||||
| `SemanticEmbeddingStrategy` | Character-frequency embedding approximation | Real embedding model integration | Future milestone |
|
||||
| `DetailDepthResolver.resolve()` | Missing `budget` parameter | `resolve(fragments, budget)` | Future milestone |
|
||||
| `FragmentScorer.score()` | Missing `plan_context` param; returns `Sequence[ContextFragment]` | Returns `list[ScoredFragment]` with `plan_context` | Future milestone |
|
||||
| `PreambleGenerator.generate()` | Missing `strategies_used`, `budget_used`, `max_tokens` params | Full parameter set per spec | Future milestone |
|
||||
| `provenance_map` keying | Keyed by `fragment_id` (ULID) | Spec keys by `uko_node` (UKO URI) | Under review |
|
||||
|
||||
---
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
The following criteria must be satisfied for ACMS v1 to be considered complete for milestone
|
||||
v3.4.0:
|
||||
|
||||
**Indexing:**
|
||||
|
||||
- `RepoIndexingService.index_resource()` successfully indexes a repository with 10,000+
|
||||
files without timeout (target: < 60 seconds on standard hardware).
|
||||
- Incremental `refresh_index()` only re-processes changed files (verified by content hash
|
||||
comparison).
|
||||
- Language detection correctly identifies all supported languages.
|
||||
- Index status transitions correctly through `pending -> indexing -> ready`.
|
||||
- `cleanup_stale_indexing()` removes orphan `INDEXING` rows on startup.
|
||||
|
||||
**Assembly:**
|
||||
|
||||
- `ACMSPipeline.assemble()` produces a `ContextPayload` that never exceeds the declared
|
||||
token budget (`is_within_budget == True`).
|
||||
- All three built-in strategies (`relevance`, `recency`, `tiered`) produce correctly
|
||||
ordered fragment sequences.
|
||||
- The pipeline runs all 10 components for every assembly call.
|
||||
- Depth fallback correctly downgrades fragments to shallower depths when budget is tight.
|
||||
- `ContextBudgetEnforcer` correctly applies `max_file_size` and `max_total_size` limits.
|
||||
|
||||
**Tiers:**
|
||||
|
||||
- `ContextTierService.store()` correctly places fragments in the specified tier.
|
||||
- `promote()` and `demote()` correctly move fragments between tiers.
|
||||
- `evict_lru()` removes the correct number of least-recently-used fragments.
|
||||
- Actor role visibility is correctly enforced (reviewer sees hot only; executor sees hot +
|
||||
warm; strategist sees all).
|
||||
- Project scoping correctly isolates fragments by `project_name`.
|
||||
|
||||
**Policy:**
|
||||
|
||||
- `ProjectContextPolicy.resolve_view()` correctly walks the inheritance chain.
|
||||
- Empty policy correctly includes all resources and paths.
|
||||
- Exclusions take precedence over inclusions.
|
||||
- `max_file_size` and `max_total_size` validation rejects zero or negative values.
|
||||
|
||||
**CLI:**
|
||||
|
||||
- `agents context list/add/show/clear` commands function correctly.
|
||||
- `agents project context set` persists policy views and ACMS pipeline configuration.
|
||||
- `agents project context show` displays resolved views and ACMS config.
|
||||
- `agents project context inspect` displays tier metrics, fragment distribution, and actor
|
||||
visibility.
|
||||
- `agents project context simulate` produces a dry-run `AssembledContext` using the
|
||||
project's ACMS configuration.
|
||||
|
||||
**UKO:**
|
||||
|
||||
- `UKOLoader` correctly parses `docs/ontology/uko.ttl` and resolves inheritance chains
|
||||
(including multi-parent `rdfs:subClassOf`).
|
||||
- All four layers (0-3) are correctly identified by prefix.
|
||||
- `resolve_inheritance()` returns the correct BFS-ordered chain for `uko-oo:Class`.
|
||||
|
||||
**Testing:**
|
||||
|
||||
- Budget constraint tests verify assembled context never exceeds declared token budget.
|
||||
- Each of the 10 pipeline components has unit tests for edge cases (empty input, budget
|
||||
exhaustion, duplicate fragments).
|
||||
- Each retrieval strategy has integration tests verifying correctly structured results.
|
||||
- Depth fallback tests verify fragments are downgraded to shallower depths when budget is
|
||||
insufficient.
|
||||
- Configuration tests verify custom pipeline components and strategy registrations are
|
||||
loaded and invoked correctly.
|
||||
- Performance benchmark: index 10,000 files in < 60 seconds; assemble context in < 5
|
||||
seconds.
|
||||
|
||||
---
|
||||
|
||||
*Section added by [AUTO-ARCH-20] — Cycle 27 — Milestone v3.4.0 — ACMS v1 + Context Scaling*
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,535 @@
|
||||
## Behavior
|
||||
|
||||
### Automation Profiles
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The automation profile system, confidence thresholds, and built-in profiles are defined in [ADR-017: Automation Profiles](adr/ADR-017-automation-profiles.md).
|
||||
|
||||
Automation profiles determine which phase transitions happen automatically and which require human approval.
|
||||
|
||||
#### Overview
|
||||
|
||||
An **automation profile** is a named collection of **confidence thresholds** — floating-point values from 0.0 to 1.0 inclusive — that controls which tasks are automated vs. require human approval. Each threshold specifies the minimum confidence score (as computed by the Semantic Escalation system) at which the system proceeds automatically. When the computed confidence for a given operation falls below the profile's threshold for that flag, the system drops to manual mode and requests human input. A threshold of **0.0** means "always automatic" (proceed regardless of confidence), while **1.0** means "always manual" (always require human approval). Profiles follow the same `<namespace>/<name>` naming convention as actors, tools, skills, and other entities. Profiles are managed via the `agents automation-profile` CLI commands.
|
||||
|
||||
#### Automatable Tasks
|
||||
|
||||
Each automation profile specifies a **confidence threshold** (a floating-point value from 0.0 to 1.0 inclusive) for each of the following automatable tasks. The threshold determines the minimum confidence level at which the system proceeds automatically. When the computed confidence (from Semantic Escalation) falls below the threshold, the system drops to manual mode for that task. Setting a threshold to **0.0** makes the task always automatic; setting it to **1.0** makes it always manual.
|
||||
|
||||
| Flag | Type | Description | Behavior |
|
||||
|------|------|-------------|----------|
|
||||
| `decompose_task` | float (0.0–1.0) | Automatically enter Strategize after `plan use` | When confidence >= threshold, Strategize begins immediately. Below threshold, system pauses after plan creation for user confirmation before entering Strategize. |
|
||||
| `create_tool` | float (0.0–1.0) | Automatically proceed from Strategize to Execute | When confidence >= threshold, Execute begins when Strategize completes. Below threshold, system pauses for user review. |
|
||||
| `select_tool` | float (0.0–1.0) | Automatically proceed from Execute to Apply | When confidence >= threshold, Apply begins when Execute completes. Below threshold, system pauses for user diff review. |
|
||||
| `edit_code` | float (0.0–1.0) | Automatically make decisions during Strategize | When confidence >= threshold, the strategy actor makes the decision autonomously. Below threshold, system pauses at the decision point for user input. |
|
||||
| `execute_command` | float (0.0–1.0) | Automatically make decisions during Execute | When confidence >= threshold, the execution actor makes the decision autonomously. Below threshold, system pauses at the decision point for user input. |
|
||||
| `create_file` | float (0.0–1.0) | Automatically attempt to fix validation failures | When confidence >= threshold, execution actor self-fixes failing validations. Below threshold, system pauses for user guidance. |
|
||||
| `delete_content` | float (0.0–1.0) | Automatically revise strategy when Execute hits constraints | When confidence >= threshold, system re-runs Strategize for affected subtree. Below threshold, system pauses and asks user. |
|
||||
| `access_network` | float (0.0–1.0) | Automatically revert from Apply (`constrained` state) to Strategize | When confidence >= threshold, a `constrained` Apply automatically triggers reversion to Strategize. Below threshold, system pauses and asks user whether to revert or cancel. |
|
||||
| `install_dependency` | float (0.0–1.0) | Automatically spawn and execute child plans | When confidence >= threshold, child plans are created and executed without pausing. Below threshold, each spawn requires approval. |
|
||||
| `modify_config` | float (0.0–1.0) | Automatically retry on transient failures (network, timeout, rate-limit) | When confidence >= threshold, system retries with backoff. Below threshold, system pauses and asks user. |
|
||||
| `approve_plan` | float (0.0–1.0) | Automatically restore from checkpoint on failure | When confidence >= threshold, system rolls back and retries. Below threshold, user decides whether to restore. |
|
||||
|
||||
#### Safety Profile (Composed Sub-Model)
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The extraction of safety constraints into a composed SafetyProfile sub-model is defined in [ADR-041: Safety Profile Extraction](adr/ADR-041-safety-profile-extraction.md).
|
||||
|
||||
Each automation profile composes a **`safety`** sub-model (`SafetyProfile`) that groups all hard safety constraints. These are binary constraints rather than confidence-dependent behaviors — they enforce invariant safety guarantees regardless of the system's confidence level. The `SafetyProfile` is the **single source of truth** for safety constraints; the `AutomationProfile` accesses them via its `safety` field.
|
||||
|
||||
A `SafetyProfile` may also be attached directly to an `Action` (via the `safety_profile` field) when only safety constraints are needed without full autonomy thresholds.
|
||||
|
||||
| Flag | Type | Default | Description | Behavior |
|
||||
|------|------|---------|-------------|----------|
|
||||
| `require_sandbox` | boolean | `true` | Require sandbox isolation for Execute phase | When `true`, Execute must run in a sandbox. When `false`, sandbox is optional. |
|
||||
| `require_checkpoints` | boolean | `true` | Require checkpointing during Execute | When `true`, tools must create checkpoints before writes. When `false`, checkpointing is optional. |
|
||||
| `allow_unsafe_tools` | boolean | `false` | Allow execution of tools marked as unsafe | When `true`, unsafe tools can be invoked. When `false`, unsafe tools are blocked. |
|
||||
| `require_human_approval` | boolean | `false` | Require human approval before each action step | When `true`, every action step pauses for explicit human approval before execution. |
|
||||
| `allowed_skill_categories` | list[string] | `[]` (all) | Skill categories permitted for execution | When non-empty, only skills in the listed categories may be used. Empty list means all categories are allowed. |
|
||||
| `max_cost_per_plan` | float \| null | `null` | Maximum cost in USD per plan execution | When set, the plan is paused or terminated if the cost limit is reached. `null` means no limit. Must be <= `max_total_cost` when both are set. |
|
||||
| `max_total_cost` | float \| null | `null` | Maximum total cost in USD across all plans | When set, execution is paused or terminated if the aggregate cost limit is reached. `null` means no limit. |
|
||||
| `max_retries_per_step` | integer | `3` | Maximum retry attempts per action step | Limits the number of retries for a single step before escalating to the user. Range: 0–100. |
|
||||
|
||||
**Relationship to Automation Guards**: The `SafetyProfile.max_total_cost` field sets a **plan-level** budget cap (broad scope), while `AutomationGuard.max_total_cost` sets a **per-invocation** budget cap (narrow scope). These operate at different granularities and both may be active simultaneously — the tighter constraint takes precedence at any given point.
|
||||
|
||||
#### Automation Guard Sub-Model
|
||||
|
||||
An `AutomationProfile` may optionally compose an `AutomationGuard` sub-model (via the `guards` field) that provides runtime enforcement hooks beyond the phase-transition thresholds. Guards gate individual tool invocations based on call counts, budgets, allowlists/denylists, and write/apply semantics.
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `max_tool_calls_per_step` | integer \| null | `null` | Maximum tool invocations per step before requiring approval. `null` means unlimited. Must be >= 0. |
|
||||
| `max_total_cost` | float \| null | `null` | Per-invocation budget cap (cumulative cost) before requiring approval. `null` means unlimited. Must be >= 0.0. |
|
||||
| `tool_allowlist` | list[string] \| null | `null` | Only these tools may be called automatically. `null` means all tools are allowed. |
|
||||
| `tool_denylist` | list[string] \| null | `null` | These tools always require human approval. `null` means no tools are denied. |
|
||||
| `require_approval_for_writes` | boolean | `false` | Require human approval for write operations. |
|
||||
| `require_approval_for_apply` | boolean | `false` | Require human approval before the apply phase. |
|
||||
|
||||
Guard evaluation is performed via `AutomationProfile.check_guard(tool_name, is_write, cost_so_far, calls_so_far, scope)`. The `scope` parameter is a `GuardScope` enum (`PLAN` or `SUBPLAN`) that distinguishes plan-level from subplan-level enforcement — error messages include the scope name for clarity. The method returns a `GuardResult` with fields `allowed` (bool), `reason` (str | None), and `requires_approval` (bool). Evaluation order: denylist → allowlist → tool call limit → budget cap → write approval → apply approval.
|
||||
|
||||
#### Built-in Automation Profiles
|
||||
|
||||
CleverAgents ships with eight built-in automation profiles. Built-in profiles use no namespace prefix.
|
||||
|
||||
Threshold values are shown for each flag. A value of **0.0** means always automatic, **1.0** means always manual, and intermediate values (e.g., 0.5, 0.7) mean "automatic when confidence is at or above that level."
|
||||
|
||||
| Flag | `manual` | `review` | `supervised` | `cautious` | `trusted` | `auto` | `ci` | `full-auto` |
|
||||
|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
|
||||
| `decompose_task` | 1.0 | 0.0 | 0.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
|
||||
| `create_tool` | 1.0 | 0.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
|
||||
| `select_tool` | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 0.0 | 0.0 |
|
||||
| `edit_code` | 1.0 | 1.0 | 0.0 | 0.6 | 0.0 | 0.0 | 0.0 | 0.0 |
|
||||
| `execute_command` | 1.0 | 1.0 | 1.0 | 0.8 | 0.0 | 0.0 | 0.0 | 0.0 |
|
||||
| `create_file` | 1.0 | 1.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
|
||||
| `delete_content` | 1.0 | 1.0 | 1.0 | 0.8 | 1.0 | 0.0 | 0.0 | 0.0 |
|
||||
| `access_network` | 1.0 | 1.0 | 1.0 | 0.9 | 1.0 | 1.0 | 0.0 | 0.0 |
|
||||
| `install_dependency` | 1.0 | 0.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
|
||||
| `modify_config` | 1.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 |
|
||||
| `approve_plan` | 1.0 | 1.0 | 1.0 | 0.6 | 1.0 | 0.0 | 0.0 | 0.0 |
|
||||
| **Safety Profile** | | | | | | | | |
|
||||
| `safety.require_sandbox` | true | true | true | true | true | true | true | false |
|
||||
| `safety.require_checkpoints` | true | true | true | true | true | true | true | false |
|
||||
| `safety.allow_unsafe_tools` | false | false | false | false | false | false | false | true |
|
||||
| `safety.require_human_approval` | false | false | false | false | false | false | false | false |
|
||||
| `safety.allowed_skill_categories` | [] | [] | [] | [] | [] | [] | [] | [] |
|
||||
| `safety.max_cost_per_plan` | null | null | null | null | null | null | null | null |
|
||||
| `safety.max_total_cost` | null | null | null | null | null | null | null | null |
|
||||
| `safety.max_retries_per_step` | 3 | 3 | 3 | 3 | 3 | 3 | 3 | 3 |
|
||||
|
||||
**`manual`**: Maximum human control. All thresholds set to 1.0 — every phase transition, every decision, every child plan requires explicit human approval regardless of confidence. Sandbox and checkpoints are mandatory. Unsafe tools are blocked. This is the default starting point. Use for: new users learning the system, critical production systems, first-time exploration of an unfamiliar codebase, sensitive projects, regulatory environments.
|
||||
|
||||
**`review`**: Phases run automatically (Strategize and Execute proceed without pausing), and most decisions within those phases require human approval (thresholds set to 1.0), except transient retries and child plan spawning which are automatic (thresholds 0.0). Apply is manual. The system does the work but consults you on every choice point. Use for: teams that want to stay in the decision loop without manually triggering each phase, code reviews where architectural choices matter more than execution mechanics.
|
||||
|
||||
**`supervised`**: Strategize thresholds set to 0.0 (always automatic), but Execute and Apply thresholds set to 1.0 (always manual). The system plans autonomously and retries transient failures automatically, but pauses before Execute for human review of the strategy. Use for: projects where you trust the planning but want to review before execution begins.
|
||||
|
||||
**`cautious`**: Uses intermediate confidence thresholds (0.6–0.8) instead of binary 0.0/1.0 values. The system proceeds automatically only when the Semantic Escalation system reports high confidence, and escalates to the user when uncertain. Apply is always manual (1.0). Higher thresholds (0.8) are applied to riskier operations like strategy revision and execution decisions, while lower thresholds (0.6) are used for safer operations like checkpoint restores and strategy decisions. Transient retries are always automatic. Use for: teams adopting automation gradually, projects with mixed complexity where some tasks are routine but others need oversight, situations where you want the system to self-assess rather than follow rigid rules.
|
||||
|
||||
**`trusted`**: Strategize and Execute thresholds set to 0.0 (always automatic). Validation fixes, child plan spawning, and transient retries proceed automatically. Strategy revision and checkpoint restores remain manual (thresholds 1.0) to preserve human oversight over plan-level course corrections. The system pauses only before Apply (threshold 1.0) for human review of the final diffs. Use for: day-to-day feature development, routine refactoring, test generation.
|
||||
|
||||
**`auto`**: All thresholds set to 0.0 except Apply (1.0). The system can revise its own strategy, restore from checkpoints, and handle all decisions automatically. Only Apply requires human approval. Use for: well-understood projects, batch operations, tasks with strong invariant coverage.
|
||||
|
||||
**`ci`**: All thresholds set to 0.0 — complete end-to-end automation including Apply — but sandbox and checkpoints remain mandatory and unsafe tools are blocked. Designed for non-interactive environments where full automation is needed but safety nets must be preserved. Use for: CI/CD pipelines, automated testing workflows, scheduled batch jobs, any headless execution where rollback capability is essential.
|
||||
|
||||
**`full-auto`**: All thresholds set to 0.0 — complete end-to-end automation including Apply. No sandbox or checkpoint requirements. Unsafe tools are allowed. Use for: low-risk routine tasks (dependency updates, documentation generation, formatting), trusted batch operations with rollback capabilities, environments where external safety mechanisms exist.
|
||||
|
||||
#### Profile Precedence
|
||||
|
||||
Automation profiles are determined using this precedence (highest to lowest):
|
||||
|
||||
1. **Plan-level**: Explicitly set via `--automation-profile` on `agents plan use`
|
||||
2. **Action-level**: Set on the action via `--automation-profile` on `agents action create`
|
||||
3. **Project-level**: Set via `agents config set core.automation-profile <PROFILE> --project <PROJECT>`
|
||||
4. **Global-level**: Set via `agents config set core.automation-profile <PROFILE>`
|
||||
|
||||
The **effective profile** for a plan is resolved at the moment of `agents plan use`. Once resolved, the profile is **locked to that plan** — subsequent changes to project or global profiles do not affect running plans.
|
||||
|
||||
#### Child Plan Profile Inheritance
|
||||
|
||||
Child plans inherit the parent plan's effective automation profile. If the parent's profile is changed explicitly after creation, new child plans use the new profile while already-running child plans retain their original profile.
|
||||
|
||||
#### Custom Automation Profiles
|
||||
|
||||
Custom profiles are created via YAML configuration files and registered with `agents automation-profile add`. Each automatable task flag takes a confidence threshold (0.0–1.0) instead of a boolean. A threshold of 0.0 means "always automatic" and 1.0 means "always manual." Intermediate values (e.g., 0.5, 0.7) enable fine-grained control where the system proceeds automatically only when the Semantic Escalation confidence score meets or exceeds the threshold:
|
||||
|
||||
<div class="highlight"><pre><code>
|
||||
<span style="opacity: 0.7;"># File: profiles/careful-auto.yaml</span>
|
||||
<span style="color: cyan; font-weight: 600;">name</span>: local/careful-auto
|
||||
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">"Autonomous execution with mandatory sandbox and manual apply"</span>
|
||||
|
||||
<span style="opacity: 0.7;"># Confidence thresholds (0.0 = always auto, 1.0 = always manual)</span>
|
||||
<span style="color: cyan; font-weight: 600;">decompose_task</span>: <span style="color: yellow;">0.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">create_tool</span>: <span style="color: yellow;">0.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">select_tool</span>: <span style="color: yellow;">1.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">edit_code</span>: <span style="color: yellow;">0.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">execute_command</span>: <span style="color: yellow;">0.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">create_file</span>: <span style="color: yellow;">0.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">delete_content</span>: <span style="color: yellow;">1.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">access_network</span>: <span style="color: yellow;">1.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">install_dependency</span>: <span style="color: yellow;">0.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">modify_config</span>: <span style="color: yellow;">0.0</span>
|
||||
<span style="color: cyan; font-weight: 600;">approve_plan</span>: <span style="color: yellow;">0.0</span>
|
||||
|
||||
<span style="opacity: 0.7;"># Safety profile (composed sub-model)</span>
|
||||
<span style="color: cyan; font-weight: 600;">safety</span>:
|
||||
<span style="color: cyan; font-weight: 600;">require_sandbox</span>: <span style="color: magenta; font-weight: 600;">true</span>
|
||||
<span style="color: cyan; font-weight: 600;">require_checkpoints</span>: <span style="color: magenta; font-weight: 600;">true</span>
|
||||
<span style="color: cyan; font-weight: 600;">allow_unsafe_tools</span>: <span style="color: magenta; font-weight: 600;">false</span>
|
||||
</code></pre></div>
|
||||
|
||||
A profile with intermediate thresholds provides nuanced control. For example, `execute_command: 0.7` means decisions during Execute proceed automatically when confidence >= 0.7, but drop to manual review when confidence is below 0.7:
|
||||
|
||||
<div class="highlight"><pre><code>
|
||||
<span style="opacity: 0.7;"># File: profiles/nuanced-auto.yaml</span>
|
||||
<span style="color: cyan; font-weight: 600;">name</span>: local/nuanced-auto
|
||||
<span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">"Nuanced automation with graduated confidence thresholds"</span>
|
||||
|
||||
<span style="color: cyan; font-weight: 600;">decompose_task</span>: <span style="color: yellow;">0.0</span><span style="opacity: 0.7;"> # Always auto-strategize</span>
|
||||
<span style="color: cyan; font-weight: 600;">create_tool</span>: <span style="color: yellow;">0.5</span><span style="opacity: 0.7;"> # Auto-execute when confidence >= 0.5</span>
|
||||
<span style="color: cyan; font-weight: 600;">select_tool</span>: <span style="color: yellow;">1.0</span><span style="opacity: 0.7;"> # Always require manual apply</span>
|
||||
<span style="color: cyan; font-weight: 600;">edit_code</span>: <span style="color: yellow;">0.3</span><span style="opacity: 0.7;"> # Low bar for strategy decisions</span>
|
||||
<span style="color: cyan; font-weight: 600;">execute_command</span>: <span style="color: yellow;">0.7</span><span style="opacity: 0.7;"> # Higher bar for execution decisions</span>
|
||||
<span style="color: cyan; font-weight: 600;">create_file</span>: <span style="color: yellow;">0.5</span><span style="opacity: 0.7;"> # Auto-fix when reasonably confident</span>
|
||||
<span style="color: cyan; font-weight: 600;">delete_content</span>: <span style="color: yellow;">0.8</span><span style="opacity: 0.7;"> # High confidence needed for auto-revision</span>
|
||||
<span style="color: cyan; font-weight: 600;">access_network</span>: <span style="color: yellow;">0.9</span><span style="opacity: 0.7;"> # Very high bar for late-stage reversion</span>
|
||||
<span style="color: cyan; font-weight: 600;">install_dependency</span>: <span style="color: yellow;">0.5</span><span style="opacity: 0.7;"> # Auto-spawn when moderately confident</span>
|
||||
<span style="color: cyan; font-weight: 600;">modify_config</span>: <span style="color: yellow;">0.0</span><span style="opacity: 0.7;"> # Always auto-retry transient errors</span>
|
||||
<span style="color: cyan; font-weight: 600;">approve_plan</span>: <span style="color: yellow;">0.6</span><span style="opacity: 0.7;"> # Auto-restore when fairly confident</span>
|
||||
|
||||
<span style="opacity: 0.7;"># Safety profile (composed sub-model)</span>
|
||||
<span style="color: cyan; font-weight: 600;">safety</span>:
|
||||
<span style="color: cyan; font-weight: 600;">require_sandbox</span>: <span style="color: magenta; font-weight: 600;">true</span>
|
||||
<span style="color: cyan; font-weight: 600;">require_checkpoints</span>: <span style="color: magenta; font-weight: 600;">true</span>
|
||||
<span style="color: cyan; font-weight: 600;">allow_unsafe_tools</span>: <span style="color: magenta; font-weight: 600;">false</span>
|
||||
</code></pre></div>
|
||||
|
||||
<div class="highlight"><pre><code>
|
||||
agents automation-profile add <span style="color: cyan;">--config</span> ./profiles/careful-auto.yaml
|
||||
</code></pre></div>
|
||||
|
||||
#### Semantic Escalation
|
||||
|
||||
Semantic Escalation is the system that computes a **confidence score** (0.0–1.0) for each operation, and it is the mechanism through which automation profile thresholds take effect. The confidence score reflects the system's assessment of how likely an autonomous action is to succeed without human guidance. This score is then compared against the profile's threshold for the relevant flag to determine whether to proceed automatically or escalate to the user.
|
||||
|
||||
The confidence score is computed from multiple factors:
|
||||
|
||||
<div class="highlight"><pre><code>
|
||||
<span style="color: magenta; font-weight: 600;">class</span> <span style="color: cyan; font-weight: 600;">AutonomyController</span>:
|
||||
<span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">should_proceed_automatically</span>(self, decision, context, profile):
|
||||
<span style="color: #66cc66;">"""Determine whether to proceed automatically or escalate to user."""</span>
|
||||
factors = {
|
||||
<span style="color: #66cc66;">'past_success_rate'</span>: self.get_historical_success(decision.type),
|
||||
<span style="color: #66cc66;">'codebase_familiarity'</span>: self.get_familiarity_score(context.project),
|
||||
<span style="color: #66cc66;">'risk_assessment'</span>: self.evaluate_risk(decision),
|
||||
<span style="color: #66cc66;">'invariant_complexity'</span>: self.analyze_invariants(decision)
|
||||
}
|
||||
|
||||
confidence = self.compute_confidence(factors) <span style="opacity: 0.7;"># Returns 0.0–1.0</span>
|
||||
threshold = profile.get_threshold(decision.flag) <span style="opacity: 0.7;"># e.g., execute_command</span>
|
||||
|
||||
<span style="color: magenta; font-weight: 600;">if</span> confidence >= threshold:
|
||||
<span style="opacity: 0.7;"># Confidence meets or exceeds the profile threshold — proceed</span>
|
||||
<span style="color: magenta; font-weight: 600;">return</span> ProceedAutonomously(decision, confidence)
|
||||
<span style="color: magenta; font-weight: 600;">else</span>:
|
||||
<span style="opacity: 0.7;"># Confidence below threshold — escalate to human</span>
|
||||
<span style="color: magenta; font-weight: 600;">return</span> RequestHumanGuidance(decision, confidence, threshold, factors)
|
||||
</code></pre></div>
|
||||
|
||||
**How thresholds and confidence interact**: A profile with `execute_command: 0.7` means the system will make execution decisions automatically when confidence >= 0.7, but will pause for human input when confidence < 0.7. This is more nuanced than a binary on/off: a profile can set a high bar (0.9) for risky operations while being permissive (0.2) for low-risk ones.
|
||||
|
||||
**Special cases**: A threshold of **0.0** means "always automatic" — even zero confidence passes the threshold. A threshold of **1.0** means "always manual" — no confidence level (which tops out below 1.0 in practice) is high enough to pass. This means the old boolean behavior is a strict subset: `true` maps to `0.0` and `false` maps to `1.0`.
|
||||
|
||||
#### Progressive Trust Building
|
||||
|
||||
New users typically follow this progression:
|
||||
|
||||
1. Start with `manual` to understand system behavior
|
||||
1. Move to `review` to let phases run automatically while staying in the decision loop
|
||||
1. Adopt `supervised` as confidence in the planning phase builds
|
||||
1. Try `cautious` for confidence-gated automation that escalates only when uncertain
|
||||
1. Adopt `trusted` for routine development tasks
|
||||
1. Enable `auto` for well-understood projects with strong invariant coverage
|
||||
1. Use `ci` for headless CI/CD pipelines with safety nets intact
|
||||
1. Use `full-auto` for low-risk batch operations where external safety mechanisms exist
|
||||
|
||||
### Guardrails
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
System-level guardrails, pre-flight checks, and runtime limits are defined in [ADR-018: Semantic Error Prevention](adr/ADR-018-semantic-error-prevention.md).
|
||||
|
||||
System-level guardrails are pre-flight checks and runtime limits that prevent plans from executing in invalid or unsafe conditions. These are distinct from **Validations** (the Tool subtype described in Core Concepts > Validation) — guardrails operate at the system/infrastructure level before and during plan execution, whereas Validations verify the *quality of the work produced* by a plan at the end of the Execute phase.
|
||||
|
||||
#### Plan Generation Guardrails
|
||||
|
||||
Before a plan begins execution, the system performs pre-flight validation to ensure the plan is well-formed and its dependencies are satisfiable. These checks must be implemented:
|
||||
|
||||
* **Action schema validation**: Verify the action referenced by the plan exists, is well-formed, and its configuration conforms to the expected schema.
|
||||
* **Actor availability**: Confirm that all actors required by the plan (strategy actor, execution actor, estimation actor, invariant reconciliation actor) are registered and reachable. For remote actors, verify network connectivity.
|
||||
* **Skill and tool existence**: Verify that all skills and tools referenced by the action's actor configuration exist in the registry. This includes both named tools and tools referenced via skills (transitively resolved).
|
||||
* **Automation policy**: Verify that the automation profile allows the requested level of autonomy for the target project, resources, and actions.
|
||||
* **Rollback feasibility**: If `require_checkpoints` is enabled on the plan, verify that all tools in the actor's skill set have `checkpointable: true`. Reject plans that would use non-checkpointable tools under a checkpoint-required policy.
|
||||
* **Resource accessibility**: Verify that the project's linked resources are accessible — git repos are cloneable, databases are connectable, file system paths exist, etc. This is a shallow connectivity check, not a full resource health assessment.
|
||||
* **Validation attachment resolution**: Pre-resolve the validations that will apply to this plan (from resource-direct, project, and plan attachment scopes) and verify they are all registered and their tool definitions are valid. This ensures validation failures during Execute are due to the work product, not misconfigured validations.
|
||||
|
||||
These pre-flight checks prevent "plan runs with fake providers," missing tool errors mid-execution, and other surprises that waste compute and user time. If any pre-flight check fails, the plan is rejected before entering the Strategize phase, with a clear error message identifying the failing check.
|
||||
|
||||
#### Cost and Rate Limits
|
||||
|
||||
Runtime guardrails to prevent runaway resource consumption:
|
||||
|
||||
* **Per-plan budgets**: Maximum API token spend, maximum wall-clock time, maximum number of tool invocations per plan. When a budget is exceeded, the plan pauses and requests user approval to continue or is terminated.
|
||||
* **Per-session budgets**: Aggregate limits across all plans in a session. Prevents a single interactive session from consuming excessive resources.
|
||||
* **Per-org budgets**: Server-enforced limits for multi-user deployments. Administrators set organization-wide spend caps that cannot be overridden by individual users.
|
||||
* **Per-actor limits**: Maximum tool calls per actor invocation, maximum retries per tool failure, maximum tokens per LLM call. Prevents individual actors from looping indefinitely.
|
||||
* **Validation retry limits**: Maximum number of fix-then-revalidate iterations when a required Validation fails during Execute. This is a specific application of per-actor limits — the default is 3 attempts, configurable per plan or in the automation profile.
|
||||
|
||||
Cost and rate limits are future concerns that require integration with LLM provider billing APIs and internal metering. The system should define configuration surfaces for these limits but may initially implement only the per-plan and per-actor limits, with per-session, per-org, and billing integration added later.
|
||||
|
||||
### Correcting Plans (Core Feature)
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
Plan correction, decision revision, and the edit-replay model are defined in [ADR-007: Decision Tree and Correction](adr/ADR-007-decision-tree-and-correction.md).
|
||||
|
||||
Correcting plans is where CleverAgents becomes more than "a fancy prompt runner."
|
||||
|
||||
#### The Goal
|
||||
|
||||
When a plan makes a wrong decision early, we want to:
|
||||
|
||||
* correct the decision,
|
||||
* recompute only the affected subtree,
|
||||
* preserve unaffected work.
|
||||
|
||||
This is explicitly described: "redo everything below that decision, not the entire code base."
|
||||
|
||||
#### Decision Tree Representation
|
||||
|
||||
Every plan records (see Decision Data Model section):
|
||||
|
||||
* decisions (choice points) - created during Strategize, including `invariant_enforced`, `subplan_spawn`, and `subplan_parallel_spawn` decisions
|
||||
* dependencies (which later work depended on that decision)
|
||||
* child plans spawned because of that decision - populated during Execute
|
||||
* artifacts generated under that branch
|
||||
|
||||
This makes plan runs auditable and correctable.
|
||||
|
||||
#### Two Correction Modes
|
||||
|
||||
=== "Revert (`--mode=revert`)"
|
||||
|
||||
!!! warning "Potentially Expensive"
|
||||
Find the decision point in the tree, roll back all changes (code and non-code) to that point, and re-run from that decision point forward. Old execution artifacts are kept for comparison.
|
||||
|
||||
- [x] Roll back all changes to the decision point
|
||||
- [x] Re-run from that decision point forward
|
||||
- [x] Keep old execution artifacts for comparison
|
||||
- [ ] ==Potentially expensive== if high up in the tree
|
||||
|
||||
=== "Append (`--mode=append`)"
|
||||
|
||||
!!! success "Safer and Cheaper"
|
||||
Leave history intact and append a new plan at the end that fixes the outcome. Does not rewrite history.
|
||||
|
||||
- [x] Leave history intact
|
||||
- [x] Append a new corrective plan at the end
|
||||
- [x] Cheaper and safer in many cases
|
||||
- [x] Does ==not rewrite history==
|
||||
|
||||
#### Correction Flow (Revert Mode)
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The detailed rollback and replay mechanics, including mid-phase correction flows and cross-sandbox coordination, are defined in [ADR-035: Decision Tree Rollback and Replay](adr/ADR-035-decision-tree-rollback-and-replay.md).
|
||||
|
||||
Correction operates on **two independent rollback dimensions**:
|
||||
|
||||
| Dimension | What It Restores | Mechanism | Applicable Phase |
|
||||
|---|---|---|---|
|
||||
| **Resource rollback** | Sandbox contents (files, database state, filesystem) | Checkpoint restoration via sandbox-strategy-specific handlers | Execute only |
|
||||
| **Reasoning rollback** | Actor's conversation history, intermediate reasoning, graph state | LangGraph checkpoint restoration from `actor_state_ref` | Strategize and Execute |
|
||||
|
||||
##### Mid-Strategize Correction
|
||||
|
||||
When the target decision was created during Strategize (e.g., a `strategy_choice` or `subplan_spawn`), **only reasoning rollback is needed** because Strategize is read-only — no resource modifications exist to undo:
|
||||
|
||||
1. **Restore actor state**: Load the target decision's `context_snapshot.actor_state_ref` (LangGraph checkpoint). This restores the strategy actor to the exact reasoning state it was in when the decision was made.
|
||||
2. **Supersede affected subtree**: Mark the target decision and all its descendants as superseded (cascading via ADR-034). Decisions above the target remain active and unchanged.
|
||||
3. **Inject guidance**: Create a `user_intervention` decision containing the user's `--guidance` text.
|
||||
4. **Resume strategy actor**: The actor continues reasoning from the restored state, informed by the correction guidance. New decisions replace the superseded ones, with `is_correction: true, corrects_decision_id: <target>`.
|
||||
5. **Record correction**: Create a `correction_attempts` record linking old and new decisions.
|
||||
|
||||
If the plan was already in Execute when this correction is requested, all Execute-phase work is rolled back (via checkpoint groups — see below) and the plan reverts to Strategize at the corrected decision point.
|
||||
|
||||
##### Mid-Execute Correction
|
||||
|
||||
When the target decision was created during Execute (e.g., an `implementation_choice` or `error_recovery`), **both resource and reasoning rollback are needed**:
|
||||
|
||||
1. **Load checkpoint group**: Every Execute-phase decision has a corresponding **checkpoint group** — one per-resource checkpoint for each sandbox resource that had been modified at the time the decision was recorded. These are stored in `checkpoint_metadata` linked by `decision_id`.
|
||||
|
||||
2. **Classify resources**:
|
||||
- *Rollbackable*: resources with sandbox strategies that support checkpointing (`git_worktree`, `filesystem_copy`, `overlay`, `transaction_rollback`)
|
||||
- *Non-rollbackable*: resources with `sandbox.strategy: none` (tracked with marker records)
|
||||
- *Unaffected*: resources not yet modified at the decision point (no checkpoint row — no rollback needed)
|
||||
|
||||
3. **Warn about limitations**: If non-rollbackable resources exist, the user is warned and must confirm. If downstream decisions triggered tools with irreversible `side_effects`, the user is warned that external effects cannot be undone.
|
||||
|
||||
4. **Resource rollback**: For each rollbackable checkpoint, dispatch to the strategy-specific handler:
|
||||
|
||||
| Strategy | Rollback Operation |
|
||||
|---|---|
|
||||
| `git_worktree` | `git reset --hard <commit_sha>` in the worktree |
|
||||
| `filesystem_copy` | Restore from archived snapshot |
|
||||
| `overlay` | Discard overlay writes since checkpoint |
|
||||
| `transaction_rollback` | `ROLLBACK TO SAVEPOINT <savepoint_name>` |
|
||||
|
||||
If any individual resource rollback fails, the correction is marked `'failed'` and the plan enters `errored` state.
|
||||
|
||||
5. **Reasoning rollback**: Restore the execution actor's LangGraph state from `context_snapshot.actor_state_ref`.
|
||||
6. **Supersede affected subtree**: Cascade superseding through the target and all descendants.
|
||||
7. **Inject guidance and resume**: The execution actor continues from the restored state.
|
||||
|
||||
!!! note "Decision-Aligned Checkpointing"
|
||||
The 1:1 mapping between Execute-phase decisions and resource checkpoints is created automatically by the `record_decision` tool (see Decision Recording Protocol in the Core Concepts section). Every `record_decision` call during Execute triggers a coordinated checkpoint group across all modified sandbox resources. This is what enables fine-grained rollback to any individual Execute-phase decision rather than reverting the entire Execute phase.
|
||||
|
||||
##### Affected Subtree Computation
|
||||
|
||||
The "affected subtree" — all decisions and child plans invalidated by a correction — is computed by walking the influence DAG (not just the structural tree):
|
||||
|
||||
<div class="highlight"><pre><code>
|
||||
<span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">compute_affected_subtree</span>(target_decision_id):
|
||||
affected_decisions = {target_decision_id}
|
||||
affected_plans = <span style="color: cyan; font-weight: 600;">set</span>()
|
||||
queue = [target_decision_id]
|
||||
|
||||
<span style="color: magenta; font-weight: 600;">while</span> queue:
|
||||
current = queue.pop(<span style="color: yellow;">0</span>)
|
||||
|
||||
<span style="opacity: 0.7;"># Follow structural tree children</span>
|
||||
children = query(<span style="color: #66cc66;">"SELECT decision_id FROM decisions "</span>
|
||||
<span style="color: #66cc66;">"WHERE parent_decision_id = :current AND superseded_by IS NULL"</span>)
|
||||
|
||||
<span style="opacity: 0.7;"># Follow influence DAG dependents</span>
|
||||
dependents = query(<span style="color: #66cc66;">"SELECT downstream_ref FROM decision_dependencies "</span>
|
||||
<span style="color: #66cc66;">"WHERE upstream_decision_id = :current AND dependency_type = 'decision'"</span>)
|
||||
|
||||
<span style="color: magenta; font-weight: 600;">for</span> d <span style="color: magenta; font-weight: 600;">in</span> children | dependents:
|
||||
<span style="color: magenta; font-weight: 600;">if</span> d <span style="color: magenta; font-weight: 600;">not in</span> affected_decisions:
|
||||
affected_decisions.add(d)
|
||||
queue.append(d)
|
||||
|
||||
<span style="opacity: 0.7;"># Collect affected child plans</span>
|
||||
child_plans = query(<span style="color: #66cc66;">"SELECT downstream_ref FROM decision_dependencies "</span>
|
||||
<span style="color: #66cc66;">"WHERE upstream_decision_id = :current AND dependency_type = 'plan'"</span>)
|
||||
affected_plans.update(child_plans)
|
||||
|
||||
<span style="color: magenta; font-weight: 600;">return</span> affected_decisions, affected_plans
|
||||
</code></pre></div>
|
||||
|
||||
##### Cross-Plan Correction Cascading
|
||||
|
||||
When the affected subtree includes child plans (via `subplan_spawn` or `subplan_parallel_spawn` decisions), the child plan's state determines the behavior:
|
||||
|
||||
| Child Plan State | Action |
|
||||
|---|---|
|
||||
| Not yet started | Cancel the child plan |
|
||||
| In progress (Strategize or Execute) | Cancel the child plan, roll back its sandbox |
|
||||
| Completed but not applied | Cancel the child plan, roll back its sandbox |
|
||||
| **Already applied** | **Correction rejected** — applied changes cannot be unilaterally reverted; correct the child plan independently or use `--mode=append` on the parent |
|
||||
|
||||
##### Rollback Tiers
|
||||
|
||||
The system's rollback capability depends on the plan's checkpoint and sandbox configuration:
|
||||
|
||||
| Tier | Prerequisites | Capability |
|
||||
|---|---|---|
|
||||
| **Full decision-level** | Checkpointing enabled + sandboxable resources | Roll back to any individual Execute-phase decision |
|
||||
| **Phase-level** | Checkpointing disabled or unsupported resources | Revert entire Execute phase → Strategize; re-execute from scratch |
|
||||
| **No rollback** | `sandbox.strategy: none` + checkpointing disabled | Only `--mode=append` corrections available |
|
||||
|
||||
The system detects the available tier automatically and informs the user when a requested correction exceeds the available capability.
|
||||
|
||||
##### Phase Boundary Interaction
|
||||
|
||||
`agents plan correct` is **orthogonal** to phase reversion (Execute → Strategize):
|
||||
|
||||
- **Phase reversion** is *actor-triggered* when execution constraints are too tight — the actor signals that the strategy needs adjustment.
|
||||
- **Decision correction** is *user-triggered* via `plan correct` — the user identifies a wrong decision.
|
||||
|
||||
They can interact: correcting a Strategize-phase decision while the plan is in Execute causes both resource rollback (of Execute-phase work) and phase reversion to Strategize. Correcting an Execute-phase decision while still in Execute performs resource rollback within Execute without a phase change.
|
||||
|
||||
##### Long-Running Database Transactions
|
||||
|
||||
The `transaction_rollback` sandbox strategy uses SAVEPOINTs for decision-aligned checkpoints within a single transaction spanning Execute. For plans with extended execution times, this may exceed database transaction timeouts. Recommended mitigations:
|
||||
|
||||
- **Decompose into child plans**: Each child plan gets a shorter transaction (aligns with hierarchical decomposition).
|
||||
- **Use `none` strategy with `--mode=append`**: Accept non-rollbackable database changes; fix issues via append corrections.
|
||||
- **Implement a custom snapshot-based strategy**: A custom `database-snapshot` resource type using point-in-time snapshots instead of long transactions.
|
||||
|
||||
#### History Cleanup
|
||||
|
||||
**History can only be flagged for cleanup after a plan reaches the `applied` state.**
|
||||
|
||||
Once a plan is applied:
|
||||
- It can no longer be rolled back
|
||||
- Old correction artifacts can be archived or deleted based on retention policy
|
||||
- The decision tree is preserved for audit purposes (superseded decisions are never deleted, per ADR-034)
|
||||
|
||||
#### CLI Commands for Correction
|
||||
|
||||
<div class="highlight"><pre><code>
|
||||
<span style="opacity: 0.7;"># View decision tree</span>
|
||||
agents plan tree <plan_id>
|
||||
agents <span style="color: cyan;">--format</span>=json plan tree <plan_id> # For visualization tools
|
||||
|
||||
<span style="opacity: 0.7;"># View decision tree including superseded branches</span>
|
||||
agents plan tree <span style="color: cyan;">--show-superseded</span> <plan_id>
|
||||
|
||||
<span style="opacity: 0.7;"># Inspect a specific decision</span>
|
||||
agents plan explain <decision_id>
|
||||
<span style="opacity: 0.7;"># Shows: question, chosen option, alternatives, rationale, downstream impact</span>
|
||||
|
||||
<span style="opacity: 0.7;"># Correct via revert-and-replay</span>
|
||||
agents plan correct <decision_id> <span style="color: cyan;">--mode</span>=revert <span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"<what the decision should be>"</span>
|
||||
<span style="opacity: 0.7;"># Re-executes from that point with the new guidance</span>
|
||||
|
||||
<span style="opacity: 0.7;"># Correct via append (add fix at end) </span>
|
||||
agents plan correct <decision_id> <span style="color: cyan;">--mode</span>=append <span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"<description of the fix>"</span>
|
||||
<span style="opacity: 0.7;"># Creates a new child plan to fix the outcome without rewriting history</span>
|
||||
|
||||
<span style="opacity: 0.7;"># Compare old vs new after correction</span>
|
||||
agents plan diff <span style="color: cyan;">--correction</span> <correction_attempt_id>
|
||||
</code></pre></div>
|
||||
|
||||
#### Correction Safety
|
||||
|
||||
!!! success "Safety Guarantees"
|
||||
Corrections always:
|
||||
|
||||
- [x] Create a new attempt revision (increment `plan.attempt`)
|
||||
- [x] Preserve old artifacts for diff/compare
|
||||
- [x] Run execute in sandbox again
|
||||
- [x] Require apply gating again
|
||||
- [x] ==Never modify already-applied changes==
|
||||
- [x] Warn about irreversible side effects before proceeding
|
||||
- [x] Reject correction of decisions whose affected subtree includes applied child plans
|
||||
|
||||
This keeps history reproducible and prevents accidental destructive edits.
|
||||
|
||||
### Human-in-the-Loop Collaboration
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
Human-in-the-loop controls, interruptibility, and approval gates are defined in [ADR-017: Automation Profiles](adr/ADR-017-automation-profiles.md).
|
||||
|
||||
Even though the direction is "more autonomous," the transcript explicitly recognizes that real workflows require engineers to collaborate with the system, editing code while it works, and using better UX integration (TUI/web/IDE).
|
||||
|
||||
!!! tip "Design Principles for Human-in-the-Loop"
|
||||
| Principle | Description |
|
||||
| :-------- | :---------- |
|
||||
| **Visibility** | What is the system doing ==right now==? |
|
||||
| **Interruptibility** | Pause / cancel / retry at any point |
|
||||
| **Editability** | Allow user to modify strategy before execute |
|
||||
| **Reconciliation** | Detect if user changed sandbox files mid-run and handle it |
|
||||
|
||||
### UI / Interaction Model
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The CLI-first interaction model, TUI, and output rendering are defined in [ADR-021: CLI and Output Rendering](adr/ADR-021-cli-and-output-rendering.md).
|
||||
|
||||
#### CLI-first + TUI + Web App + IDE
|
||||
|
||||
!!! abstract "Multi-Frontend Architecture"
|
||||
The system is ==CLI-first==, with a single UI codebase powering multiple frontends:
|
||||
|
||||
- [x] **CLI** — Primary interface for all operations
|
||||
- [x] **TUI** — Built using Textual for rich terminal experiences
|
||||
- [x] **Web App** — Generated from TUI "for free"
|
||||
- [ ] **IDE Plugin** — Future: embeds the TUI in the IDE
|
||||
|
||||
#### Plan Tree Visualization
|
||||
|
||||
The TUI should show:
|
||||
|
||||
* plan list
|
||||
* plan details
|
||||
* plan tree (ASCII)
|
||||
* diff view
|
||||
* approvals
|
||||
|
||||
And should later allow exporting the tree as image (PNG) or JSON for other visualization tools.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,32 @@
|
||||
# CleverAgents Specification
|
||||
|
||||
This directory contains the authoritative specification for CleverAgents, split into logical sub-documents for easier navigation and review.
|
||||
|
||||
## Contents
|
||||
|
||||
| Document | Description |
|
||||
| :------- | :---------- |
|
||||
| [Overview & Glossary](overview.md) | Overview, standards alignment, and glossary of core terms |
|
||||
| [CLI Commands](cli.md) | Complete CLI command reference (~18,000 lines) |
|
||||
| [Core Concepts](core-concepts.md) | Plan lifecycle, actors, tools, skills, sessions, resources, and context |
|
||||
| [Behavior](behavior.md) | Automation profiles, guardrails, and plan correction |
|
||||
| [TUI](tui.md) | Text User Interface architecture and components |
|
||||
| [Configuration](configuration.md) | Configuration keys and file schemas |
|
||||
| [Workflow Examples](examples.md) | End-to-end workflow examples |
|
||||
| [Architecture](architecture.md) | System architecture, ACMS, storage, and security |
|
||||
| [Milestone Plan](milestones.md) | Milestone delivery plan |
|
||||
| [ACMS v1](acms.md) | ACMS v1 detailed specification (Milestone v3.4.0) |
|
||||
|
||||
## Source of Truth
|
||||
|
||||
`docs/specification/` is the authoritative source of truth for architectural decisions and design details. Before beginning any task, always review the relevant parts of the specification to understand the intended design. When there is a discrepancy between the current codebase and the specification, always assume the specification is correct and align the code accordingly.
|
||||
|
||||
## Navigation
|
||||
|
||||
- **New to CleverAgents?** Start with [Overview & Glossary](overview.md)
|
||||
- **Working on CLI features?** See [CLI Commands](cli.md)
|
||||
- **Understanding the domain model?** See [Core Concepts](core-concepts.md)
|
||||
- **Working on the TUI?** See [TUI](tui.md)
|
||||
- **Configuring the system?** See [Configuration](configuration.md)
|
||||
- **Understanding the architecture?** See [Architecture](architecture.md)
|
||||
- **Working on ACMS?** See [ACMS v1](acms.md)
|
||||
@@ -0,0 +1,355 @@
|
||||
## Milestone Plan
|
||||
|
||||
This section defines the ordered milestone plan for CleverAgents v3.x, mapping architectural features to verifiable deliverables. Each milestone builds on the previous and is independently testable. Milestones v3.0.0 and v3.1.0 are **complete**. This plan covers v3.2.0 through v3.8.0 — the production-ready target including server mode.
|
||||
|
||||
!!! note "Milestone Status (as of 2026-04-11)"
|
||||
- **v3.0.0** ✅ CLOSED — Minimal Local Source-Code Workflow
|
||||
- **v3.1.0** ✅ CLOSED — Actor Compiler + Full LLM Integration
|
||||
- **v3.2.0** 🔄 IN PROGRESS — Decisions + Validations + Invariants (571 open / 257 closed)
|
||||
- **v3.3.0** 🔄 IN PROGRESS — Corrections + Subplans + Checkpoints (122 open / 108 closed)
|
||||
- **v3.4.0** 🔄 IN PROGRESS — ACMS v1 + Context Scaling (200 open / 137 closed)
|
||||
- **v3.5.0** 🔄 IN PROGRESS — Autonomy Hardening (971 open / 201 closed)
|
||||
- **v3.6.0** 🔄 IN PROGRESS — Advanced Concepts & Deferred Features (282 open / 150 closed)
|
||||
- **v3.7.0** 🔄 IN PROGRESS — TUI Implementation (526 open / 427 closed)
|
||||
- **v3.8.0** 🔄 IN PROGRESS — Server Implementation (352 open / 132 closed)
|
||||
|
||||
---
|
||||
|
||||
### v3.2.0 — Decisions + Validations + Invariants
|
||||
|
||||
**Goal**: Decisions are recorded during Strategize and Execute phases and persisted to the database. Users can view the decision tree, inspect individual decisions, manage invariants, and correct decisions with selective subtree recomputation.
|
||||
|
||||
**Spec Coverage**: [Decision Tree and Correction](#decision-tree-and-correction), [Invariant System](#invariant-system), [Validation Abstraction](#validation-abstraction)
|
||||
|
||||
#### Deliverables
|
||||
|
||||
| # | Deliverable | Spec Reference | Verifiable Check |
|
||||
|---|-------------|----------------|-----------------|
|
||||
| 1 | Decision recording during Strategize with full context snapshots | §Decision Tree — Recording Protocol | `agents plan tree <plan_id>` renders non-empty tree after strategize |
|
||||
| 2 | Decision recording during Execute phase | §Decision Tree — Execute Phase | Execute-phase decisions appear in `plan tree` output |
|
||||
| 3 | `agents plan tree` renders the decision tree with correct hierarchy | §CLI Commands — plan tree | Command exits 0, shows tree structure with decision IDs |
|
||||
| 4 | `agents plan explain <decision_id>` shows decision details including alternatives | §CLI Commands — plan explain | Output includes `alternatives`, `confidence_score`, `rationale` fields |
|
||||
| 5 | `agents invariant add` creates invariants; `agents invariant list` displays them | §CLI Commands — invariant | Round-trip: add then list shows the invariant |
|
||||
| 6 | Invariants enforced during Strategize phase | §Invariant System — Enforcement | `invariant_enforced` decision type appears in tree when invariant applies |
|
||||
| 7 | `agents plan correct --mode=revert` re-executes from targeted decision point | §Correction Model — Revert Mode | Correction creates new attempt, affected subtree recomputed |
|
||||
| 8 | `agents plan correct --mode=append` adds guidance without recomputing | §Correction Model — Append Mode | Append correction recorded; no subtree recomputation triggered |
|
||||
| 9 | `agents plan correct --dry-run` shows warnings, recompute time, and hint | §Correction Model — Dry Run | Output includes `warnings`, `estimated_recompute_time_seconds`, and "remove --dry-run" hint |
|
||||
| 10 | `plan.attempt` incremented on each correction | §Correction Safety Guarantees | `plan show` displays `Attempt: N` where N > 1 after correction |
|
||||
| 11 | Validation runner executes required and informational validations | §Validation Abstraction | `agents validation attach` + plan execute triggers validation; required failure blocks apply |
|
||||
| 12 | Output validation is flexible — structural checks, not exact character matching | §Testing Strategy | Tests use structural assertions, not string equality |
|
||||
| 13 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
|
||||
|
||||
#### Key Architectural Constraints
|
||||
|
||||
- **Decision persistence**: All decisions use ULID identifiers; stored in `v3_decisions` table with `context_snapshot` JSONB column.
|
||||
- **Correction atomicity**: `CorrectionService.execute_revert()` MUST increment `plan.attempt` via `PlanLifecycleService` before recomputing the subtree.
|
||||
- **Dry-run purity**: `generate_dry_run_report()` MUST be used for `--dry-run` (not `analyze_impact()`); it preserves correction status at PENDING.
|
||||
- **Invariant precedence**: plan > action > project > global; `non_overridable` global invariants always win.
|
||||
- **Validation read-only**: Validations are always `writes=False`, `checkpointable=False`.
|
||||
|
||||
#### Definition of Done
|
||||
|
||||
- All 13 deliverables verified by automated tests
|
||||
- `nox` passes with coverage ≥ 97%
|
||||
- No open P0/P1 bugs in v3.2.0 milestone
|
||||
- `agents plan tree`, `plan explain`, `plan correct`, `invariant add/list` all functional end-to-end
|
||||
|
||||
---
|
||||
|
||||
### v3.3.0 — Corrections + Subplans + Checkpoints
|
||||
|
||||
**Goal**: Plans can spawn child plans (subplans) during execution. Subplans execute in parallel with configurable concurrency limits. Results are merged back using three-way merge strategies. Checkpointing enables rollback to previous plan states.
|
||||
|
||||
**Spec Coverage**: [Subplan Architecture](#subplan-architecture), [Checkpoint and Rollback](#checkpoint-and-rollback), [Merge Strategies](#merge-strategies), [Correction Model](#correction-model)
|
||||
|
||||
#### Deliverables
|
||||
|
||||
| # | Deliverable | Spec Reference | Verifiable Check |
|
||||
|---|-------------|----------------|-----------------|
|
||||
| 1 | Plans spawn child subplans during Execute via `subplan_spawn` decision type | §Subplan Architecture | `plan tree` shows `subplan_spawn` decisions with child plan IDs |
|
||||
| 2 | Sequential subplan execution functional | §Subplan Execution — Sequential | Child plan completes before parent resumes |
|
||||
| 3 | Parallel subplan execution with `max_parallel` limit | §Subplan Execution — Parallel | Multiple child plans execute concurrently up to `max_parallel` |
|
||||
| 4 | Parent plan tracks all subplan statuses | §Subplan Status Tracking | `plan show <parent_id>` lists child plan statuses |
|
||||
| 5 | Three-way merge combines non-conflicting changes | §Merge Strategies — Three-Way | Non-conflicting file edits from two subplans both appear in merged result |
|
||||
| 6 | Merge conflicts surfaced to user for resolution | §Merge Strategies — Conflict Resolution | Conflicting changes produce `CONFLICT` markers; user prompted |
|
||||
| 7 | Checkpoint creation during Execute | §Checkpoint System | `plan show` lists checkpoints; each has a ULID and timestamp |
|
||||
| 8 | `agents plan rollback <plan_id> --checkpoint <id>` restores plan state | §CLI Commands — plan rollback | Plan state reverts to checkpoint; subsequent apply uses checkpoint state |
|
||||
| 9 | Correction flow functional (`plan correct --mode revert` and `--mode append`) | §Correction Model | Both modes functional end-to-end (builds on v3.2.0) |
|
||||
| 10 | Correction rejects decisions whose subtree includes applied child plans | §Correction Safety Guarantees | Attempting to correct such a decision returns error with explanation |
|
||||
| 11 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
|
||||
|
||||
#### Key Architectural Constraints
|
||||
|
||||
- **Subplan identity**: Child plans use ULID identifiers only (no namespaced name); referenced by plan ID in all operations.
|
||||
- **Sandbox isolation**: Each subplan operates in its own sandbox; parent sandbox merges results via `MergeWorkflow`.
|
||||
- **Checkpoint granularity**: Checkpoints capture the full plan state including decision tree, sandbox state hash, and resource versions.
|
||||
- **Parallel limit enforcement**: `max_parallel` is enforced by the `PlanLifecycleService`; excess subplans queue until a slot opens.
|
||||
- **Merge strategy selection**: Strategy selected per resource type; `git-checkout` uses git three-way merge; `fs-mount` uses file-level merge.
|
||||
|
||||
#### Definition of Done
|
||||
|
||||
- All 11 deliverables verified by automated tests
|
||||
- `nox` passes with coverage ≥ 97%
|
||||
- No open P0/P1 bugs in v3.3.0 milestone
|
||||
- Subplan spawning, parallel execution, checkpoint/rollback, and merge all functional end-to-end
|
||||
|
||||
---
|
||||
|
||||
### v3.4.0 — ACMS v1 + Context Scaling
|
||||
|
||||
**Goal**: The Advanced Context Management System v1 is operational. Projects with 10,000+ files can be indexed and queried. The context assembly pipeline produces scoped, budget-constrained context views for actors. Hot/warm/cold storage tiers manage context lifecycle.
|
||||
|
||||
**Spec Coverage**: [ACMS Architecture](#acms-advanced-context-management-system), [Context Assembly Pipeline](#context-assembly-pipeline), [UKO Ontology](#uko-universal-knowledge-ontology), [Hot/Warm/Cold Tiers](#context-storage-tiers)
|
||||
|
||||
#### Deliverables
|
||||
|
||||
| # | Deliverable | Spec Reference | Verifiable Check |
|
||||
|---|-------------|----------------|-----------------|
|
||||
| 1 | Context policies configurable with view-specific settings (strategize/execute/apply/default) | §Context Policy Configuration | `agents project context set --view strategize` persists and is retrievable |
|
||||
| 2 | Budget enforcement: `max_file_size` and `max_total_size` constraints respected | §Context Budget Enforcement | Files exceeding `max_file_size` excluded; total context ≤ `max_total_size` |
|
||||
| 3 | `agents project context show` displays current context policy | §CLI Commands — project context show | Command exits 0, shows all configured parameters |
|
||||
| 4 | `agents project context inspect` runs context assembly and shows result | §CLI Commands — project context inspect | Returns assembled context fragments with UKO URIs |
|
||||
| 5 | `agents project context simulate` shows budget simulation without executing | §CLI Commands — project context simulate | Returns token budget breakdown without modifying state |
|
||||
| 6 | Context assembly pipeline produces scoped context output for actors | §Context Assembly Pipeline | Plan execution uses ACMS context; actor receives assembled fragments |
|
||||
| 7 | Hot/warm/cold tier management functional | §Context Storage Tiers | Hot tier bounded by `hot_max_tokens`; overflow moves to warm tier |
|
||||
| 8 | Projects with 10,000+ files index without timeout | §ACMS Scalability | Indexing a 10k-file project completes within 5 minutes |
|
||||
| 9 | UKO ontology indexing for Python and common resource types | §UKO — Technology-Specific Layer | Python files indexed with `uko-py:` URIs; relationships inferred |
|
||||
| 10 | Pluggable context strategies execute in parallel | §Context Strategy Execution | Multiple strategies run concurrently; results fused by `FragmentFusionCoordinator` |
|
||||
| 11 | Skeleton compression for child plan context inheritance | §Skeleton Compressor | Child plans receive compressed parent context via `skeleton_ratio` budget |
|
||||
| 12 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
|
||||
|
||||
#### Key Architectural Constraints
|
||||
|
||||
- **Pipeline composability**: All 10 Context Assembly Pipeline slots are overridable at plan > project > global scope.
|
||||
- **UKO URI stability**: UKO URIs are stable identifiers; changing a file's content does not change its URI.
|
||||
- **Strategy parallelism**: `ParallelStrategyExecutor` runs strategies concurrently with circuit-breaker protection per strategy.
|
||||
- **Budget packing**: `GreedyKnapsackPacker` fills context up to token budget; fragments ordered by `RelevanceCoherenceOrderer`.
|
||||
- **Tier eviction**: Hot tier evicts to warm on overflow; warm evicts to cold on age threshold; cold is persistent storage.
|
||||
|
||||
#### Definition of Done
|
||||
|
||||
- All 12 deliverables verified by automated tests
|
||||
- `nox` passes with coverage ≥ 97%
|
||||
- No open P0/P1 bugs in v3.4.0 milestone
|
||||
- ACMS pipeline functional end-to-end; 10k-file project indexes and queries successfully
|
||||
|
||||
---
|
||||
|
||||
### v3.5.0 — Autonomy Hardening
|
||||
|
||||
**Goal**: The system can autonomously execute a large-scale task using hierarchical plan decomposition with 4+ levels of subplans, decision correction with selective subtree recomputation, parallel execution scaling to 10+ concurrent subplans, and validation-gated apply.
|
||||
|
||||
**Spec Coverage**: [Automation Profiles](#automation-profiles), [Safety Profiles](#safety-profiles), [A2A Facade](#agent-to-agent-protocol-a2a), [Guard Enforcement](#guard-enforcement), [Event Queue](#event-queue)
|
||||
|
||||
#### Deliverables
|
||||
|
||||
| # | Deliverable | Spec Reference | Verifiable Check |
|
||||
|---|-------------|----------------|-----------------|
|
||||
| 1 | A2A facade session and plan lifecycle operations functional via CLI | §A2A Local Facade | `agents session create` and `agents plan use` route through A2A facade |
|
||||
| 2 | Event queue publish/subscribe operational | §Event Queue | Plan lifecycle events published; subscribers receive events |
|
||||
| 3 | Guard enforcement: denylist, budget caps, tool call limits | §Guard Enforcement | Plan exceeding `max_cost_per_plan` is blocked; denylist tools rejected |
|
||||
| 4 | Automation profile resolution precedence correct (plan > action > global) | §Automation Profiles — Precedence | Plan-level profile overrides action-level; action overrides global |
|
||||
| 5 | Safety profile enforcement: `require_sandbox`, `require_checkpoints`, `allow_unsafe_tools` | §Safety Profiles | Plans with `require_sandbox=true` fail if sandbox unavailable |
|
||||
| 6 | Hierarchical decomposition creates 4+ levels of subplans | §Subplan Architecture — Hierarchy | `plan tree` shows 4+ nesting levels for complex tasks |
|
||||
| 7 | Parallel execution scales to 10+ concurrent subplans | §Subplan Execution — Parallel | 10 subplans execute concurrently without deadlock or resource starvation |
|
||||
| 8 | Decision correction recomputes only affected subtree | §Correction Model — Selective Recomputation | Unaffected decisions preserved; only downstream decisions recomputed |
|
||||
| 9 | Validation-gated apply: required validations must pass before apply | §Validation Abstraction — Apply Gating | Apply blocked when required validation fails; informational validation does not block |
|
||||
| 10 | A realistic porting task completes autonomously | §Autonomy Acceptance | End-to-end task (e.g., port a Python module) completes without human intervention |
|
||||
| 11 | `agents automation-profile add/list/show` functional | §CLI Commands — automation-profile | Round-trip: add profile, list shows it, show displays details |
|
||||
| 12 | `agents plan guard` shows active guards for a plan | §CLI Commands — plan guard | Command shows denylist, budget caps, tool limits |
|
||||
| 13 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
|
||||
|
||||
#### Key Architectural Constraints
|
||||
|
||||
- **A2A facade**: In local mode, `A2aLocalFacade` resolves all A2A operations in-process; no subprocess spawning for local operations.
|
||||
- **Guard evaluation order**: Denylist checked first (fast reject), then budget caps, then tool call limits.
|
||||
- **Autonomy threshold**: `0.0` = always automatic; `1.0` = always manual; eight built-in profiles from `manual` to `full-auto`.
|
||||
- **Subtree recomputation**: Only decisions with `depends_on` edges to the corrected decision are recomputed; others preserved.
|
||||
- **Validation gating**: `required` validations block apply; `informational` validations log but do not block.
|
||||
|
||||
#### Definition of Done
|
||||
|
||||
- All 13 deliverables verified by automated tests
|
||||
- `nox` passes with coverage ≥ 97%
|
||||
- No open P0/P1 bugs in v3.5.0 milestone
|
||||
- Full autonomy acceptance flow with 4+ subplan levels completes successfully
|
||||
|
||||
---
|
||||
|
||||
### v3.6.0 — Advanced Concepts & Deferred Features
|
||||
|
||||
**Goal**: Advanced concepts not needed for basic MVP. Extends beyond core MVP but does not require TUI (v3.7.0) or Server (v3.8.0). Includes advanced context strategies, additional LLM backends, additional resource types, A2A module rename, container tool execution, pluggable scope chain extensions, cost/session budgets, and E2E workflow specification tests.
|
||||
|
||||
**Spec Coverage**: [LSP Integration](#lsp-integration), [Resource Type Inheritance](#resource-type-inheritance), [Devcontainer Integration](#devcontainer-integration), [Container Resource Types](#container-resource-types), [Advanced Context Strategies](#advanced-context-strategies), [Provider Registry](#provider-registry)
|
||||
|
||||
#### Deliverables
|
||||
|
||||
| # | Deliverable | Spec Reference | Verifiable Check |
|
||||
|---|-------------|----------------|-----------------|
|
||||
| 1 | ACP → A2A module rename and symbol standardization complete | §A2A Protocol — Module Structure | No `acp` references in public API; all imports use `a2a` namespace |
|
||||
| 2 | LSP Registry: `agents lsp add/list/show/remove` functional | §LSP Integration — Registry | Round-trip: add LSP server, list shows it, show displays capabilities |
|
||||
| 3 | LSP server bound to actor graph node via YAML configuration | §LSP Integration — Actor Binding | Actor with `lsp_bindings` activates LSP server on startup |
|
||||
| 4 | LSP capabilities exposed as tools via `LSPToolAdapter` | §LSP Integration — Tool Adapter | `agents actor run` with LSP-bound actor can invoke `lsp/diagnostics` tool |
|
||||
| 5 | LSP diagnostics injected into ACMS hot context automatically | §LSP Integration — Context Enrichment | Plan execution with LSP-bound actor includes diagnostic fragments in context |
|
||||
| 6 | Resource type inheritance: `inherits` field functional | §Resource Type Inheritance | Subtype resource inherits parent type's tools and sandbox strategy |
|
||||
| 7 | Polymorphic tool matching: tools bound to parent type work with subtypes | §Resource Type Inheritance — Polymorphism | Tool registered for `container-instance` works with `devcontainer-instance` |
|
||||
| 8 | Devcontainer auto-discovery from `.devcontainer/devcontainer.json` | §Devcontainer Integration | `agents resource add git-checkout <url>` auto-discovers devcontainer |
|
||||
| 9 | Devcontainer lazy activation: container built only when first needed | §Devcontainer Integration — Lazy Activation | Container not started until plan execution requires it |
|
||||
| 10 | Container tool execution: tools run inside devcontainer | §Container Resource Types — Execution | Tool invocation with `execution_environment` set runs in container |
|
||||
| 11 | Additional LLM provider backends registered via `ProviderRegistry` | §Provider Registry | `agents actor add` with non-OpenAI/Anthropic provider works |
|
||||
| 12 | Cloud resource types stubbed with `NotImplementedError` for future implementation | §Cloud Resource Types | `agents resource add cloud-*` validates config but raises `NotImplementedError` for sandbox |
|
||||
| 13 | Pluggable scope chain resolution extensions | §Scope Chain Resolution | Custom scope resolver registered and invoked during name resolution |
|
||||
| 14 | Cost and session budget enforcement | §Safety Profiles — Budget Caps | Plan exceeding `max_cost_per_plan` or `max_total_cost` is blocked |
|
||||
| 15 | E2E workflow specification tests covering all major user workflows | §Testing Strategy — E2E | Robot Framework E2E tests cover: plan lifecycle, correction, subplans, ACMS, invariants |
|
||||
| 16 | Code review tool examples in `examples/` directory | §Workflow Examples | `examples/code-review/` contains working action YAML and actor YAML |
|
||||
| 17 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
|
||||
|
||||
#### Key Architectural Constraints
|
||||
|
||||
- **ACP deprecation**: The `acp` module is deprecated; all new code uses `a2a`. The `acp` module may remain as a compatibility shim but must not be used in new implementations.
|
||||
- **LSP server lifecycle**: LSP servers start when actor activates and stop when actor deactivates; managed by `LSPRuntime`.
|
||||
- **Resource type inheritance depth**: Maximum chain depth of 5 levels; circular inheritance rejected at registration time.
|
||||
- **Devcontainer resource type**: `devcontainer-instance` inherits from `container-instance`; uses lazy activation pattern.
|
||||
- **Cloud resource stubs**: Cloud SDK integration is planned for v3.8.0+; stubs validate configuration but raise `NotImplementedError` for sandbox provisioning.
|
||||
|
||||
#### Definition of Done
|
||||
|
||||
- All 17 deliverables verified by automated tests
|
||||
- `nox` passes with coverage ≥ 97%
|
||||
- No open P0/P1 bugs in v3.6.0 milestone
|
||||
- LSP integration, resource type inheritance, devcontainer, and container execution all functional end-to-end
|
||||
|
||||
---
|
||||
|
||||
### v3.7.0 — TUI Implementation
|
||||
|
||||
**Goal**: Implement the comprehensive Text User Interface (TUI) and all TUI-dependent features using Textual ≥ 1.0.
|
||||
|
||||
**Spec Coverage**: [TUI Architecture](#tui), [Persona System](#persona-system), [Reference and Command System](#reference-and-command-system), [TUI Materializer](#tui-materializer)
|
||||
|
||||
**Key ADRs**: [ADR-044](adr/ADR-044-tui-architecture-and-framework.md), [ADR-045](adr/ADR-045-tui-persona-system.md), [ADR-046](adr/ADR-046-tui-reference-and-command-system.md)
|
||||
|
||||
#### Deliverables
|
||||
|
||||
| # | Deliverable | Spec Reference | Verifiable Check |
|
||||
|---|-------------|----------------|-----------------|
|
||||
| 1 | `agents tui` launches Textual-based MainScreen | §TUI — MainScreen | Command launches TUI; MainScreen renders without errors |
|
||||
| 2 | 3 sidebar states: hidden / visible / fullscreen | §TUI — Sidebar States | Keyboard shortcuts cycle through all 3 sidebar states |
|
||||
| 3 | Persona system: YAML-based actor + args + scope + presets | §Persona System | `agents persona add --config persona.yaml` creates persona; persona selectable in TUI |
|
||||
| 4 | Reference input system (`@` mode for resources/files) | §Reference and Command System — @ Mode | Typing `@` in input shows resource completion popup |
|
||||
| 5 | Command input system (`/` mode for commands) | §Reference and Command System — / Mode | Typing `/` in input shows command completion popup |
|
||||
| 6 | Shell execution mode (`!` mode) | §Reference and Command System — ! Mode | Typing `!` in input executes shell command; output shown in TUI |
|
||||
| 7 | `TuiMaterializer` A2A integration layer functional | §TUI Materializer | TUI operations route through A2A facade; same operations as CLI |
|
||||
| 8 | Session persistence in SQLite at `~/.local/state/cleveragents/tui.db` | §TUI — Session Persistence | TUI state persists across restarts; previous sessions resumable |
|
||||
| 9 | Dracula theme applied | §TUI — Theme | TUI renders with Dracula color scheme |
|
||||
| 10 | Block cursor navigation | §TUI — Navigation | Block cursor moves through interactive elements |
|
||||
| 11 | Notification system for async events | §TUI — Notifications | Plan phase changes trigger toast notifications |
|
||||
| 12 | Multi-session tabs with independent A2A bindings | §TUI — Multi-Session | Multiple tabs open simultaneously; each has independent session |
|
||||
| 13 | Settings screen functional | §TUI — Settings Screen | Settings screen opens; configuration changes persist |
|
||||
| 14 | Session management screen functional | §TUI — Session Management Screen | Session list shows all sessions; sessions can be created/deleted |
|
||||
| 15 | Content pruning for long conversations | §TUI — Content Pruning | Long conversations pruned to fit display; older messages summarized |
|
||||
| 16 | Safety behaviors: confirmation dialogs for destructive operations | §TUI — Safety Behaviors | Destructive operations (delete, apply) show confirmation dialog |
|
||||
| 17 | Loading states for async operations | §TUI — Loading States | Spinner shown during plan execution; progress updates streamed |
|
||||
| 18 | `agents tui web` launches Textual Web mode | §TUI — Web Mode | Web mode accessible via browser at configured port |
|
||||
| 19 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
|
||||
|
||||
#### Key Architectural Constraints
|
||||
|
||||
- **Textual version**: Textual ≥ 1.0 required; no compatibility with pre-1.0 API.
|
||||
- **TUI/CLI parity**: All operations available in CLI must be available in TUI via `TuiMaterializer`; no TUI-exclusive features.
|
||||
- **A2A routing**: TUI operations route through `A2aLocalFacade` in local mode; same A2A operations as CLI.
|
||||
- **Session database**: TUI session state stored in `~/.local/state/cleveragents/tui.db` (SQLite); separate from main `~/.local/share/cleveragents/data.db`.
|
||||
- **Persona scope**: Personas are scoped to TUI only; they are not visible to CLI or server mode.
|
||||
|
||||
#### Definition of Done
|
||||
|
||||
- All 19 deliverables verified by automated tests
|
||||
- `nox` passes with coverage ≥ 97%
|
||||
- No open P0/P1 bugs in v3.7.0 milestone
|
||||
- Full TUI functional end-to-end: launch, persona, reference/command input, multi-session, settings, session management
|
||||
|
||||
---
|
||||
|
||||
### v3.8.0 — Server Implementation
|
||||
|
||||
**Goal**: Implement the CleverAgents server and all server-dependent capabilities using the A2A (Agent-to-Agent) protocol standard. The server enables multi-device collaboration, shared namespaces, team RBAC, and cloud-hosted actor execution via LangGraph Platform.
|
||||
|
||||
**Spec Coverage**: [Server and Client Architecture](#server-and-client-architecture), [A2A Protocol](#agent-to-agent-protocol-a2a), [Authentication and Authorization](#authentication-and-authorization)
|
||||
|
||||
**Key ADRs**: [ADR-047](adr/ADR-047-acp-standard-adoption.md), [ADR-048](adr/ADR-048-server-application-architecture.md)
|
||||
|
||||
!!! note "Sequencing"
|
||||
v3.8.0 has no deadline. Development effort should focus on M1–M6 (v3.2.0–v3.7.0) first. v3.8.0 work may proceed in parallel but is not on the critical path for local-mode production readiness.
|
||||
|
||||
#### Deliverables
|
||||
|
||||
| # | Deliverable | Spec Reference | Verifiable Check |
|
||||
|---|-------------|----------------|-----------------|
|
||||
| 1 | A2A JSON-RPC 2.0 wire format: standard operations (`message/send`, `message/stream`, task lifecycle) | §Server and Client Architecture — Server Presentation Layer | `curl` to A2A endpoint returns valid JSON-RPC 2.0 response |
|
||||
| 2 | `_cleveragents/` extension method routing: plan lifecycle, registry CRUD, entity sync, namespace management | §Server and Client Architecture — Extension Methods | `_cleveragents/plan/use` creates a plan via server |
|
||||
| 3 | A2A stdio transport (local mode — agent as subprocess) | §A2A Protocol — Local Mode | `agents plan use` routes through A2A stdio transport in local mode |
|
||||
| 4 | A2A HTTP transport (server mode — single JSON-RPC endpoint) | §A2A Protocol — Server Mode | CLI connects to remote server via HTTP; all operations functional |
|
||||
| 5 | LangGraph Platform RemoteGraph integration for server-side actor execution | §Server Infrastructure — LangGraph Platform | Strategy and execution actors run on LangGraph Platform via RemoteGraph |
|
||||
| 6 | Server application structure: FastAPI + A2A SDK server | §Server Application Structure | Server starts, serves Agent Card at discovery endpoint |
|
||||
| 7 | API token authentication: `Authorization: Bearer <token>` header | §Authentication and Authorization — API Tokens | Requests without valid token return 401; valid token accepted |
|
||||
| 8 | Team RBAC: namespace-scoped read/write/admin permissions | §Authentication and Authorization — Team RBAC | User without write permission cannot create plans in restricted namespace |
|
||||
| 9 | Entity sync via `_cleveragents/sync/*` extension methods | §Entity Sync | `_cleveragents/sync/pull` fetches server entities to local registry |
|
||||
| 10 | Multi-device experience: shared namespaces accessible from any device | §Multi-Device Experience | Plan created on device A visible from device B via shared namespace |
|
||||
| 11 | Shared namespaces: team members access same actors, actions, projects | §Shared Namespaces | Actor in shared namespace usable by all team members |
|
||||
| 12 | PostgreSQL backend for server persistence | §Server Infrastructure — Persistence | Server stores plans, decisions, and registry data in PostgreSQL |
|
||||
| 13 | Server deployment: Docker container with `docker compose up` | §Server Deployment — Docker | `docker compose up` starts server; health check endpoint returns 200 |
|
||||
| 14 | Server deployment: Kubernetes Helm chart | §Server Deployment — Kubernetes | `helm install cleveragents ./charts/cleveragents` deploys to cluster |
|
||||
| 15 | `agents server add` registers a remote server in local config | §CLI Commands — server | Round-trip: add server, list shows it, CLI connects to it |
|
||||
| 16 | `agents server status` shows server health and version | §CLI Commands — server status | Command exits 0, shows server version and uptime |
|
||||
| 17 | Multi-turn interactions forwarded to client: `_cleveragents/fs/*`, `_cleveragents/terminal/*` | §Server Presentation Layer — Multi-Turn | Server-hosted actor can read client-local files via forwarded fs operations |
|
||||
| 18 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
|
||||
|
||||
#### Key Architectural Constraints
|
||||
|
||||
- **A2A exclusivity**: The server exposes **only** an A2A JSON-RPC 2.0 endpoint. No REST API, no GraphQL, no admin endpoint.
|
||||
- **Shared domain/application layers**: Server and client share identical Domain and Application layer packages. Zero behavioral drift between local and server modes.
|
||||
- **LangGraph Platform**: Actor graphs are deployed to LangGraph Platform as separate deployments; server invokes them via RemoteGraph. The server does NOT run actor graphs in-process.
|
||||
- **PostgreSQL schema**: Server uses the same schema as the SQLite client database, with PostgreSQL-specific extensions for multi-tenancy (namespace isolation, team membership).
|
||||
- **Authentication boundary**: All A2A requests require a valid API token. Tokens are scoped to a namespace; team RBAC controls per-namespace permissions.
|
||||
- **Extension method routing**: `_cleveragents/` methods are routed to Application-layer services. Standard A2A operations (`message/send`, etc.) are routed to `SessionWorkflow` and actor execution.
|
||||
- **Multi-turn forwarding**: When a server-hosted actor needs client-local resources (files, terminal), it sends a `_cleveragents/fs/*` or `_cleveragents/terminal/*` request back to the connected client via the A2A task `input-required` mechanism.
|
||||
|
||||
#### Definition of Done
|
||||
|
||||
- All 18 deliverables verified by automated tests
|
||||
- `nox` passes with coverage ≥ 97%
|
||||
- No open P0/P1 bugs in v3.8.0 milestone
|
||||
- Server starts, accepts A2A connections, executes plans via LangGraph Platform, and persists to PostgreSQL
|
||||
- CLI connects to remote server; all plan lifecycle operations functional in server mode
|
||||
|
||||
---
|
||||
|
||||
### Cross-Milestone Quality Gates
|
||||
|
||||
These quality gates apply to **every milestone** and must pass before a milestone is considered complete:
|
||||
|
||||
| Gate | Requirement | Command |
|
||||
|------|-------------|---------|
|
||||
| **Unit Tests** | All BDD Behave scenarios pass | `nox -s unit_tests` |
|
||||
| **Integration Tests** | All Robot Framework tests pass | `nox -s integration_tests` |
|
||||
| **Type Checking** | Zero Pyright errors (strict mode) | `nox -s typecheck` |
|
||||
| **Linting** | Zero Ruff violations | `nox -s lint` |
|
||||
| **Coverage** | ≥ 97% line coverage | `nox -s coverage_report` |
|
||||
| **Security Scan** | No high/critical Bandit findings | `nox -s security_scan` |
|
||||
| **Performance** | No ASV benchmark regressions > 10% | `nox -s benchmarks` |
|
||||
| **Documentation** | All public APIs documented | `nox -s docs` |
|
||||
|
||||
### Cross-Milestone Architectural Invariants
|
||||
|
||||
These architectural invariants must be maintained across all milestones:
|
||||
|
||||
1. **Spec-first**: No feature is implemented without spec coverage. If implementation discovers a better approach, the spec is updated first via PR.
|
||||
2. **Layer boundaries**: Presentation → Application → Domain → Infrastructure. No reverse dependencies.
|
||||
3. **Type safety**: Full Pyright strict compliance. No `# type: ignore` suppressions.
|
||||
4. **Fail-fast**: All argument validation at entry points. No silent failures.
|
||||
5. **ULID identifiers**: Plans, decisions, resources, correction attempts, and validation attachments use ULIDs. Projects, actions, skills, and tools use namespaced names.
|
||||
6. **Namespace format**: `[[server:]namespace/]name`. `local/` reserved for local-only items.
|
||||
7. **A2A exclusivity**: All client-server communication uses A2A. No REST API.
|
||||
8. **BDD tests**: All unit-level tests expressed as Behave/Gherkin scenarios. No xUnit-style tests.
|
||||
9. **File size limit**: No source file exceeds 500 lines. Split into modules if approaching limit.
|
||||
10. **Atomic commits**: One logical change per commit. No mixed concerns.
|
||||
@@ -0,0 +1,197 @@
|
||||
# CleverAgents Documentation (Detailed Spec)
|
||||
|
||||
## Overview
|
||||
|
||||
CleverAgents is your **command center for AI agents** — a unified platform for orchestrating any task you want agents to accomplish, from developing large software projects to writing comprehensive technical papers, administering databases, managing cloud infrastructure, or any complex multi-step workflow.
|
||||
|
||||
The core value proposition is enabling long-running, complex, large-scale tasks to execute autonomously with minimal human intervention, making it ideal for building entire software systems, producing extensive documentation, or managing sophisticated operations largely hands-off.
|
||||
|
||||
!!! info "Server Mode"
|
||||
|
||||
In **server mode**, CleverAgents becomes a collaborative hub where teams can share resources — prompts, actors, actions, and projects — while executing plans in the cloud. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine.
|
||||
|
||||
!!! note "Runtime Foundation"
|
||||
|
||||
While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top of these foundations.
|
||||
|
||||
!!! success "Core Capabilities"
|
||||
|
||||
- [x] A **first-class plan lifecycle** (Action templates driving Strategize / Execute / Apply phases) for breaking down and tracking complex work
|
||||
- [x] A **project + resource model** for grounding tasks in real codebases, databases, documents, and infrastructure
|
||||
- [x] A consistent **actor abstraction** for defining and composing intelligent agents
|
||||
- [x] An independently registered **resource abstraction** for representing anything that can be read, written, or queried
|
||||
- [x] An independently registered **tool abstraction** for reusable, callable operations with resource bindings
|
||||
- [x] A **validation abstraction** that extends the tool concept with pass/fail semantics and resource-centric attachment with optional project/plan scoping
|
||||
- [x] A consistent **skill abstraction** for organizing tools into composable capability collections
|
||||
- [x] A **sandbox + checkpoint** safety model for safe, reversible execution
|
||||
- [x] A **CLI/TUI/Web UX** for controlling and monitoring large multi-step autonomous work
|
||||
|
||||
!!! example "Advanced Subsystems"
|
||||
|
||||
- A scalable **Advanced Context Management System (ACMS)** with a Universal Knowledge Ontology (UKO), a demand-driven Context Request Protocol (CRP), pluggable context strategies, a fusion coordinator, and hot/warm/cold tiers with per-actor views.
|
||||
- **Invariants** as first-class constraints (global, project, action, and plan scoped) that flow into the decision tree, with precedence-based conflict resolution via the Invariant Reconciliation Actor.
|
||||
- A future-facing ==correction model== where the user can "edit the decision tree" and only recompute affected subtrees.
|
||||
|
||||
### Standards Alignment
|
||||
|
||||
CleverAgents deliberately adopts open, versioned protocols wherever possible so that clients, tools, and skills can interoperate without bespoke integrations.
|
||||
|
||||
!!! tip "Guiding Principles"
|
||||
|
||||
1. **Prefer open protocols** — align with community standards to keep integrations portable and reduce vendor lock-in.
|
||||
2. **Keep adapters at the edge** — standards map into stable internal domain models so core logic remains protocol-agnostic.
|
||||
|
||||
The following standards are integrated into the architecture:
|
||||
|
||||
| Standard | Role | Key Benefit |
|
||||
| :------- | :--- | :---------- |
|
||||
| **A2A** (Agent-to-Agent Protocol) | Versioned client-server contract for messaging, task lifecycle, plan management, registry access, and event streaming | Clients are interchangeable; Agent Card discovery enables ecosystem interoperability; reliable remote execution in server mode |
|
||||
| **MCP** (Model Context Protocol) | Discovering and invoking external tools over a server boundary | Plug-and-play access to a growing ecosystem of tool providers |
|
||||
| **LSP** (Language Server Protocol) | Attaching language intelligence (diagnostics, type info, symbol navigation, completions) to actors and agents | Actors gain semantic code understanding from the mature LSP ecosystem without bespoke language analysis |
|
||||
| **Agent Skills** ([AgentSkills.io](https://AgentSkills.io)) | Packaging instruction-driven, multi-step workflows as `SKILL.md` with progressive disclosure | Teaches agents *how* to accomplish complex tasks, complementing MCP tools |
|
||||
|
||||
??? info "Agent-to-Agent Protocol (A2A) -- Details"
|
||||
|
||||
CleverAgents adopts the external **Agent-to-Agent (A2A) Protocol** standard ([a2a-protocol.org](https://a2a-protocol.org)) as the **sole** communication protocol for all client-server interaction. A2A is the successor to the Agent Client Protocol (ACP), which is now deprecated; A2A retains backward compatibility with ACP's JSON-RPC 2.0 foundation. A2A is built on **JSON-RPC 2.0** (with additional gRPC and REST bindings available) and defines the **fundamental boundary between the Presentation and Application layers** — every client operation flows through A2A regardless of deployment mode. The standard provides operations for messaging (`message/send`, `message/stream`), task lifecycle management, streaming updates via SSE, and **Agent Card**-based capability discovery. CleverAgents extends the standard with `_cleveragents/`-prefixed extension methods (declared via the A2A extension mechanism) for platform operations: plan lifecycle, registry CRUD, entity sync, namespace management, and diagnostics. In local mode, A2A flows over **stdio** via the JSON-RPC binding (agent as subprocess) with platform operations resolved in-process via `A2aLocalFacade`. In server mode, A2A flows over **HTTP** to the CleverAgents server. Both transports use the A2A Python SDK. All clients — CLI, TUI, IDE plugin, and third-party — communicate exclusively through A2A. See [ADR-047](adr/ADR-047-acp-standard-adoption.md), [ADR-048](adr/ADR-048-server-application-architecture.md), and [Server and Client Architecture](#server-and-client-architecture) for the full detail.
|
||||
|
||||
??? info "Model Context Protocol (MCP) -- Details"
|
||||
|
||||
The standard for discovering and invoking external tools over a server boundary. MCP servers are bridged into the Tool Registry via adapters, giving CleverAgents plug-and-play access to a growing ecosystem of tool providers.
|
||||
|
||||
??? info "Language Server Protocol (LSP) -- Details"
|
||||
|
||||
The standard for attaching language intelligence to actors and agents. LSP servers are registered in a global LSP Registry (namespaced like all other entities) and bound to actor graph nodes via YAML configuration. When an actor activates, the LSP Runtime starts the appropriate language servers for the actor's bound languages and workspace resources. LSP capabilities — diagnostics, type information, symbol navigation, completions, references, rename, code actions, and more — are exposed to the actor as callable tools (via the `LSPToolAdapter`) and as automatic context enrichment (diagnostics and type annotations injected into the ACMS hot context). Actors can bind LSP servers explicitly by name, by language, or automatically based on the languages detected in their project's resources. Different nodes in an actor's graph can have different LSP bindings, enabling fine-grained control over which agents receive which language intelligence capabilities. See [LSP Integration](#lsp-integration) for the full architectural detail and [ADR-027](adr/ADR-027-language-server-protocol.md) for the decision record.
|
||||
|
||||
??? info "Agent Skills (AgentSkills.io) -- Details"
|
||||
|
||||
The standard for packaging instruction-driven, multi-step workflows as `SKILL.md` with progressive disclosure. Agent Skills complement MCP tools by teaching agents *how* to accomplish complex tasks rather than simply exposing callable functions.
|
||||
|
||||
## Glossary
|
||||
|
||||
???+ abstract "Plan Lifecycle"
|
||||
|
||||
Plan
|
||||
: A ==ULID-identified==, hierarchical unit of work instantiated from an Action template. Progresses through four phases — **Action**, **Strategize**, **Execute**, **Apply** — persisting a decision tree at each step. May spawn child plans. Scoped to one or more projects. Top-level plans carry a namespaced name (`[[server:]namespace/]name`); child plans are identified solely by their plan ID (ULID). All plans are referenced by plan ID when precision is needed, especially in hierarchies containing subplans.
|
||||
|
||||
Action
|
||||
: A YAML-defined, reusable plan template specifying a description, definition of done, strategy/execution actors, typed arguments, and optional invariants. Project-agnostic until bound to one or more projects via `agents plan use`, which instantiates a Plan. Namespaced as `[[server:]namespace/]name`.
|
||||
|
||||
Strategize
|
||||
: Second phase of the plan lifecycle (following the Action phase). The first phase where active processing occurs. ==Read-only==: the strategy actor produces the initial decision tree — strategy choices, invariant enforcement records, resource selections, child plan blueprints — without modifying any resources.
|
||||
|
||||
Execute
|
||||
: Third phase of the plan lifecycle. The execution actor carries out decisions from Strategize — invoking tools, spawning child plans, producing artifacts, creating checkpoints — with all mutations confined to a sandbox. May also create additional decisions constrained by Strategize-phase decisions, based on runtime discoveries.
|
||||
|
||||
Apply
|
||||
: Fourth and final phase of the plan lifecycle. Merges the sandbox changeset into real project resources. Terminal states: `applied` (success), `constrained` (cannot complete — may revert to Strategize), `errored` (failed), `cancelled` (user/system cancelled).
|
||||
|
||||
Decision
|
||||
: A persisted choice point in a plan's decision tree, created during Strategize or Execute. Records the question, chosen option, alternatives, confidence score, rationale, context snapshot, and downstream dependencies. Types: `prompt_definition`, `invariant_enforced`, `strategy_choice`, `subplan_spawn`, `subplan_parallel_spawn`, among others. Supports targeted correction with selective subtree recomputation.
|
||||
|
||||
Invariant
|
||||
: A natural-language constraint on plan execution scoped to global, project, action, or plan level. The runtime precedence chain is four-tier: ==plan > action > project > global==. Exception: global invariants marked `non_overridable` always win regardless of scope. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans.
|
||||
|
||||
Automation Profile
|
||||
: A named set of confidence thresholds (each `0.0`–`1.0`) gating which plan operations proceed automatically versus requiring human approval. `0.0` = always automatic; `1.0` = always manual. Eight built-in profiles (`manual` through `full-auto`). Custom profiles namespaced as `[[server:]namespace/]name`. Each profile composes a **Safety Profile** that controls hard safety constraints (sandbox, checkpoint, unsafe-tool gating, skill restrictions, cost/retry limits).
|
||||
|
||||
Safety Profile
|
||||
: A composed sub-model of an Automation Profile that groups all hard safety constraints: `require_sandbox`, `require_checkpoints`, `allow_unsafe_tools`, `require_human_approval`, `allowed_skill_categories`, `max_cost_per_plan`, `max_retries_per_step`, and `max_total_cost`. Safety profiles can also be referenced standalone on Actions when only safety constraints (without full autonomy thresholds) are needed. See [ADR-041](adr/ADR-041-safety-profile-extraction.md).
|
||||
|
||||
???+ abstract "Projects & Resources"
|
||||
|
||||
Project
|
||||
: A named scope linking resources (from the Resource Registry), context policies, invariants, and validation attachments. Does not own resources; a single resource may be linked to multiple projects. Identified solely by its namespaced name (`[[server:]namespace/]name`) — no ULID is generated. May be local or remote.
|
||||
|
||||
Resource
|
||||
: A ULID-identified entity registered in the Resource Registry representing anything readable, writable, or queryable (git repos, filesystems, databases, etc.). Classified as physical or virtual, typed by a Resource Type, and organized in a DAG via parent/child links.
|
||||
|
||||
Resource Type
|
||||
: A schema-level definition constraining a category of resources. Specifies accepted CLI arguments, physical/virtual classification, permitted parent/child type relationships, auto-discovery rules, sandbox strategy, and handler implementation. Built-in types (e.g., `git-checkout`, `fs-mount`) are unnamespaced; custom types are namespaced as `[[server:]namespace/]name`. Resource types support single inheritance via the `inherits` field — see [ADR-042](adr/ADR-042-resource-type-inheritance.md).
|
||||
|
||||
Resource Type Inheritance
|
||||
: A mechanism allowing one resource type to inherit properties, capabilities, child types, sandbox strategy, and handler behavior from another type via the `inherits` field in the type definition. Subtypes can selectively override or extend any inherited field. Tools bound to a parent type automatically work with all subtypes (polymorphic matching). Auto-discovery child type matching and DAG queries are also polymorphic. Single inheritance only; maximum chain depth of 5 levels. See [ADR-042](adr/ADR-042-resource-type-inheritance.md).
|
||||
|
||||
Devcontainer
|
||||
: A container execution environment defined by a `.devcontainer/devcontainer.json` configuration file per the [Development Containers Specification](https://containers.dev). Auto-discovered when a `git-checkout` or `fs-directory` resource contains a `.devcontainer/` directory. Represented as a `devcontainer-instance` resource type that inherits from `container-instance`. Uses lazy activation — the container is only built when first needed by a plan. See [ADR-043](adr/ADR-043-devcontainer-integration.md).
|
||||
|
||||
Execution Environment
|
||||
: The runtime context in which tools execute — either the host system or a specific container. Configurable at project scope (`execution_environment` preference), plan scope (`--execution-environment` flag), and resource scope (auto-detected devcontainers). Precedence resolution determines which environment is used when multiple are configured, with `priority: override` forcing a specific container and `priority: fallback` deferring to auto-detected devcontainers. See [ADR-043](adr/ADR-043-devcontainer-integration.md).
|
||||
|
||||
Physical Resource
|
||||
: A resource bound to a concrete, located artifact — a specific file at a specific path, a specific repo at a specific URL. Directly readable and writable by tools. Two physical resources with identical content remain distinct instances.
|
||||
|
||||
Virtual Resource
|
||||
: A resource representing an abstract equivalence identity that links physical resources sharing the same content, hash, or name. ==Has no location; cannot be directly read or written.== Equivalence relationships update when underlying physical resources diverge.
|
||||
|
||||
Resource Binding
|
||||
: The association between a tool and the resources it operates on, declared via typed resource slots. Slots resolve through **contextual binding** (from the plan's project), **static binding** (hardcoded at registration), or **parameter binding** (passed at invocation).
|
||||
|
||||
Resource Registry
|
||||
: The persistent catalog of all registered resources and their DAG relationships (parent/child links). One of the core registries, alongside the Tool Registry, Skill Registry, Actor Registry, Provider Registry, and LSP Registry.
|
||||
|
||||
???+ abstract "Tools & Skills"
|
||||
|
||||
Tool
|
||||
: The ==atomic unit of execution==: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`). Sources: MCP servers, Agent Skills folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`.
|
||||
|
||||
Validation
|
||||
: A Tool subtype adding: a `mode` (`required` | `informational`) controlling whether failure blocks execution; a structured JSON return with mandatory `passed` boolean, optional `data`, and optional `message`. ==Always read-only== (`writes = false`, `checkpointable = false`). May wrap an existing Tool via `wraps` + `transform`. Managed via `agents validation add/attach/detach`; always attached to a resource, optionally scoped to a project or plan.
|
||||
|
||||
Anonymous Tool
|
||||
: An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered, unnamespaced, and scoped only to its defining context.
|
||||
|
||||
Skill
|
||||
: A composable, namespaced collection of tools assembled by referencing named tools, defining inline anonymous tools, including other skills, or exposing MCP server tools and Agent Skills ([AgentSkills.io](https://AgentSkills.io)) tools. Actors reference skills by name to acquire capabilities. Namespaced as `[[server:]namespace/]name`.
|
||||
|
||||
MCP (Model Context Protocol)
|
||||
: A standard for exposing tools and resources over a server boundary via JSON-RPC. CleverAgents discovers MCP tools through the `MCPToolAdapter` and registers them in the Tool Registry with extended capability metadata. MCP tools can be composed into skills and used as tool nodes in actor graphs.
|
||||
|
||||
Agent Skills ([AgentSkills.io](https://AgentSkills.io))
|
||||
: A standard for packaging instruction-driven, multi-step workflows as `SKILL.md` files with optional `scripts/`, `references/`, and `assets/` directories, using progressive disclosure. Surfaced as tools inside skills and loaded on demand by the actor runtime.
|
||||
|
||||
???+ abstract "Actors & Sessions"
|
||||
|
||||
Actor
|
||||
: A YAML-configured conversational unit — either a single LLM/agent or a composed LangGraph of actors and tool nodes. Specialized roles: strategy actor, execution actor, estimation actor, invariant reconciliation actor. Namespaced as `[[server:]namespace/]name`.
|
||||
|
||||
Session
|
||||
: A persistent conversation thread tied to an orchestrator actor. Maintains message history across plans and serves as the user's natural-language interface.
|
||||
|
||||
Server
|
||||
: An optional shared backend providing multi-user storage, namespace resolution, and remote plan execution.
|
||||
|
||||
???+ abstract "Protocols & Standards"
|
||||
|
||||
A2A (Agent-to-Agent Protocol)
|
||||
: The external **Agent-to-Agent (A2A) Protocol** standard ([a2a-protocol.org](https://a2a-protocol.org)), built on **JSON-RPC 2.0** (with gRPC and REST bindings available), used as the **sole** communication protocol for all client-server interaction. A2A is the successor to the Agent Client Protocol (ACP), which is now deprecated; A2A retains backward compatibility with ACP's JSON-RPC 2.0 foundation. A2A defines the **fundamental boundary between the Presentation and Application layers**. Standard A2A operations handle agent messaging (`message/send`, `message/stream`), task lifecycle, streaming updates, and Agent Card-based discovery. CleverAgents `_cleveragents/`-prefixed extension methods handle platform operations (plan lifecycle, registry CRUD, entity sync, namespace management, diagnostics). In local mode A2A flows over stdio via JSON-RPC (agent as subprocess); in server mode over HTTP. Every CLI command maps to an A2A operation. See [Core Concepts > Server > A2A](#agent-to-agent-protocol-a2a) and [Server and Client Architecture](#server-and-client-architecture) for full detail.
|
||||
|
||||
LSP (Language Server Protocol)
|
||||
: A standard protocol for language intelligence, used in CleverAgents to attach semantic code understanding to actors and agents. LSP servers are registered in the global **LSP Registry** (namespaced as `[[server:]namespace/]name`) and bound to actor graph nodes via YAML configuration. Capabilities — diagnostics, type information, symbol navigation, completions, references, rename, code actions — are exposed as tools (via `LSPToolAdapter`) and as automatic context enrichment. Actors can bind LSP servers explicitly by name, by language, or automatically based on detected resource languages. The LSP Runtime in the Infrastructure layer manages server lifecycle, workspace mapping, and file synchronization. See [LSP Integration](#lsp-integration) for full detail.
|
||||
|
||||
???+ abstract "Naming & Identity"
|
||||
|
||||
Namespace
|
||||
: The scoping segment in the name format `[[server:]namespace/]name`. Defaults to `local/` when omitted. `local/` is reserved for local-only items. Non-`local/` namespaces with server omitted assume the default configured server. Built-in LLM actors use provider prefixes (e.g., `openai/`, `anthropic/`). Built-in resource types are unnamespaced.
|
||||
|
||||
ULID
|
||||
: ==Universally Unique Lexicographically Sortable Identifier.== Assigned to plans, decisions, resources, correction attempts, and validation attachments. Projects, actions, skills, and tools use their namespaced name as sole identifier instead.
|
||||
|
||||
???+ abstract "Context Management (ACMS)"
|
||||
|
||||
ACMS (Advanced Context Management System)
|
||||
: The pluggable, strategy-driven framework for assembling actor context. Comprises the UKO, CRP, pluggable context strategies, the Context Assembly Pipeline, and hot/warm/cold tiered storage with per-actor scoped views.
|
||||
|
||||
UKO (Universal Knowledge Ontology)
|
||||
: An RDF-based, inheritance-driven ontology representing resources at multiple abstraction levels with provenance and temporal versioning. Four layers: universal foundation, domain specializations (software, documents, data schemas, infrastructure), paradigm/format specializations (procedural programming, markdown), and technology-specific (Python, PostgreSQL). ==Semantically aware — implicit relationships are inferred from content analysis.==
|
||||
|
||||
CRP (Context Request Protocol)
|
||||
: A structured vocabulary through which actors declare needed information, desired detail depth, and scope.
|
||||
|
||||
Context Strategy
|
||||
: A pluggable retrieval component that searches for and assembles ContextFragments using a specific approach (keyword search, semantic embedding, graph navigation, temporal archaeology, etc.). Registered with the Context Assembly Pipeline; executed in parallel by the StrategyExecutor.
|
||||
|
||||
Context Assembly Pipeline
|
||||
: The central ACMS orchestrator. Ten pluggable Protocol-defined components in three phases: **Strategy Orchestration**, **Fragment Fusion**, and **Context Finalization**. Each component ships with a default implementation and is overridable at global, project, or plan scope.
|
||||
|
||||
Skeleton (context)
|
||||
: A compressed representation of a plan's accumulated context produced by the SkeletonCompressor. Propagated from parent plans to child plans as inherited context. Size governed by the `skeleton_ratio` budget parameter.
|
||||
File diff suppressed because it is too large
Load Diff
+12
-1
@@ -9,7 +9,18 @@ site_url: https://docs.cleverthis.com/cleveragents
|
||||
site_dir: build/site
|
||||
|
||||
nav:
|
||||
- Specification: specification.md
|
||||
- Specification:
|
||||
- Index: specification/index.md
|
||||
- Overview & Glossary: specification/overview.md
|
||||
- CLI Commands: specification/cli.md
|
||||
- Core Concepts: specification/core-concepts.md
|
||||
- Behavior: specification/behavior.md
|
||||
- TUI: specification/tui.md
|
||||
- Configuration: specification/configuration.md
|
||||
- Workflow Examples: specification/examples.md
|
||||
- Architecture: specification/architecture.md
|
||||
- Milestone Plan: specification/milestones.md
|
||||
- ACMS v1: specification/acms.md
|
||||
- Architecture: architecture.md
|
||||
- API Reference:
|
||||
- Overview: api/index.md
|
||||
|
||||
Reference in New Issue
Block a user