fix: add validation for model ID type assertion and improve code documentation

- Add validation before type assertion in claude-code.ts to ensure model ID is valid
- Add comprehensive JSDoc comments for convertModelNameForVertex and getClaudeCodeModelId functions
- Extract regex pattern as named constant VERTEX_DATE_PATTERN for better maintainability

Author: daniel-lxs

packages/types/src/providers/claude-code.ts

@@ -1,17 +1,40 @@
 import type { ModelInfo } from "../model.js"
 import { anthropicModels } from "./anthropic.js"
 
-// Utility function to convert model names for Vertex AI format
+// Regex pattern to match 8-digit date at the end of model names
+const VERTEX_DATE_PATTERN = /-(\d{8})$/
+
+/**
+ * Converts Claude model names from hyphen-date format to Vertex AI's @-date format.
+ *
+ * @param modelName - The original model name (e.g., "claude-sonnet-4-20250514")
+ * @returns The converted model name for Vertex AI (e.g., "claude-sonnet-4@20250514")
+ *
+ * @example
+ * convertModelNameForVertex("claude-sonnet-4-20250514") // returns "claude-sonnet-4@20250514"
+ * convertModelNameForVertex("claude-model") // returns "claude-model" (no change)
+ */
 export function convertModelNameForVertex(modelName: string): string {
 	// Convert hyphen-date format to @date format for Vertex AI
-	return modelName.replace(/-(\d{8})$/, "@$1")
+	return modelName.replace(VERTEX_DATE_PATTERN, "@$1")
 }
 
 // Claude Code
 export type ClaudeCodeModelId = keyof typeof claudeCodeModels
 export const claudeCodeDefaultModelId: ClaudeCodeModelId = "claude-sonnet-4-20250514"
 export const CLAUDE_CODE_DEFAULT_MAX_OUTPUT_TOKENS = 8000
-// Helper function to get model ID based on environment
+
+/**
+ * Gets the appropriate model ID based on whether Vertex AI is being used.
+ *
+ * @param baseModelId - The base Claude Code model ID
+ * @param useVertex - Whether to format the model ID for Vertex AI (default: false)
+ * @returns The model ID, potentially formatted for Vertex AI
+ *
+ * @example
+ * getClaudeCodeModelId("claude-sonnet-4-20250514", true) // returns "claude-sonnet-4@20250514"
+ * getClaudeCodeModelId("claude-sonnet-4-20250514", false) // returns "claude-sonnet-4-20250514"
+ */
 export function getClaudeCodeModelId(baseModelId: ClaudeCodeModelId, useVertex = false): string {
 	return useVertex ? convertModelNameForVertex(baseModelId) : baseModelId
 }

src/api/providers/claude-code.ts

@@ -27,11 +27,16 @@ export class ClaudeCodeHandler extends BaseProvider implements ApiHandler {
 		const filteredMessages = filterMessagesForClaudeCode(messages)
 
 		const useVertex = process.env.CLAUDE_CODE_USE_VERTEX?.toLowerCase() === "true"
+		const model = this.getModel()
+
+		// Validate that the model ID is a valid ClaudeCodeModelId
+		const modelId = model.id in claudeCodeModels ? (model.id as ClaudeCodeModelId) : claudeCodeDefaultModelId
+
 		const claudeProcess = runClaudeCode({
 			systemPrompt,
 			messages: filteredMessages,
 			path: this.options.claudeCodePath,
-			modelId: getClaudeCodeModelId(this.getModel().id as ClaudeCodeModelId, useVertex),
+			modelId: getClaudeCodeModelId(modelId, useVertex),
 			maxOutputTokens: this.options.claudeCodeMaxOutputTokens,
 		})