f6b84d864a
Standardize project name to lowercase 'g3' throughout documentation, comments, and configuration files. Environment variables (G3_*) are unchanged as they follow the uppercase convention.
117 lines
4.8 KiB
Markdown
117 lines
4.8 KiB
Markdown
# AGENTS.md - Machine Instructions for g3
|
||
|
||
**Purpose**: Machine-specific instructions for AI agents working with this codebase.
|
||
**For project overview, architecture, and usage**: See [README.md](README.md)
|
||
|
||
## Critical Invariants
|
||
|
||
### MUST Hold
|
||
|
||
1. **Tool calls must be valid JSON** - The streaming parser expects well-formed tool calls
|
||
2. **Context window limits must be respected** - Exceeding limits causes API errors
|
||
3. **Provider trait implementations must be Send + Sync** - Required for async runtime
|
||
4. **Session IDs must be unique** - Used for log file paths and TODO scoping
|
||
5. **File paths in tools support tilde expansion** - `~` expands to home directory
|
||
6. **Streaming is preferred** - Non-streaming requests block UI
|
||
7. **Tool results are size-limited** - Large outputs are truncated or thinned automatically
|
||
|
||
### MUST NOT Do
|
||
|
||
1. **Never block the async runtime** - Use `tokio::spawn` for CPU-intensive work
|
||
2. **Never store secrets in logs** - API keys are redacted in error logs
|
||
3. **Never modify files outside working directory without explicit permission**
|
||
4. **Never assume tool results fit in context** - Large results are thinned automatically
|
||
|
||
## Recommended Entry Points
|
||
|
||
### For Understanding the System
|
||
|
||
1. `src/main.rs` - Entry point (trivial)
|
||
2. `crates/g3-cli/src/lib.rs` - CLI logic and execution modes
|
||
3. `crates/g3-core/src/lib.rs` - Agent struct and orchestration
|
||
4. `crates/g3-providers/src/lib.rs` - Provider trait definition
|
||
|
||
### For Adding Features
|
||
|
||
1. **New tool**: `crates/g3-core/src/tool_definitions.rs` → `crates/g3-core/src/tools/`
|
||
2. **New provider**: `crates/g3-providers/src/` → implement `LLMProvider` trait
|
||
3. **New CLI mode**: `crates/g3-cli/src/lib.rs`
|
||
4. **New config option**: `crates/g3-config/src/lib.rs`
|
||
|
||
### For Debugging
|
||
|
||
1. Session logs: `.g3/sessions/<session_id>/session.json`
|
||
2. Error logs: `.g3/errors/`
|
||
3. Context state: Use `/stats` command in interactive mode
|
||
|
||
## Dangerous/Subtle Code Paths
|
||
|
||
### Context Window Management (`g3-core/src/context_window.rs`)
|
||
|
||
- **Thinning**: Automatically replaces large tool results with file references
|
||
- **Summarization**: Compresses conversation history at 80% capacity
|
||
- **Token estimation**: Uses character-based heuristics, not exact tokenization
|
||
- **Risk**: Incorrect token estimates can cause context overflow
|
||
|
||
### Streaming Parser (`g3-core/src/streaming_parser.rs`)
|
||
|
||
- Parses LLM responses in real-time for tool calls
|
||
- Must handle partial JSON across chunk boundaries
|
||
- **Risk**: Malformed responses can cause parsing failures
|
||
|
||
### Tool Dispatch (`g3-core/src/tool_dispatch.rs`)
|
||
|
||
- Routes tool calls to implementations
|
||
- Handles both native and JSON-based tool calling
|
||
- **Risk**: Missing dispatch cases cause silent failures
|
||
|
||
### Retry Logic (`g3-core/src/retry.rs`)
|
||
|
||
- Exponential backoff with jitter
|
||
- Different configs for interactive vs autonomous mode
|
||
- **Risk**: Aggressive retries can hit rate limits harder
|
||
|
||
## Do's and Don'ts for Automated Changes
|
||
|
||
### Do
|
||
|
||
- ✅ Run `cargo check` after modifications
|
||
- ✅ Run `cargo test` before committing
|
||
- ✅ Update tool definitions when adding tools
|
||
- ✅ Add tests for new functionality
|
||
- ✅ Use existing patterns for similar features
|
||
- ✅ Keep functions under 80 lines
|
||
- ✅ Update documentation for user-facing changes
|
||
|
||
### Don't
|
||
|
||
- ❌ Modify `Cargo.toml` dependencies without justification
|
||
- ❌ Add blocking code in async contexts
|
||
- ❌ Store sensitive data in plain text
|
||
- ❌ Ignore error handling
|
||
- ❌ Create deeply nested conditionals (>6 levels)
|
||
- ❌ Add external dependencies for simple tasks
|
||
|
||
## Common Incorrect Assumptions
|
||
|
||
1. **"All providers support tool calling"** - Embedded models use JSON fallback
|
||
2. **"Context window is unlimited"** - Each provider has limits (4k-200k tokens)
|
||
3. **"Tool results are always small"** - File reads can return megabytes
|
||
4. **"Sessions persist across runs"** - Sessions are ephemeral by default
|
||
5. **"All platforms are equal"** - macOS has more features (Vision, Accessibility)
|
||
|
||
## Dependency Analysis Artifacts
|
||
|
||
The `analysis/deps/` directory contains static analysis artifacts generated by the Euler agent:
|
||
|
||
| File | Purpose |
|
||
|------|--------|
|
||
| `graph.json` | Raw dependency graph data (crate and file-level edges with evidence) |
|
||
| `graph.summary.md` | Overview metrics: crate counts, edge counts, fan-in/fan-out rankings |
|
||
| `sccs.md` | Strongly Connected Components analysis (cycle detection via Tarjan's algorithm) |
|
||
| `layers.observed.md` | Mechanically-derived layer diagram showing crate hierarchy and intra-crate module structure |
|
||
| `hotspots.md` | Coupling hotspots: files/crates with disproportionate fan-in or fan-out (>2× average) |
|
||
| `limitations.md` | Known limitations of the static analysis (conditional compilation, macros, re-exports) |
|
||
|
||
These artifacts are useful for understanding coupling, planning refactors, and identifying architectural boundaries.
|