Skip to content

docs: add sync protocol guide (DOC-06)#47

Merged
Killea merged 1 commit intoKillea:mainfrom
bertheto:docs/guide-sync-protocol
Mar 6, 2026
Merged

docs: add sync protocol guide (DOC-06)#47
Killea merged 1 commit intoKillea:mainfrom
bertheto:docs/guide-sync-protocol

Conversation

@bertheto
Copy link
Contributor

@bertheto bertheto commented Mar 5, 2026

Summary

Add docs/guides/sync-protocol.md — a comprehensive guide to the AgentChatBus sync protocol.

Content

  • How It Works — sequence diagram (Mermaid) of the full sync cycle: context issue, msg_post, success/error, recovery
  • Sync Context — table of current_seq, reply_token, reply_window fields
  • Reply Tokens — lifecycle flowchart (Mermaid), token sources table, validation rules
  • Sequence ValidationSEQ_TOLERANCE formula and behaviour
  • Fast-Return Logic — 3-level priority table (messages, bus_connect token, sync-only)
  • Error Types — 5 sync exceptions table with conditions
  • Error Response Shape — full JSON example with CRITICAL_REMINDER and new_messages_1st_read
  • Recovery Flow — flowchart (Mermaid) + 4-step procedure
  • ConfigurationAGENTCHATBUS_SEQ_TOLERANCE and AGENTCHATBUS_SEQ_MISMATCH_MAX_MESSAGES
  • Best Practices — agent-facing guidance
  • See Also — links to bus-connect guide and tools reference

mkdocs.yml changes

  • Enable Mermaid rendering: pymdownx.superfences custom_fences + extra_javascript: unpkg mermaid@10
  • Add nav entry: Guides > Sync Protocol

Test plan

  • mkdocs serve builds without errors
  • Sequence diagram renders correctly (How It Works)
  • Lifecycle flowchart renders correctly (Reply Tokens)
  • Recovery flowchart renders correctly (Recovery Flow)
  • Nav entry visible under Guides
  • All internal links resolve (note: bus-connect.md link resolves after PR docs: add bus_connect guide (DOC-01) #46 merges)

Add docs/guides/sync-protocol.md — comprehensive guide covering:
- How the sync protocol works (sequence diagram)
- Sync context fields (current_seq, reply_token, reply_window)
- Reply token lifecycle (flowchart), sources, and validation rules
- Sequence validation and SEQ_TOLERANCE
- Fast-return logic (3 priority levels)
- Error types (5 exceptions) and error response shape
- Recovery flow (flowchart)
- Configuration env vars and best practices

Enable Mermaid rendering in mkdocs.yml:
- pymdownx.superfences custom_fences for mermaid
- extra_javascript: unpkg mermaid@10

Add nav entry: Guides > Sync Protocol
@bertheto bertheto force-pushed the docs/guide-sync-protocol branch from a575d16 to f9a455b Compare March 5, 2026 23:45
@Killea Killea merged commit e203c68 into Killea:main Mar 6, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants