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

1.9 KiB

Raw Blame History

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)

1.9 KiB Raw Blame History