adachsoft / ai-tool-call-middleware

v0.2.0 2026-09-04 15:29 UTC

Requires

• php: ^8.3
• adachsoft/ai-tool-call: ^1.0 || ^2.0

Requires (Dev)

• adachsoft/php-code-style: ^0.7
• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^12.5
• rector/rector: ^2.6
• symplify/phpstan-rules: ^14.13

MIT

Published on Packagist.org on 2026-09-04 14:02 UTC

README

adachsoft/ai-tool-call-middleware provides decorators for the public adachsoft/ai-tool-call facade.

Output-size safeguard

Wrap a facade through OutputSizeLimitingFacadeFactory:

use AdachSoft\AiToolCallMiddleware\OutputSize\OutputSizeLimitingFacadeFactory;

/** @var OutputSizeLimitingFacadeFactory $factory */
$factory = $container->get(OutputSizeLimitingFacadeFactory::class);
$facade = $factory->wrap($baseFacade);

wrap() returns an AiToolCallFacadeInterface. The returned facade measures supported tool results in bytes and passes results within the configured limit through unchanged. Oversized results are returned as a structured truncation payload containing the original size, configured limit, returned size, preview, and guidance for requesting a narrower result.

The middleware does not throw an exception when an output exceeds the limit. Results that cannot be measured are passed through unchanged, using a fail-open policy so the safeguard does not break an otherwise valid tool call. Exceptions raised by the wrapped facade are propagated unchanged.

Tool discovery methods are delegated without modification. The safeguard therefore applies only to tool-call results.

UTF-8 sanitization safeguard

Wrap a facade through Utf8SanitizingFacadeFactory:

use AdachSoft\AiToolCallMiddleware\Utf8Sanitizing\Utf8SanitizingFacadeFactory;

$facade = $container->get(Utf8SanitizingFacadeFactory::class)->wrap($baseFacade);

Invalid UTF-8 sequences in string tool results are replaced with U+FFFD, including nested array values and string keys. Other result types are passed through unchanged.

Compose safeguards from the inside out with UTF-8 sanitization closest to the tool:

$facade = $utf8->wrap($outputSize->wrap($baseFacade));

See docs/middleware-design-rules.md for the middleware design rules and recommended chain order.

Individual tools should still provide their own limits, pagination, filtering, and truncation metadata. See the repository documentation in docs/tool-output-size-rules.md for the output-size contract.