Context
MessageDocument (from @loopstack/common) and LlmMessageDocument (from @loopstack/llm-provider-module) both expose { role, content }. Both render as chat bubbles in Studio. The semantic distinction — one is for UI; the other doubles as LLM conversation history via messagesSearchTag — is real but invisible from the names or APIs. Builders confuse them and either get unexpected behaviour (history collected when not wanted, or not collected when it is) or waste cycles deciding which one to use.
What to do
Decide how to make the distinction unambiguous, then carry the decision through across @loopstack/common, @loopstack/llm-provider-module, every doc page that mentions either class, and the example workflows in registry/examples/*.
Affected area
- Package(s):
@loopstack/common, @loopstack/llm-provider-module, all packages that save chat messages
Acceptance criteria
Additional context
Surfaced during a benchmark agent session where the agent oscillated between the two classes while debugging a "summary not visible" symptom that turned out to be unrelated. The confusion cost real iteration time.
Context
MessageDocument(from@loopstack/common) andLlmMessageDocument(from@loopstack/llm-provider-module) both expose{ role, content }. Both render as chat bubbles in Studio. The semantic distinction — one is for UI; the other doubles as LLM conversation history viamessagesSearchTag— is real but invisible from the names or APIs. Builders confuse them and either get unexpected behaviour (history collected when not wanted, or not collected when it is) or waste cycles deciding which one to use.What to do
Decide how to make the distinction unambiguous, then carry the decision through across
@loopstack/common,@loopstack/llm-provider-module, every doc page that mentions either class, and the example workflows inregistry/examples/*.Affected area
@loopstack/common,@loopstack/llm-provider-module, all packages that save chat messagesAcceptance criteria
@loopstack/commonand@loopstack/llm-provider-modulealigned with the decision.Additional context
Surfaced during a benchmark agent session where the agent oscillated between the two classes while debugging a "summary not visible" symptom that turned out to be unrelated. The confusion cost real iteration time.