chatpharo

Message flow (from “Send” to response)

This document explains what happens internally from the moment you send a message until the model output appears.

High-level sequence diagram

User
  |
  | (1) sendMessage
  v
ChatPharoPresenter (Spec)
  |
  | model sendMessage: text
  v
ChatPharoChat (conversation)
  |
  | (2) command parsing? (/help, /reset, ...)
  | (3) add user message -> UI + history
  | (4) build prompt:
  |     - history prefix
  |     - + memory context (optional)
  |     - + skills context (optional)
  | (5) multivers chain (optional) / cache (optional)
  v
ChatPharoAgent (backend)
  |
  | (6) HTTP request via ChatPharoTool (or backend-specific client)
  | (7) parse response (content, thinking, tool_calls)
  |
  | (8) tool loop (bounded):
  |     while tool_calls and iteration < maximumIterations:
  |         execute tool -> append tool result -> call model again
  v
ChatPharoChat
  |
  | (9) add assistant message -> UI + history
  | (10) notify listeners / update status
  v
User sees response

Step-by-step lifecycle

1) UI triggers a send

The presenter sends the current input text to the model and records a frontend log entry.

2) Command parsing (optional)

If the text starts with a supported command, ChatPharo executes it locally:

• /help, /clear, /reset, /export, /history

No model call occurs for these commands.

3) UI message and history message are written together

ChatPharo keeps two synchronized representations:

• ChatPharoMessage for UI rendering
• ChatPharoHistoryMessage for LLM requests (role/content/tool_calls)

4) Prompt building

ChatPharo builds an effective prompt from multiple sources:

• Conversation history (promptPrefix)
• Memory context (if enabled)
• Skills context (enabled skills + optional auto-detected skills)

5) Multivers and cache (optional)

• Multivers can rewrite/refine the prompt across a chain of agents.
• Caching can return a previously computed response for identical prompts.

6) Agent call

The selected ChatPharoAgent sends the request to the backend.

• Most cloud agents build OpenAI-like payloads (messages + tools) through ChatPharoTool.
• Some local agents use a backend-specific schema but preserve the same agent interface.

7) Response parsing

The response may include:

• assistant content
• optional thinking content
• optional tool calls (tool_calls)

8) Tool call loop (bounded)

If tool calls exist and tool calling is enabled/supported:

1. Execute the requested tool locally (browser, custom, MCP).
2. Append tool result to history as a tool message.
3. Call the model again with updated history.

Repeat until tool calls stop or maximumIterations is reached.

9) Conversation update and notifications

The final assistant message is appended to UI and history, and listeners are notified.

10) Auto-summarize to memory (optional)

When enabled, ChatPharo can summarize conversations into memory for future context injection.

Cancellation & concurrency

• Requests run asynchronously to keep the UI responsive.
• Cancelling terminates the in-flight prompt process and prevents applying the response.

Related docs

• Tools: tools.md
• Memory: memory.md
• Multivers: multivers.md

This site is open source. Improve this page.