feat: add runner failover rules and cache affinity

apps/api/internal/clients/clients_test.go

@@ -302,7 +302,7 @@ func TestOpenAIClientChatContract(t *testing.T) {
 			"choices": []any{map[string]any{
 				"message": map[string]any{"role": "assistant", "content": "ok"},
 			}},
-			"usage": map[string]any{"prompt_tokens": 3, "completion_tokens": 2, "total_tokens": 5},
+			"usage": map[string]any{"prompt_tokens": 3, "completion_tokens": 2, "total_tokens": 5, "prompt_cache_hit_tokens": 2},
 		})
 	}))
 	defer server.Close()
@@ -327,6 +327,14 @@ func TestOpenAIClientChatContract(t *testing.T) {
 	if response.Usage.TotalTokens != 5 || response.Result["id"] != "chatcmpl-test" {
 		t.Fatalf("unexpected response: %+v", response)
 	}
+	if response.Usage.CachedInputTokens != 2 {
+		t.Fatalf("expected cached input token usage, got %+v", response.Usage)
+	}
+	resultUsage, _ := response.Result["usage"].(map[string]any)
+	promptDetails, _ := resultUsage["prompt_tokens_details"].(map[string]any)
+	if intFromAny(promptDetails["cached_tokens"]) != 2 {
+		t.Fatalf("expected normalized cached prompt tokens in result usage, got %+v", resultUsage)
+	}
 	if response.RequestID != "req-chat-test" || response.ResponseStartedAt.IsZero() || response.ResponseFinishedAt.IsZero() {
 		t.Fatalf("response metadata was not captured: %+v", response)
 	}
@@ -335,6 +343,29 @@ func TestOpenAIClientChatContract(t *testing.T) {
 	}
 }
 
+func TestUsageFromOpenAIUsageTracksKnownCachedInputZero(t *testing.T) {
+	knownZero := usageFromOpenAIUsage(map[string]any{
+		"prompt_tokens":     100,
+		"completion_tokens": 10,
+		"total_tokens":      110,
+		"prompt_tokens_details": map[string]any{
+			"cached_tokens": 0,
+		},
+	})
+	if !knownZero.CachedInputTokensKnown || knownZero.CachedInputTokens != 0 {
+		t.Fatalf("expected known zero cached input tokens, got %+v", knownZero)
+	}
+
+	absent := usageFromOpenAIUsage(map[string]any{
+		"prompt_tokens":     100,
+		"completion_tokens": 10,
+		"total_tokens":      110,
+	})
+	if absent.CachedInputTokensKnown {
+		t.Fatalf("expected missing cached field to remain unknown, got %+v", absent)
+	}
+}
+
 func TestOpenAIClientEmbeddingsContract(t *testing.T) {
 	var gotPath string
 	var gotModel string