g3/AGENTS.md

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

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: logs/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

UTF-8 String Slicing (Throughout Codebase)

• Rust string slices (&s[..n]) use byte indices, not character indices
• Multi-byte UTF-8 characters (emoji, bullets •, ×, ⚡) cause panics if sliced mid-character
• Risk: Runtime panic on any string containing non-ASCII characters
• Fix: Use char_indices() to find byte boundaries:

  let byte_idx = s.char_indices().nth(char_limit).map(|(i, _)| i).unwrap_or(s.len());
  let truncated = &s[..byte_idx];
  

• Danger zones: Display truncation, ACD stubs, user input handling

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)
6. "String length equals character count" - s.len() returns bytes; use s.chars().count() for characters

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.