Message history state machine: invariant by construction

[seamus-brady]

Summary

The cog has been dying mid-cycle with API 400s of the form messages.40.content.0: unexpected tool_use_id — orphan tool_result blocks whose matching tool_use was lost. Each historical fix patched one new shape; the next code path introduced another. This PR ends the family at the root.

Root cause: state.messages was a public List(Message). ~30 handlers across the cog list.append-ed directly. Provider-API invariants (alternation, leading-user, tool_use ↔ tool_result pairing) lived only in a reactive sweep at the LLM boundary that covered one direction of one rule. New mutations kept introducing new violations.

Structural fix: opaque MessageHistory with one chokepoint (add) that maintains every invariant by construction. Direct list.append on state.messages is now impossible — the type prevents it.

What's enforced where

Invariant	Enforced by
Leading message must be User	add silently drops a leading Assistant; from_list strips one at ingest
User/assistant alternation	add coalesces consecutive same-role messages
No orphan tool_result	add strips any tool_result whose tool_use_id has no matching tool_use in the prior assistant message; if that empties the message, the message is dropped
No orphan tool_use	from_list injects synthetic stub tool_results at ingest (the opposite direction; useful when loading persisted history with a half-completed cycle)

for_send exports a wire-ready List(Message). The reactive boundary sweep (repair_orphans_and_warn + llm/message_repair.gleam) is deleted — there's nothing left for it to repair.

What changed

• New: src/llm/message_history.gleam (442 lines) — opaque type, add chokepoint, from_list ingest sanitisation, to_list / for_send exports
• New: test/llm/message_history_test.gleam (260 lines) — 16 tests, one per invariant, each constructing the exact malformation that caused a production bug
• Modified: src/agent/cognitive_state.gleam — state.messages: MessageHistory (was List(Message))
• Modified: src/agent/cognitive.gleam, src/agent/cognitive/agents.gleam, src/agent/cognitive/llm.gleam, src/agent/cognitive/safety.gleam — every direct list.append(state.messages, ...) rewritten through message_history.add / add_user / add_assistant / add_user_text
• Deleted: src/llm/message_repair.gleam, test/llm/message_repair_test.gleam — module redundant; its pipeline is intrinsic to MessageHistory.from_list

Test plan

• gleam build clean
• gleam format clean
• gleam test — 2155 passing (gained 16 from new tests, lost the deleted message_repair_test cases since the module is gone)
• add_user_with_orphan_tool_result_strips_it_test reproduces the operator-reported cog-killer
• Run gleam run against the live agent; confirm no API 400s after a turn that previously dropped the cog

🤖 Generated with Claude Code