Files

T

kami d26f20c316 docs(dox): build out the DOX AGENTS.md hierarchy

Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree
(core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc),
each following the DOX section shape: Purpose, Ownership, Local Contracts,
Work Guidance, Verification, Child DOX Index.

2026-06-28 20:43:27 +04:00

2.2 KiB

Raw Permalink Blame History

core/tools — AGENTS.md

Purpose

Tool contract, registry, executor, and receipt tracking: defines the Tool interface, manages tool registration, executes tools within their declared tier, compresses tool output, and projects tool invocation history via the standard event-sourcing stack.

Ownership

CORREX kernel team.

Local Contracts

Tool — primary interface all tools implement. Must declare Tier (from core:events).
ToolRegistry — holds all registered tools for a session; looked up by name.
ToolExecutor — executes a Tool given a ToolRequest, records ToolEvents in core:events.
ToolResult — sealed result type: success with output, or failure with error.
ToolState rebuilt from ToolEvents via DefaultToolReducer + ToolProjector.
DefaultToolRepository wraps EventReplayer<ToolState>.
ToolInvocationRecord / ToolInvocationStatus / ToolCallAssessmentRecord — history types.
FileMutationRecord — records file-affecting side effects.
FileAffectingTool — extended Tool interface for tools that write files; must declare affectedPaths.
OutputCompressionSpec / ToolOutputCompressor / DeclarativeCompressor — compress large tool outputs to fit token budgets (Hard Invariant #6: compressed output is informational; original events are preserved).
ParamRole — annotates tool parameter semantic roles (input path, output path, etc.).
ValidationResult — result from tool-level parameter validation (pre-execution check).
Hard Invariant #5: all tool side effects are captured in events. Silent execution is not allowed.

Work Guidance

Follow the standard Events→State→Reducer→Projector→Repository pattern (see core/AGENTS.md).
DefaultToolReducer only does state.copy(...).
ToolExecutor must record a ToolExecutedEvent (or equivalent) before returning, even on failure.
Output compression must not discard the original event — only produce a derived summary alongside it.
New tools implement Tool (or FileAffectingTool) and register in ToolRegistry. Do not instantiate tools inside ToolExecutor.

Verification

./gradlew :core:tools:test --rerun-tasks

Child DOX Index

No child AGENTS.md (leaf module).

2.2 KiB Raw Permalink Blame History