kami
d26f20c316
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.
44 lines
2.2 KiB
Markdown
44 lines
2.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
./gradlew :core:tools:test --rerun-tasks
|
|
```
|
|
|
|
## Child DOX Index
|
|
|
|
No child AGENTS.md (leaf module).
|