Architecture 

Polling over SSE 

The chat UI uses periodic AJAX polling instead of Server-Sent Events (SSE) or WebSockets. This was chosen because:

• It works reliably behind reverse proxies and load balancers without special configuration.
• TYPO3 backend requests go through the standard middleware stack, ensuring authentication and CSRF protection.
• The polling interval is short enough (1-2 seconds) to feel responsive.

CLI processing over HTTP 

Message processing happens in CLI context (ai-chat:process or ai-chat:worker), not in the web request. This design:

• Avoids PHP timeout issues -- the LLM calls and tool execution in the agent run can take many seconds.
• Keeps the web server responsive -- no long-running HTTP connections.
• Allows the worker mode to reuse a single process for multiple requests, reducing overhead.

Crash recovery 

The system is designed to handle crashes gracefully:

• Every state transition is persisted to the database immediately.
• If a CLI process crashes mid-conversation, the conversation remains in processing, locked, or tool_loop status.
• The ai-chat:cleanup command detects conversations stuck for more than 5 minutes and marks them as failed.
• Users see a clear error message and can retry.

Conversation 

The central entity. Stored in tx_nrmcpagent_conversation.

Fields:

be_user

UID of the owning backend user.

title

Auto-generated title from the first message.

messages

JSON-encoded array of all messages (user, assistant, tool calls, tool results). Stored as mediumtext.

User messages with file attachments contain additional fields:

{
    "role": "user",
    "content": "What is in this image?",
    "fileUid": 42,
    "fileName": "photo.jpg",
    "fileMimeType": "image/jpeg"
}

Copied!

The fileUid is a TYPO3 FAL UID. ChatService::buildLlmMessages() reads the file and converts it to a multimodal content array before passing messages to the LLM.

message_count

Denormalized count for display without decoding.

status

Current processing state (see below).

current_request_id

Identifier for the active processing request. Used for worker dequeue locking.

system_prompt

Optional custom system prompt override (per conversation).

System prompt priority 

The system prompt is composed in this order:

1. Identity / behaviour contract -- Always prepended. A fixed block establishes that the assistant is the Netresearch TYPO3 Backend AI Chat, steers it to use its tools instead of asking the user to paste data, forbids it from claiming to be ChatGPT/OpenAI, and tells it to answer in the user's language. This holds regardless of how the Task/Configuration prompt is set.
2. Conversation-level prompt -- If a conversation has a custom system_prompt set, it is used in place of the Configuration/Task prompts.
3. nr-llm Configuration + Task prompts -- Otherwise the system_prompt from the nr-llm Configuration record and the prompt_template from the Task record are combined (separated by a blank line). Configure these in the TYPO3 backend to provide tool usage instructions or persona definitions.

The site-language context is appended in every case.

Configuration resolution 

ChatService resolves the LlmConfiguration the chat runs against, and the prompts, through nr-llm:

1. Load the Task record via nr-llm's TaskRepository (by llmTaskUid from extension configuration).
2. Take Task::getConfiguration() as the LlmConfiguration passed to AgentRuntime::run(). A missing Task or Configuration fails the turn loudly.
3. The Configuration's system_prompt and the Task's prompt_template feed buildSystemPrompt().

A provider adapter is still created from the Configuration's model (via ProviderAdapterRegistry) — but only to expand file attachments and report supported formats; the chat turn itself runs inside nr-llm's AgentRuntime.

archived

Whether the conversation is archived.

pinned

Whether the conversation is pinned (prevents auto-archiving).

error_message

Last error message (sanitized, no API keys).

ConversationStatus 

The conversation lifecycle is modeled as a state enum:

idle

Ready for new user input. This is the resting state.

processing

A CLI process is actively calling the LLM.

locked

Reserved by a worker process for dequeue.

tool_loop

Legacy transitional state. The tool loop now runs synchronously inside nr-llm's AgentRuntime within a single processing turn, so the chat no longer parks a conversation here; the state is retained for backward compatibility.

failed

An error occurred. The user can retry by sending a new message.

State transitions:

idle --> processing --> idle          (success)
idle --> processing --> tool_loop --> processing
                                         (tool iteration)
idle --> processing --> failed        (error)
* --> failed                         (cleanup timeout)