Refactor db pkg

internal/db/models.go

@@ -2,23 +2,64 @@ package db
 
 import "time"
 
-// ApprovalStatus defines the lifecycle states for a tool call approval.
-type ApprovalStatus string
+// ExecutionStatus is the state of one tool call, as stored in the executions
+// table (one row for every tool call in an assistant message).
+//
+// The row tracks the call's lifecycle; it does not store the call's
+// outcome. The outcome lives in a tool result message row in the messages
+// table, matched to the call by tool_call_id.
+//
+// Lifecycle, by tool kind:
+//
+// A. Approval not required:
+//
+//	┌────────────┐    ┌────────────┐
+//	│  running   ├┄┄┄▶│ completed  │
+//	└────────────┘    └────────────┘
+//
+// B. Approval required:
+//
+//	┌────────────┐    ┌────────────┐    ┌────────────┐    ┌────────────┐
+//	│  pending   ├───▶│  approved  ├───▶│  running   ├┄┄┄▶│ completed  │
+//	└────────────┘    └────────────┘    └────────────┘    └────────────┘
+//	      │
+//	      ▼
+//	┌────────────┐
+//	│   denied   │
+//	└────────────┘
+//
+// The dashed arrow from running to completed indicates the possibility that a
+// tool call may not complete. if a tool call is interrupted, the row ends at
+// running. See [ExecutionStatusRunning].
+type ExecutionStatus string
 
 const (
-	ApprovalStatusApproved ApprovalStatus = "approved"
-	ApprovalStatusDenied   ApprovalStatus = "denied"
-	ApprovalStatusPending  ApprovalStatus = "pending"
+	// ExecutionStatusApproved: tool call approved by user.
+	// The call has not launched yet.
+	ExecutionStatusApproved ExecutionStatus = "approved"
+	// ExecutionStatusCompleted: the tool call returned output or an error.
+	// Terminal.
+	ExecutionStatusCompleted ExecutionStatus = "completed"
+	// ExecutionStatusDenied: user refused the tool call. Terminal.
+	ExecutionStatusDenied ExecutionStatus = "denied"
+	// ExecutionStatusPending: the call awaits a user decision.
+	ExecutionStatusPending ExecutionStatus = "pending"
+	// ExecutionStatusRunning: the tool call either:
+	// A. is about to be started,
+	// B. was started and is still executing,
+	// C. was interrupted before it started or finished (terminal).
+	ExecutionStatusRunning ExecutionStatus = "running"
 )
 
-// Approval represents a tool call awaiting or resolved by user permission.
-type Approval struct {
-	CreatedAt  time.Time      `json:"created_at"`
-	Id         string         `json:"id"`
-	MessageId  string         `json:"message_id"`
-	Status     ApprovalStatus `json:"status"`
-	ToolCallId string         `json:"tool_call_id"`
-	UpdatedAt  time.Time      `json:"updated_at"`
+// Execution represents a row in the executions table: one tool call
+// within an assistant message and its current state.
+type Execution struct {
+	CreatedAt  time.Time       `json:"created_at"`
+	Id         string          `json:"id"`
+	MessageId  string          `json:"message_id"`
+	Status     ExecutionStatus `json:"status"`
+	ToolCallId string          `json:"tool_call_id"`
+	UpdatedAt  time.Time       `json:"updated_at"`
 }
 
 // Conversation represents a stored conversation.