From 9b95a18b7b5f6f72e43f24895a9ebb28bea9e076 Mon Sep 17 00:00:00 2001 From: David Hagerty Date: Fri, 13 Feb 2026 10:09:18 -0500 Subject: [PATCH] docs: update project context for V2 Phase 5 changes Reflect new autonomy module, CodeSearchTool, budget-aware context builder, orchestrator error recovery, and SecurityScope enforcement methods. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 10 ++++++---- src/agent/AGENTS.md | 17 ++++++++++------- src/context/AGENTS.md | 30 ++++++++++++++++++++++++++++++ src/context/CLAUDE.md | 1 + 4 files changed, 47 insertions(+), 11 deletions(-) create mode 100644 src/context/AGENTS.md create mode 100644 src/context/CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 7c3ac1c..9d818bf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Rustagent -Last verified: 2026-02-11 +Last verified: 2026-02-13 ## Project Overview @@ -62,6 +62,7 @@ src/ ├── config.rs # Configuration loading with env var substitution ├── logging.rs # File-based tracing with daily rotation ├── spec.rs # V1 specification data structures +├── autonomy.rs # AutonomyLevel, ApprovalGate, GateChecker for human-in-the-loop control ├── project.rs # Project type and ProjectStore (CRUD over SQLite) ├── db/ # Database layer (SQLite + WAL mode) │ ├── mod.rs # Database wrapper with async access @@ -80,8 +81,8 @@ src/ │ ├── builtin_profiles.rs # 5 built-in profiles: planner, coder, reviewer, tester, researcher │ └── runtime.rs # AgentRuntime: agentic loop with token budget and failure thresholds ├── context/ # Context building for agent prompts -│ ├── mod.rs # ContextBuilder + ReadAgentsMdTool -│ └── agents_md.rs # AGENTS.md file discovery and heading extraction +│ ├── mod.rs # ContextBuilder (plain + budget-aware) + ReadAgentsMdTool +│ └── agents_md.rs # AGENTS.md file discovery with heading + line count extraction ├── llm/ # LLM provider abstraction │ ├── mod.rs # LlmClient trait, Message, Response (with token tracking) │ ├── anthropic.rs # Anthropic (Claude) client @@ -96,13 +97,14 @@ src/ ├── security/ │ ├── mod.rs # SecurityValidator for paths/commands │ ├── permission.rs # Permission handling (CLI prompts) -│ └── scope.rs # SecurityScope: per-agent path/command/network restrictions +│ └── scope.rs # SecurityScope with check_path/check_command/check_network (glob-based) └── tools/ ├── mod.rs # Tool trait and ToolRegistry ├── factory.rs # create_default_registry + create_v2_registry ├── graph_tools.rs # 11 graph tools for agents (create, update, query, claim, etc.) ├── file.rs # read_file, write_file, list_files ├── shell.rs # run_command + ├── search.rs # CodeSearchTool: regex search over project files with glob filtering ├── signal.rs # signal_completion └── permission_check.rs # File permission checking ``` diff --git a/src/agent/AGENTS.md b/src/agent/AGENTS.md index 9443937..3a9b257 100644 --- a/src/agent/AGENTS.md +++ b/src/agent/AGENTS.md @@ -1,18 +1,18 @@ # Agent Module -Last verified: 2026-02-09 +Last verified: 2026-02-13 ## Purpose Defines the agent abstraction and runtime loop for autonomous task execution. Agents are configured via profiles that control their role, allowed tools, security scope, LLM settings, and resource budgets. ## Contracts -- **Exposes**: `Agent` trait, `AgentProfile`, `AgentContext`, `AgentOutcome`, `AgentRuntime`, `resolve_profile()`, 5 built-in profiles -- **Guarantees**: Runtime stops on token budget exhaustion (returns `TokenBudgetExhausted`). Consecutive LLM/tool failures trigger `Blocked` outcome (configurable thresholds). Profile inheritance detects cycles. `signal_completion` tool ends the loop cleanly. -- **Expects**: An `Arc`, a `ToolRegistry`, and an `AgentContext` with work package tasks and graph store access. +- **Exposes**: `Agent` trait, `AgentProfile`, `AgentContext`, `AgentOutcome`, `AgentRuntime`, `resolve_profile()`, 5 built-in profiles, `Orchestrator` (multi-agent coordinator) +- **Guarantees**: Runtime stops on token budget exhaustion (returns `TokenBudgetExhausted`). Consecutive LLM/tool failures trigger `Blocked` outcome (configurable thresholds). Profile inheritance detects cycles. `signal_completion` tool ends the loop cleanly. Orchestrator retries failed tasks with previous error context injected. Failed tasks cascade-block dependents; successful retries auto-unblock them. +- **Expects**: An `Arc`, a `ToolRegistry`, and an `AgentContext` with work package tasks, graph store access, and optional `previous_attempt`/`dependency_statuses` fields. ## Dependencies -- **Uses**: `llm::LlmClient`, `tools::ToolRegistry`, `context::ContextBuilder`, `graph::GraphNode`, `graph::store::GraphStore`, `security::SecurityScope` -- **Used by**: `main.rs` (V2 `run` command wires up the runtime) +- **Uses**: `llm::LlmClient`, `tools::ToolRegistry`, `context::ContextBuilder` (budget-aware), `graph::GraphNode`, `graph::store::GraphStore`, `security::SecurityScope` +- **Used by**: `main.rs` (V2 `run` command wires up the runtime), orchestrator coordinates multi-agent execution - **Boundary**: Does NOT directly access the database; uses `GraphStore` trait ## Key Decisions @@ -20,14 +20,17 @@ Defines the agent abstraction and runtime loop for autonomous task execution. Ag - Inheritance via `extends`: system_prompt appends (child after parent), lists replace, optionals fall through - SecurityScope per profile: Each agent type has explicit path/command/network restrictions - Confusion counter pattern: Consecutive failures tracked separately for LLM and tool errors +- Error recovery: On task failure, orchestrator stores error in `metadata["previous_attempt"]` and increments `retry_count`; on retry the error context is injected into the agent's system prompt ## Invariants - AgentOutcome is always returned (never panics): Completed, Blocked, Failed, or TokenBudgetExhausted - Token budget warning fires at 80% (configurable), hard stop at 100% - Built-in profiles: planner (read-only, graph-only), coder (file+shell+graph), reviewer (read-only), tester (file+shell+graph), researcher (read-only) +- Failed tasks cascade-block dependents via `metadata["blocker_task_id"]`; unblock checks use this key (not string parsing) ## Key Files -- `mod.rs` - Agent trait, AgentId, AgentContext, AgentOutcome enum +- `mod.rs` - Agent trait, AgentId, AgentContext (incl. previous_attempt, dependency_statuses), AgentOutcome enum - `profile.rs` - AgentProfile struct, ProfileLlmConfig, resolve_profile() with cycle detection - `builtin_profiles.rs` - planner(), coder(), reviewer(), tester(), researcher() - `runtime.rs` - AgentRuntime, RuntimeConfig (defaults: 100 turns, 200k tokens, 3 failure threshold) +- `orchestrator.rs` - Orchestrator: scheduling, work packages, error recovery (retry/cascade/unblock) diff --git a/src/context/AGENTS.md b/src/context/AGENTS.md new file mode 100644 index 0000000..8a43b91 --- /dev/null +++ b/src/context/AGENTS.md @@ -0,0 +1,30 @@ +# Context Module + +Last verified: 2026-02-13 + +## Purpose +Assembles structured system prompts for agents from their AgentContext. Handles token budget management to prioritize critical information (role, tasks, rules) over optional context (sessions, decisions, conventions) when prompts are too large. + +## Contracts +- **Exposes**: `ContextBuilder` (plain + budget-aware), `ContextBudget` (default: 4000 tokens), `ReadAgentsMdTool`, `resolve_agents_md()` +- **Guarantees**: Required sections (Role, Task, Dependencies, Previous Attempt, Rules) are never trimmed. Optional sections are dropped in priority order when over budget: Session Continuity > Active Decisions > Observations > Project Conventions (lowest). Token estimate uses 1 token per 4 chars. `ReadAgentsMdTool` only reads AGENTS.md files (rejects other filenames). `resolve_agents_md` returns relative paths with heading line counts. +- **Expects**: A populated `AgentContext`. `ReadAgentsMdTool` needs a valid project path or AGENTS.md file path. + +## Dependencies +- **Uses**: `agent::AgentContext`, `graph::GraphNode`, `tools::Tool` trait +- **Used by**: `agent::runtime` (builds system prompt each run), `tools::factory` (registers ReadAgentsMdTool) +- **Boundary**: Does NOT access the database or LLM directly + +## Key Decisions +- Budget-aware assembly: Required sections always included; optional sections trimmed by priority when over budget +- Token estimation at 4 chars/token: Simple heuristic avoids tokenizer dependency +- ReadAgentsMdTool accepts directory paths: Agents can pass `src/auth` instead of `src/auth/AGENTS.md` + +## Invariants +- `build_system_prompt_with_budget` always includes Role, Task, Dependencies, Previous Attempt, and Rules sections +- `resolve_agents_md` walks from file's directory up to project root, deduplicating paths +- AGENTS.md heading summaries include line counts: `"Section Name (N lines)"` + +## Key Files +- `mod.rs` - ContextBuilder, ContextBudget, ReadAgentsMdTool +- `agents_md.rs` - resolve_agents_md(), extract_heading_summaries() diff --git a/src/context/CLAUDE.md b/src/context/CLAUDE.md new file mode 100644 index 0000000..f66a6ac --- /dev/null +++ b/src/context/CLAUDE.md @@ -0,0 +1 @@ +Read @./AGENTS.md and treat its contents as if they were in CLAUDE.md -- 2.51.2