File reference — one page per source file

Every file in loopctl/src/, the derive/ crate, and the supporting trees, in plain words. Each page: what the file is, its key items, its behavior notes, and a link to the deep-dive article.

Use this when you’re in the code and want to know what the file in front of you does — or when you’re looking for where something lives.

The crate root & foundations

File	One line
lib.rs	Crate root — module wiring and the feature gates.
message.rs	The conversation data model: Message, parts, roles, tool content.
error.rs	LoopError — the one error enum, plus the lock-poison policy.
config.rs	SessionConfig — system prompt, context window, compaction knobs.
cancel.rs	CancelSignal — cooperative cancellation.
capabilities.rs	Small traits asking “does this bundle have X?”
contributor.rs	ContextContributor — per-turn message injection.
numeric.rs	Internal safe-math helpers (not public).
managers.rs	LoopManagers — the bundle of optional components.
presets.rs	Constrained/Frontier profiles + GoalReminder.

Talking to models

File	One line
api.rs	The ApiClient trait and request/response carriers.
api/error.rs	ApiError + ErrorCode — provider errors classified.
stream.rs	Stream events, deltas, stop reasons, the accumulator.
stream/handler.rs	StreamHandler — retries, timeouts, fallback.
stream/rate_limit.rs	Token-bucket rate limiter.
structured.rs	Structured (JSON) output: trait, formats, constraints.
provider.rs	Provider profiles + shared HTTP plumbing.
provider/openai.rs	OpenAI client (base of the compatible family).
provider/anthropic.rs	Anthropic client (base of Z.ai path).
provider/gemini.rs	Gemini client.
provider/bedrock.rs	AWS Bedrock client (signing, two wire paths).
provider/sse.rs	The SSE reader shared by the clients.
provider/grammar.rs	Grammar constraints for local samplers.

The engine

File	One line
engine.rs / engine/core.rs	Module roots (re-exports).
engine/core/machine.rs	The brain — the pure state machine.
engine/core/lifecycle.rs	Loop trait, Run/Session/Turn, RunConfig.
engine/core/outcome.rs	Outcome → error translation.
engine/bare.rs	The hands — the driver loop and its handlers.
engine/bare/llm_turn.rs	Building and sending one model request.
engine/bare/dispatch.rs	The tool-call pipeline and recovery.
engine/bare/compact.rs	The driver side of compaction.
engine/bare/emission.rs	All observer/hook fan-out.
engine/bare/config.rs	The set_*/with_* builders, temp dir.
engine/bare/model_switch.rs	Atomic mid-session model change.
engine/bare/tests.rs	The engine’s own test suite (in-file).

Tools & safety

File	One line
tool.rs	The Tool trait, outputs, errors, contexts.
tool/registry.rs	ToolRegistry + FnTool.
tool/permission.rs	PermissionCheck — the decision type.
tool/health.rs	Per-tool stats and circuit breakers.
tool/shield.rs	The safety shield trait + UnixShield.
middleware.rs	The pipeline core: trait, context, builder.
middleware/tool_call.rs	The pipeline’s innermost core (registry call).
middleware/timeout.rs	Per-call deadline.
middleware/permission.rs	Policy enforcement layer.
middleware/output_limit.rs	Output size cap.
middleware/unknown_tool.rs	“Did you mean…?” suggestions.
middleware/memoize.rs	The tool-result cache.
middleware/verify.rs	Post-write verification.
middleware/redaction.rs	Secret scrubbing.
middleware/shield.rs	The shield’s pipeline wiring.
detection/loop_detector.rs	Repeated-operation detection.
detection/convergence.rs	Repeated-answer detection.
detection/manager.rs	The detection facade (+ detection.rs root).
fallback.rs	Model-level circuit breaker + chain.
reflection.rs	Reflector + RecoveryStrategy traits.
reflection/llm.rs	The model-powered reflector.
reflection/backoff.rs	Exponential backoff strategy.

Watching & extending

File	One line
observer.rs + observer/context.rs	The LoopObserver trait + event payloads.
hooks.rs + hooks/context.rs	The Hook trait + contexts.
hooks/executor.rs	First-block-wins execution.
hooks/builtin/*	AutoCommit, Blocklist, Confirmation, Logging.
memory.rs + entry.rs + builtin.rs	The memory trait, entries, in-memory store.
compact.rs + types.rs + truncating.rs	Compaction manager, outcome types, truncator.

Integration & support

File	One line
mcp.rs	MCP client side (import foreign tools).
mcp/server.rs	MCP server side (serve your registry).
mcp/convert.rs	The type conversion layer between worlds.
testing.rs	Mocks and fixtures.
derive/src/*	The #[derive(Tool)] macro crate.
examples & tests	The runnable tour.