feat: add chat debug log tables, queries, and SDK types (#23913)

codersdk/chats.go

@@ -549,6 +549,135 @@ type UpdateChatDesktopEnabledRequest struct {
 	EnableDesktop bool `json:"enable_desktop"`
 }
 
+// ChatDebugLoggingAdminSettings describes the runtime admin setting
+// that allows users to opt into chat debug logging.
+type ChatDebugLoggingAdminSettings struct {
+	AllowUsers         bool `json:"allow_users"`
+	ForcedByDeployment bool `json:"forced_by_deployment"`
+}
+
+// UserChatDebugLoggingSettings describes whether debug logging is
+// active for the current user and whether the user may control it.
+type UserChatDebugLoggingSettings struct {
+	DebugLoggingEnabled bool `json:"debug_logging_enabled"`
+	UserToggleAllowed   bool `json:"user_toggle_allowed"`
+	ForcedByDeployment  bool `json:"forced_by_deployment"`
+}
+
+// UpdateChatDebugLoggingAllowUsersRequest is the admin request to
+// toggle whether users may opt into chat debug logging.
+type UpdateChatDebugLoggingAllowUsersRequest struct {
+	AllowUsers bool `json:"allow_users"`
+}
+
+// UpdateUserChatDebugLoggingRequest is the per-user request to
+// opt into or out of chat debug logging.
+type UpdateUserChatDebugLoggingRequest struct {
+	DebugLoggingEnabled bool `json:"debug_logging_enabled"`
+}
+
+// ChatDebugStatus enumerates the lifecycle states shared by debug
+// runs and steps. These values must match the literals used in
+// FinalizeStaleChatDebugRows and all insert/update callers.
+type ChatDebugStatus string
+
+const (
+	ChatDebugStatusInProgress  ChatDebugStatus = "in_progress"
+	ChatDebugStatusCompleted   ChatDebugStatus = "completed"
+	ChatDebugStatusError       ChatDebugStatus = "error"
+	ChatDebugStatusInterrupted ChatDebugStatus = "interrupted"
+)
+
+// ChatDebugTerminalStatuses returns the statuses that represent a
+// finished lifecycle. The SQL query FinalizeStaleChatDebugRows uses
+// a NOT IN list that must match these exactly. A test in
+// coderd/database asserts this alignment at CI time.
+func ChatDebugTerminalStatuses() []ChatDebugStatus {
+	return []ChatDebugStatus{
+		ChatDebugStatusCompleted,
+		ChatDebugStatusError,
+		ChatDebugStatusInterrupted,
+	}
+}
+
+// ChatDebugRunKind labels the operation that produced the debug
+// run. Each value corresponds to a distinct call-site in chatd.
+type ChatDebugRunKind string
+
+const (
+	ChatDebugRunKindChatTurn        ChatDebugRunKind = "chat_turn"
+	ChatDebugRunKindTitleGeneration ChatDebugRunKind = "title_generation"
+	ChatDebugRunKindQuickgen        ChatDebugRunKind = "quickgen"
+	ChatDebugRunKindCompaction      ChatDebugRunKind = "compaction"
+)
+
+// ChatDebugStepOperation labels the model interaction type for a
+// debug step.
+type ChatDebugStepOperation string
+
+const (
+	ChatDebugStepOperationStream   ChatDebugStepOperation = "stream"
+	ChatDebugStepOperationGenerate ChatDebugStepOperation = "generate"
+)
+
+// ChatDebugRunSummary is a lightweight run entry for list endpoints.
+type ChatDebugRunSummary struct {
+	ID         uuid.UUID        `json:"id" format:"uuid"`
+	ChatID     uuid.UUID        `json:"chat_id" format:"uuid"`
+	Kind       ChatDebugRunKind `json:"kind"`
+	Status     ChatDebugStatus  `json:"status"`
+	Provider   *string          `json:"provider,omitempty"`
+	Model      *string          `json:"model,omitempty"`
+	Summary    map[string]any   `json:"summary"`
+	StartedAt  time.Time        `json:"started_at" format:"date-time"`
+	UpdatedAt  time.Time        `json:"updated_at" format:"date-time"`
+	FinishedAt *time.Time       `json:"finished_at,omitempty" format:"date-time"`
+}
+
+// ChatDebugRun is the detailed run response including steps.
+// This type is consumed by the run-detail handler added in a later
+// PR in this stack; it is forward-declared here so that all SDK
+// types live in the same schema-layer commit.
+type ChatDebugRun struct {
+	ID                  uuid.UUID        `json:"id" format:"uuid"`
+	ChatID              uuid.UUID        `json:"chat_id" format:"uuid"`
+	RootChatID          *uuid.UUID       `json:"root_chat_id,omitempty" format:"uuid"`
+	ParentChatID        *uuid.UUID       `json:"parent_chat_id,omitempty" format:"uuid"`
+	ModelConfigID       *uuid.UUID       `json:"model_config_id,omitempty" format:"uuid"`
+	TriggerMessageID    *int64           `json:"trigger_message_id,omitempty"`
+	HistoryTipMessageID *int64           `json:"history_tip_message_id,omitempty"`
+	Kind                ChatDebugRunKind `json:"kind"`
+	Status              ChatDebugStatus  `json:"status"`
+	Provider            *string          `json:"provider,omitempty"`
+	Model               *string          `json:"model,omitempty"`
+	Summary             map[string]any   `json:"summary"`
+	StartedAt           time.Time        `json:"started_at" format:"date-time"`
+	UpdatedAt           time.Time        `json:"updated_at" format:"date-time"`
+	FinishedAt          *time.Time       `json:"finished_at,omitempty" format:"date-time"`
+	Steps               []ChatDebugStep  `json:"steps"`
+}
+
+// ChatDebugStep is a single step within a debug run.
+type ChatDebugStep struct {
+	ID                  uuid.UUID              `json:"id" format:"uuid"`
+	RunID               uuid.UUID              `json:"run_id" format:"uuid"`
+	ChatID              uuid.UUID              `json:"chat_id" format:"uuid"`
+	StepNumber          int32                  `json:"step_number"`
+	Operation           ChatDebugStepOperation `json:"operation"`
+	Status              ChatDebugStatus        `json:"status"`
+	HistoryTipMessageID *int64                 `json:"history_tip_message_id,omitempty"`
+	AssistantMessageID  *int64                 `json:"assistant_message_id,omitempty"`
+	NormalizedRequest   map[string]any         `json:"normalized_request"`
+	NormalizedResponse  map[string]any         `json:"normalized_response,omitempty"`
+	Usage               map[string]any         `json:"usage,omitempty"`
+	Attempts            []map[string]any       `json:"attempts"`
+	Error               map[string]any         `json:"error,omitempty"`
+	Metadata            map[string]any         `json:"metadata"`
+	StartedAt           time.Time              `json:"started_at" format:"date-time"`
+	UpdatedAt           time.Time              `json:"updated_at" format:"date-time"`
+	FinishedAt          *time.Time             `json:"finished_at,omitempty" format:"date-time"`
+}
+
 // DefaultChatWorkspaceTTL is the default TTL for chat workspaces.
 // Zero means disabled — the template's own autostop setting applies.
 const DefaultChatWorkspaceTTL = 0

codersdk/deployment.go

@@ -3624,6 +3624,16 @@ Write out the current server config as YAML to stdout.`,
 			YAML:        "acquireBatchSize",
 			Hidden:      true, // Hidden because most operators should not need to modify this.
 		},
+		{
+			Name:        "Chat: Debug Logging Enabled",
+			Description: "Force chat debug logging on for every chat, bypassing the runtime admin and user opt-in settings.",
+			Flag:        "chat-debug-logging-enabled",
+			Env:         "CODER_CHAT_DEBUG_LOGGING_ENABLED",
+			Value:       &c.AI.Chat.DebugLoggingEnabled,
+			Default:     "false",
+			Group:       &deploymentGroupChat,
+			YAML:        "debugLoggingEnabled",
+		},
 		// AI Bridge Options
 		{
 			Name:        "AI Bridge Enabled",
@@ -4090,7 +4100,8 @@ type AIBridgeProxyConfig struct {
 }
 
 type ChatConfig struct {
-	AcquireBatchSize serpent.Int64 `json:"acquire_batch_size" typescript:",notnull"`
+	AcquireBatchSize    serpent.Int64 `json:"acquire_batch_size" typescript:",notnull"`
+	DebugLoggingEnabled serpent.Bool  `json:"debug_logging_enabled" typescript:",notnull"`
 }
 
 type AIConfig struct {