⚙️ FEATURE: Repository graph context injection — AST and call-graph summary before loop start

[FernandoCelmer]

Problem

When the agent starts on a large codebase, its first several tool calls are typically exploratory: listing files, reading entry points, mapping imports. These turns consume tokens and time before any real work begins. Research papers (CodePlan, LocAgent, RPG) show that injecting a structural index of the repository upfront — file dependency graph, public API surface, key entry points — dramatically improves first-turn accuracy on multi-file tasks.

Context

Structure-Grounded Planning patterns from the "Code as Agent Harness" literature demonstrate that agents with a pre-built code graph context require fewer exploratory tool calls and make fewer out-of-scope file edits.

Expected behavior

codeloop = CodeLoop(config=Config(
    repo_context=True,         # build structural index before first turn
    repo_context_max_tokens=2000,  # cap injected summary size
))

What gets injected into the system prompt (before the user's message):

# Repository structure
Entry points: src/main.py, src/cli.py
Modules: auth (src/auth/), storage (src/store/), tools (src/tools/)
Public API surface: CodeLoop, Config, Agent, GenericProvider
Key imports: pycodeloop → [auth, store, tools, providers]

Suggested implementation

• Add build_repo_context(workspace: str, max_tokens: int) -> str in pycodeloop/core/repo_context.py
• Uses ast.parse() on Python files to extract: module names, public classes/functions, import graph
• Builds a compact text summary (no full source, just structure)
• Add repo_context: bool = False, repo_context_max_tokens: int = 2000 to Config
• Wire into CodeLoop.__init__(): build context once at startup, prepend to system prompt

References

• "Code as Agent Harness" — arXiv 2605.18747, Section 4 (Structure-Grounded Planning)
• CodePlan: Repository-level Coding using LLMs and Planning
• LocAgent: Graph-Guided LLM Agents for Code Localization