..  include:: /Includes.rst.txt

.. _adr-002:

=====================================
ADR-002: CLI-Based Message Processing
=====================================

**Status:** Accepted

**Date:** 2026-03-14

Context
=======

Processing an AI chat message involves: calling the LLM API (seconds to tens of
seconds), potentially executing multiple MCP tool calls (each spawning a
subprocess), and looping until the agent produces a final reply. This cannot
complete within a reasonable HTTP request timeout and would block a PHP-FPM
worker for the entire duration.

Alternatives considered:

-   **Synchronous HTTP response**: Ties up an FPM worker; times out on slow LLMs
    or long tool chains.
-   **Async HTTP (ReactPHP/Swoole)**: Requires a non-standard PHP runtime;
    incompatible with most TYPO3 hosting environments.
-   **Queue system (RabbitMQ, Redis Queue)**: Adds external infrastructure
    dependencies.
-   **CLI subprocess**: PHP CLI has no timeout constraints; uses no FPM workers
    during processing.

Decision
========

Process messages via CLI commands, dispatched by the web server:

-   **``exec`` mode**: The web request forks a ``ai-chat:process <messageUid>``
    subprocess per message and returns immediately.
-   **``worker`` mode**: A long-running ``ai-chat:worker`` process polls for
    pending messages. Suitable for environments where forking per request is
    undesirable.

Both modes write the assistant reply back to the database. The browser polls for
completion.

Consequences
============

-   Web server stays responsive regardless of LLM latency or tool chain depth.
-   No external queue infrastructure required.
-   ``exec`` mode requires ``proc_open`` / ``shell_exec`` to be available.
-   ``worker`` mode requires a process supervisor (systemd, supervisor) to keep
    the worker alive.
-   The processing strategy is configurable via extension configuration.