adachsoft / ai-tool-call-middleware
Middleware decorators for adachsoft/ai-tool-call facade.
Package info
gitlab.com/a.adach/ai-tool-call-middleware
pkg:composer/adachsoft/ai-tool-call-middleware
Requires
- php: ^8.3
- adachsoft/ai-tool-call: ^2.2
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^12.5
- rector/rector: ^2.6
- symplify/phpstan-rules: ^14.13
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
adachsoft/ai-tool-call-middleware provides decorators for the public adachsoft/ai-tool-call facade.
Output-size safeguard
Create a facade factory through OutputSizeLimitingFacadeFactory::create():
use AdachSoft\AiToolCallMiddleware\OutputSize\OutputSizeLimitingFacadeFactory;
/** @var OutputSizeLimitingFacadeFactory $factory */
$factory = OutputSizeLimitingFacadeFactory::create(4096);
$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
Create a facade factory through Utf8SanitizingFacadeFactory::create():
use AdachSoft\AiToolCallMiddleware\Utf8Sanitizing\Utf8SanitizingFacadeFactory;
$facade = Utf8SanitizingFacadeFactory::create()->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 and execution-time limiting outside the result-processing decorators:
$facade = $executionTime->wrap(
$outputSize->wrap(
$utf8->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.
Tool result media
Results may carry media (ToolCallResultDto::$media, adachsoft/ai-tool-call 2.2+). The output-size and UTF-8 safeguards only inspect and rewrite the structured result; media are passed through unchanged and do not count towards the output-size limit. Tools that return media are responsible for bounding media size themselves.
Execution-time safeguard
Create a factory with a default limit and optional per-tool overrides:
use AdachSoft\AiToolCallMiddleware\ExecutionTime\ExecutionTimeLimitingFacadeFactory;
$executionTime = ExecutionTimeLimitingFacadeFactory::create(
defaultLimitSeconds: 600,
toolLimitOverrides: [
'phpunit_runner' => 900,
'long_running_tool' => 1800,
'unlimited_tool' => 0,
],
);
$facade = $executionTime->wrap($baseFacade);
A per-tool override replaces the default. A value of 0 or null disables the limit for that tool; a default of 0 or null disables limits unless overridden. Negative values are rejected. A timed-out call throws the adachsoft/ai-tool-call ToolCallFailedException with a message such as Tool "phpunit_runner" exceeded its execution time limit of 600 s; use a narrower command or a non-interactive mode.
When PCNTL is unavailable, the decorator fails open, delegates the call unchanged, and writes one availability message to the PHP error log per process. If an outer call times out during a nested agent call, subsequent nested calls fail fast without running their tool operations. The parent surfaces its timeout even if the nested agent caught the original exception, once the parent operation returns or throws. On Linux, after a timeout the decorator discovers descendants through /proc/<pid>/task/*/children, sends them SIGTERM, and sends SIGKILL to any still running after a two-second grace period. Processes that existed before the call, the current PHP process, and process groups are not signalled.
This middleware is a safety net rather than a replacement for tool-specific timeouts. It cannot guarantee immediate interruption while execution is inside some blocking C-extension calls. SIGALRM is process-global, so other uses of pcntl_alarm() or SIGALRM can conflict with this middleware. Descendant cleanup requires Linux procfs and posix_kill(); without them, the timeout still applies but child cleanup is unavailable.