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.
34 lines
1.9 KiB
Markdown
34 lines
1.9 KiB
Markdown
# infrastructure/tools/
|
|
|
|
## Purpose
|
|
|
|
Tool implementations and execution infrastructure. Provides `DefaultToolRegistry`, `DispatchingToolExecutor`, and `SandboxedToolExecutor`. Implements concrete tools: shell execution (`ShellTool`), web search (`WebSearchTool`, requires SearXNG), web fetch + HTML→Markdown extraction (`WebFetchTool`, jsoup), task management tools, and filesystem tools (in `filesystem/`).
|
|
|
|
## Ownership
|
|
|
|
Adapter for `core:tools`. Depends on `core:tools`, `core:events`, `core:approvals`, `core:sessions`, `core:tasks`, `core:artifacts`, `core:artifacts-store`. The `filesystem/` submodule is a dependency of this module.
|
|
|
|
## Local Contracts
|
|
|
|
- `DefaultToolRegistry` implements `ToolRegistry` from `core:tools`.
|
|
- `SandboxedToolExecutor` wraps `DispatchingToolExecutor`; it enforces approval gates and records all tool side effects as events before returning (invariant #5).
|
|
- No tool may execute a side effect without emitting an event — silent execution is not allowed.
|
|
- Web search and web fetch results are environment observations; they must be recorded as events by callers to preserve replay determinism (invariant #9).
|
|
- `ToolConfig` is the only configuration surface; pass via `InfrastructureModule.createToolExecutor()`.
|
|
- `buildTools()` extension on `ToolConfig` assembles the full tool list; add new tools there, not in the registry directly.
|
|
|
|
## Work Guidance
|
|
|
|
Standard adapter rules apply (see parent `AGENTS.md`). Network calls (web tools) use Ktor CIO client with `withContext(Dispatchers.IO)`. Shell tool executes OS processes — never suppress `CancellationException` in process wait loops.
|
|
|
|
## Verification
|
|
|
|
```
|
|
./gradlew :infrastructure:tools:test --rerun-tasks
|
|
./gradlew :infrastructure:tools:filesystem:test --rerun-tasks
|
|
```
|
|
|
|
## Child DOX Index
|
|
|
|
- `filesystem/` — filesystem read/write/list tools implementing `core:tools` contracts; no separate AGENTS.md (sub-leaf, covered by this doc)
|