# runifold-agent Agent guide
Read ../../AGENTS.md first. This guide adds local boundaries.
## Purpose
Owns: Canonical model/callable loop, review, structured completion and sessions.
Does not own: HTTP transports and database implementations.
## Key files and execution path
Start at `src/agent/execution.rs` and follow its module declarations and calls.
- `src/agent/execution.rs`
- `src/agent/callable.rs`
- `src/agent/review.rs`
- `src/agent/completion.rs`
- `src/checkpoint.rs`
- `src/conversation/session.rs`
## Extension points
Before changing callable dispatch, read ../runifold-effect/AGENTS.md and the modify-agent-loop recipe; test both agent and effect crates.
- RF-AGENT-LAW-001: prompt, run, stream, checkpoint and session execution share the canonical engine.
- RF-AGENT-LAW-002: reviewers receive attenuated parent authority.
- RF-TOOL-003: callable dispatch preserves explicit capability checks.
Public exports are in the crate entry point. Consult
[the architecture map](../../docs/ai/architecture.md) before crossing a crate boundary.
Tests next to implementation exercise local invariants; `tests/` (where present)
exercises public or protocol boundaries. Keep extensions within this ownership.
## Dependencies
- `runifold-core`: normal
- `runifold-effect`: normal
- `runifold-model`: normal
- `runifold-retrieval`: normal
- `runifold-testkit`: dev
- `runifold-tool`: normal
## Invariants and common mistakes
Preserve the root architectural laws. Do not introduce a second execution path,
ambient authority, hidden retry, or vendor wire types into neutral contracts.
Do not infer a public API from historical RFC examples; verify current exports.
Changes to a public contract need a regression test and release documentation.
## Tests to run
```sh
cargo test -p runifold-agent --locked
cargo clippy -p runifold-agent --all-targets --all-features --locked -- -D warnings
```
Database tests may require Docker; see [testing](../../docs/ai/testing.md).
After changing features, dependencies, entry points or recipes, run
`python3 scripts/ai-knowledge.py --write` and `--check` at the workspace root.