Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs(coderd/x/chatd): correct timing, route, hook, and tool details in ARCHITECTURE.md - #29154

Merged
jscottmiller merged 1 commit into
mainfrom
scott/chatd-arch-doc-fixes
Sep 11, 2026
Merged

docs(coderd/x/chatd): correct timing, route, hook, and tool details in ARCHITECTURE.md#29154
jscottmiller merged 1 commit into
mainfrom
scott/chatd-arch-doc-fixes

Conversation

@jscottmiller

@jscottmiller jscottmiller commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Corrects statements in coderd/x/chatd/ARCHITECTURE.md that disagree with the current code, and fills in the omissions found alongside them. Docs-only; each item below names the code that backs it.

  • Acquisition loop: the timer fires every 1s and a lease expires after 5m, not 30s/30s. Both are chatd.New defaults (DefaultPendingChatAcquireInterval, DefaultInFlightChatStaleAfter, coderd/x/chatd/chatd.go:65-68, 3120-3123); coderd/coderd.go:937-965 sets neither and no deployment flag exposes them. The 30s values are the chatWorkerOptions fallbacks in options.go:24,30. 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:2480-2489).
  • Heartbeat loop: the interval is 30s (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).
  • 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). 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_part stream events already carry history_version and generation_attempt (codersdk/chats.go:1692-1698); the "should additionally include" note is replaced with a statement of current behavior.
  • Lifecycle hooks: enumerated the seven event types (codersdk/x/agenthooks/types.go:31-37) and noted that a permission on any event other than user_prompt_submit or pre_tool_use is rejected as an invalid response (coderd/x/agenthooks/dispatch/dispatcher.go:590-599, 363-370).
  • Generation goroutine: listed the subagent tools and the close_agent alias (coderd/x/chatd/subagent_catalog.go:17-18,43-50, subagent.go:41-47).
  • Replaced 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, chatprovider/chatprovider.go:767-771).

Follow-ups noted during review, out of scope here because they are new content rather than corrections:

  • The chat:ownership emission rule (Pubsub section) decides "no fresh heartbeat row" using a hardcoded 30s in coderd/x/chatd/chatstate/machine.go:20, distinct from the 5m lease threshold. The doc should state both thresholds.
  • The concurrent agent limiter counts a chat as active while its heartbeat row is younger than the same 5m threshold (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.

…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
jscottmiller marked this pull request as ready for review September 11, 2026 15:41
@jscottmiller
jscottmiller merged commit 7a2cedf into main Sep 11, 2026
59 of 60 checks passed
@jscottmiller
jscottmiller deleted the scott/chatd-arch-doc-fixes branch September 11, 2026 17:53
@github-actions github-actions Bot locked and limited conversation to collaborators Sep 11, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants