docs(coderd/x/chatd): correct timing, route, hook, and tool details in ARCHITECTURE.md - #29154
Merged
Conversation
…n ARCHITECTURE.md Fix statements that disagree with the current code and fill in omissions noted alongside them. Each change cites its code location. - Acquisition loop: timer is 1s and lease expiry is 5m in production, set by chatd.New from DefaultPendingChatAcquireInterval and DefaultInFlightChatStaleAfter (coderd/x/chatd/chatd.go:65-68, 2988-2996, 3120-3123). coderd/coderd.go:937-965 sets neither and no deployment flag exposes them. The acquire predicate also treats a null runner_id as unowned and checks chat_heartbeats for the current (chat_id, runner_id) (coderd/database/queries/chats.sql:2461-2470). - Heartbeat loop: interval is 30s from DefaultChatHeartbeatInterval (chatd.go:83, 3122); a lease survives ten intervals after the last successful write against the 5m threshold (strict comparison at chats.sql:2469). Cleanup runs every 30s (options.go:29, runner_manager.go:499) and uses the same parameterized threshold (chats.sql:2503-2505). - HTTP endpoints: routes are registered once and mounted under both /api/experimental and /api/v2 (coderd/chat_routes.go:33-43, coderd/coderd.go:1394,1451); list the experimental-only routes (chat_routes.go:62-77, 128-139, 166-179) and the reserved 404 segments on each mount (chat_routes.go:52-60, 78-93). - message_part already carries history_version and generation_attempt (codersdk/chats.go:1692-1698). - Lifecycle hooks: enumerate the seven event types (codersdk/x/agenthooks/types.go:31-37); a permission on any other event is rejected as an invalid response (coderd/x/agenthooks/dispatch/dispatcher.go:590-599, 363-370). - Generation goroutine: list the subagent tools and the close_agent alias (coderd/x/chatd/subagent_catalog.go:17-18,43-50, subagent.go:41-47). - Replace the two TODO notes with prose describing openAIReasoningEffort (coderd/x/chatd/chatprovider/reasoningeffort.go:183-192) and UsesResponsesAPI (coderd/x/chatd/chatopenai/transport.go:64-78, coderd/x/chatd/chatprovider/chatprovider.go:767-771).
jscottmiller
marked this pull request as ready for review
September 11, 2026 15:41
ibetitsmike
approved these changes
Sep 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Corrects statements in
coderd/x/chatd/ARCHITECTURE.mdthat disagree with the current code, and fills in the omissions found alongside them. Docs-only; each item below names the code that backs it.chatd.Newdefaults (DefaultPendingChatAcquireInterval,DefaultInFlightChatStaleAfter,coderd/x/chatd/chatd.go:65-68,3120-3123);coderd/coderd.go:937-965sets neither and no deployment flag exposes them. The 30s values are thechatWorkerOptionsfallbacks inoptions.go:24,30. The acquire predicate also treats a nullrunner_idas unowned and checkschat_heartbeatsfor the current(chat_id, runner_id)(coderd/database/queries/chats.sql:2480-2489).DefaultChatHeartbeatInterval,chatd.go:83), not 9s, so a lease survives ten intervals after the last successful write rather than three. The cleanup loop runs every 30s and uses the same parameterized threshold (runner_manager.go:499,chats.sql:2522-2524)./api/experimentaland/api/v2(coderd/chat_routes.go:33-43,coderd/coderd.go:1394,1451). Added the experimental-only routes (chat_routes.go:62-77,128-139,166-179) and the reserved 404 segments on each mount (chat_routes.go:52-60,78-93).message_partstream events already carryhistory_versionandgeneration_attempt(codersdk/chats.go:1692-1698); the "should additionally include" note is replaced with a statement of current behavior.codersdk/x/agenthooks/types.go:31-37) and noted that apermissionon any event other thanuser_prompt_submitorpre_tool_useis rejected as an invalid response (coderd/x/agenthooks/dispatch/dispatcher.go:590-599,363-370).close_agentalias (coderd/x/chatd/subagent_catalog.go:17-18,43-50,subagent.go:41-47).TODO:notes with prose describingopenAIReasoningEffort(coderd/x/chatd/chatprovider/reasoningeffort.go:183-192) andUsesResponsesAPI(coderd/x/chatd/chatopenai/transport.go:64-78,chatprovider/chatprovider.go:767-771).Follow-ups noted during review, out of scope here because they are new content rather than corrections:
chat:ownershipemission rule (Pubsub section) decides "no fresh heartbeat row" using a hardcoded 30s incoderd/x/chatd/chatstate/machine.go:20, distinct from the 5m lease threshold. The doc should state both thresholds.chatd.go:3102-3105,chats.sql:2975,2992,3007), so a crashed replica's chats hold capacity slots until the lease expires. The doc does not mention this.Generated by Coder Agents on behalf of @jscottmiller.