bytechefhq / bytechefhq/bytechef
Agent tool callbacks should call facades only; move domain error types out of the tool modules
- Dominant language
- Java
- Stars
- 1k
- Forks
- 170
- Avg merge
- 11h 25m
- Merged PRs (30d)
- 115
Description
## Goal
Make agent tool callbacks a thin adapter layer. A tool callback should translate the model's arguments into a facade call and translate the result back — nothing else. Domain logic and the error types describing domain failures belong with the services and facades that own them.
## What's wrong
Tool callbacks have accumulated logic that duplicates, and drifts from, the domain layer:
- **Tools reach past facades into services.** Many tool callbacks inject domain services directly instead of the domain's facade. Some join several services together inside the callback — orchestration that is precisely what a facade exists to express. The result is a second, parallel implementation of an operation that already exists one layer down, with no guarantee the two agree.
- **Authorization is bypassed as a side effect.** Authorization checks live on the facades. A tool that calls a service directly runs without them, so whether an agent-invoked operation is guarded depends on which collaborator the tool happened to inject. This makes the security posture of the tool surface accidental rather than declared.
- **Error types live in the tool modules.** Each tool module defines its own set of domain error types, describing failures of operations that the tool does not own. The domain cannot raise or reason about its own failure modes, and callers other than the tool surface get a different error vocabulary for the same failure.
## What we want instead
- A tool callback depends on facades only. If a tool needs an operation that no facade exposes, the operation is added to the facade — not assembled inside the tool.
- Multi-step operations invoked by tools are expressed as a single facade method, so they are authorized, transactional, and testable in one place.
- Domain error types move to the module that owns the domain, alongside the service or facade that raises them, and the tool surface translates them into tool-visible errors rather than defining them.
## Scope
Affects the agent tool modules across editions and both platform types. The domains where a tool currently reaches services directly, rather than through a facade, are the natural units of work — each can be migrated and verified independently.
## Definition of done
- No tool callback injects a domain service where a facade exists for that domain.
- Every operation a tool can invoke is reachable through a facade method carrying the domain's own authorization.
- Domain error types live with their domain, not in the tool modules.
## Suggested approach
Migrate one domain at a time, starting with the domains whose tools currently join multiple services — those carry the most duplicated logic and the widest authorization gap. File a tracking issue per domain so the work can be parallelized.
Contributor guide
Assessment
This issue has not been assessed yet.