refactor: eliminate code duplication with shared utilities

Created 5 new utility modules in apps/server/src/lib/ to eliminate ~320 lines of duplicated code:
- image-handler.ts: Centralized image processing (MIME types, base64, content blocks)
- prompt-builder.ts: Standardized prompt building with image attachments
- model-resolver.ts: Model alias resolution and provider routing
- conversation-utils.ts: Conversation history processing for providers
- error-handler.ts: Error classification and user-friendly messages

Updated services and providers to use shared utilities:
- agent-service.ts: -51 lines (removed duplicate image handling, model logic)
- auto-mode-service.ts: -75 lines (removed MODEL_MAP, duplicate utilities)
- claude-provider.ts: -10 lines (uses conversation-utils)
- codex-provider.ts: -5 lines (uses conversation-utils)

Added comprehensive documentation:
- docs/server/utilities.md: Complete reference for all 9 lib utilities
- docs/server/providers.md: Provider architecture guide with examples

Benefits:
- Single source of truth for critical business logic
- Improved maintainability and testability
- Consistent behavior across services and providers
- Better documentation for future development

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

apps/server/src/lib/model-resolver.ts

@@ -0,0 +1,88 @@
+/**
+ * Model resolution utilities for handling model string mapping
+ *
+ * Provides centralized model resolution logic:
+ * - Maps Claude model aliases to full model strings
+ * - Detects and passes through OpenAI/Codex models
+ * - Provides default models per provider
+ * - Handles multiple model sources with priority
+ */
+
+/**
+ * Model alias mapping for Claude models
+ */
+export const CLAUDE_MODEL_MAP: Record<string, string> = {
+  haiku: "claude-haiku-4-5",
+  sonnet: "claude-sonnet-4-20250514",
+  opus: "claude-opus-4-5-20251101",
+} as const;
+
+/**
+ * Default models per provider
+ */
+export const DEFAULT_MODELS = {
+  claude: "claude-opus-4-5-20251101",
+  openai: "gpt-5.2",
+} as const;
+
+/**
+ * Resolve a model key/alias to a full model string
+ *
+ * @param modelKey - Model key (e.g., "opus", "gpt-5.2", "claude-sonnet-4-20250514")
+ * @param defaultModel - Fallback model if modelKey is undefined
+ * @returns Full model string
+ */
+export function resolveModelString(
+  modelKey?: string,
+  defaultModel: string = DEFAULT_MODELS.claude
+): string {
+  // No model specified - use default
+  if (!modelKey) {
+    return defaultModel;
+  }
+
+  // OpenAI/Codex models - pass through unchanged
+  if (modelKey.startsWith("gpt-") || modelKey.startsWith("o")) {
+    console.log(`[ModelResolver] Using OpenAI/Codex model: ${modelKey}`);
+    return modelKey;
+  }
+
+  // Full Claude model string - pass through unchanged
+  if (modelKey.includes("claude-")) {
+    console.log(`[ModelResolver] Using full Claude model string: ${modelKey}`);
+    return modelKey;
+  }
+
+  // Look up Claude model alias
+  const resolved = CLAUDE_MODEL_MAP[modelKey];
+  if (resolved) {
+    console.log(`[ModelResolver] Resolved model alias: "${modelKey}" -> "${resolved}"`);
+    return resolved;
+  }
+
+  // Unknown model key - use default
+  console.warn(
+    `[ModelResolver] Unknown model key "${modelKey}", using default: "${defaultModel}"`
+  );
+  return defaultModel;
+}
+
+/**
+ * Get the effective model from multiple sources
+ * Priority: explicit model > session model > default
+ *
+ * @param explicitModel - Explicitly provided model (highest priority)
+ * @param sessionModel - Model from session (medium priority)
+ * @param defaultModel - Fallback default model (lowest priority)
+ * @returns Resolved model string
+ */
+export function getEffectiveModel(
+  explicitModel?: string,
+  sessionModel?: string,
+  defaultModel?: string
+): string {
+  return resolveModelString(
+    explicitModel || sessionModel,
+    defaultModel
+  );
+}