@extentos/mcp-server 0.0.77 → 0.0.79

package/dist/tools/data/codeExamples.js

@@ -57,17 +57,23 @@ class CoachHandler(
                 val question = recording.transcript.trim()
                 if (question.isEmpty() || "stop" in question.lowercase()) break
 
-                // ask() returns LlmResult. Pattern-match so AuthFailure,
-                // NetworkError, and Empty each speak a distinct line — the
-                // F-R2-10 bug was collapsing all three into one message.
+                // ask() returns LlmResult — 6 variants, each with its own
+                // user-facing message. F-R2-10 + F-R3-10: collapsing any of
+                // them into one "try again" line confuses users (was it
+                // wifi? key? the AI?) and the debugging agent (is retry
+                // going to help?). Compile-time exhaustive \`when\` makes
+                // adding a new variant break every caller until they
+                // handle it explicitly.
                 val spoken = when (val r = anthropic.ask(
                     question = question,
                     workoutHistory = workouts.recent(),
                 )) {
-                    is LlmResult.Ok       -> r.text
-                    LlmResult.AuthFailure -> "Your Anthropic key isn't set up — add it to local.properties and rebuild."
-                    LlmResult.NetworkError -> "I couldn't reach the AI. Try again."
-                    LlmResult.Empty       -> "I didn't get an answer. Try rephrasing."
+                    is LlmResult.Ok        -> r.text
+                    LlmResult.AuthFailure  -> "Your Anthropic key isn't set up — add it to local.properties and rebuild."
+                    LlmResult.Connectivity -> "I can't reach the network. Check your connection."
+                    LlmResult.Transient    -> "The AI is slow right now — try again in a moment."
+                    LlmResult.ClientBug    -> "Something's off with the request — check logcat AnthropicClient:E."
+                    LlmResult.Empty        -> "I didn't get an answer. Try rephrasing."
                 }
                 glasses.audio.speak(spoken)
             }
@@ -114,15 +120,19 @@ class CoachHandler(
             let question = recording.transcript.trimmingCharacters(in: .whitespaces)
             if question.isEmpty || question.lowercased().contains("stop") { break }
 
-            // ask() returns LlmResult. Switch so AuthFailure, NetworkError,
-            // and Empty each speak a distinct line — the F-R2-10 bug was
-            // collapsing all three into one user-facing message.
+            // ask() returns LlmResult — 6 variants, each with its own
+            // user-facing message. F-R2-10 + F-R3-10: collapsing any of
+            // them into one "try again" line confuses users and the
+            // debugging agent. Exhaustive switch breaks compilation if a
+            // new variant is added — that's the point.
             let spoken: String
             switch await anthropic.ask(question: question, workoutHistory: workouts.recent()) {
-            case .ok(let text):  spoken = text
-            case .authFailure:   spoken = "Your Anthropic key isn't set up — check Info.plist."
-            case .networkError:  spoken = "I couldn't reach the AI. Try again."
-            case .empty:         spoken = "I didn't get an answer. Try rephrasing."
+            case .ok(let text):   spoken = text
+            case .authFailure:    spoken = "Your Anthropic key isn't set up — check Info.plist."
+            case .connectivity:   spoken = "I can't reach the network. Check your connection."
+            case .transient:      spoken = "The AI is slow right now — try again in a moment."
+            case .clientBug:      spoken = "Something's off with the request — check OSLog AnthropicClient."
+            case .empty:          spoken = "I didn't get an answer. Try rephrasing."
             }
             _ = await glasses.audio.speak(spoken)
         }
@@ -144,7 +154,7 @@ class CoachHandler(
         "speak() blocks until done by default. If you want speak + listen-for-barge-in simultaneously, see the barge_in_speak pattern.",
         "BuildConfig API-key fields don't reflect rotations because kotlinc inlines them at compile time. Use resValue / R.string.X for Android secrets. See getCredentialGuide.",
         "AnthropicClient is a USER-PROVIDED stub — there's no first-party Anthropic Kotlin SDK. Use getCodeExample('byok_anthropic') for a paste-ready minimal OkHttp / URLSession wrapper around POST /v1/messages, and getCredentialGuide('anthropic') for the key-storage pattern. WorkoutRepository is your app's existing data layer — swap in whatever shape your app uses.",
-        "ask() returns LlmResult, not String. Pattern-match each failure mode (AuthFailure, NetworkError, Empty) into a distinct spoken line — flattening them is the R2 F-R2-10 finding (user can't distinguish 'fix your key' from 'AI didn't understand').",
+        "ask() returns LlmResult — 6 variants: Ok / AuthFailure / Connectivity / Transient / ClientBug / Empty. Pattern-match each into a distinct spoken line. R2 F-R2-10 + R3 F-R3-10: collapsing them obscures both the user's remediation (was it wifi? key? AI?) and the debugging agent's signal (was a retry going to help?).",
     ],
     relatedFeatures: ["voice_command", "transcription_incremental", "record_audio"],
 };
@@ -276,10 +286,12 @@ class VisionHandler(
                 mediaType = mediaType,
                 prompt = "Describe this scene briefly, conversationally.",
             )) {
-                is LlmResult.Ok       -> r.text
-                LlmResult.AuthFailure -> "Your Anthropic key isn't set up — add it to local.properties and rebuild."
-                LlmResult.NetworkError -> "I couldn't reach the vision service. Try again."
-                LlmResult.Empty       -> "I couldn't describe that one. Try a different angle."
+                is LlmResult.Ok        -> r.text
+                LlmResult.AuthFailure  -> "Your Anthropic key isn't set up — add it to local.properties and rebuild."
+                LlmResult.Connectivity -> "I can't reach the network. Check your connection."
+                LlmResult.Transient    -> "The vision service is slow right now — try again in a moment."
+                LlmResult.ClientBug    -> "Something's off with the request — check logcat AnthropicClient:E."
+                LlmResult.Empty        -> "I couldn't describe that one. Try a different angle."
             }
             glasses.audio.speak(spoken)
         }
@@ -319,14 +331,17 @@ class VisionHandler(
             // your vision LLM however it expects them (base64, Data).
             let image = await photo.loadImage()
             // describe() returns LlmResult — switch so each failure mode
-            // gets the right user-facing message. Folding all three into
-            // one "I couldn't describe that one." is the F-R2-10 bug.
+            // gets the right user-facing message. F-R2-10 + F-R3-10:
+            // collapsing variants into one line confuses both users and
+            // the debugging agent.
             let spoken: String
             switch await vision.describe(image: image, prompt: "Describe this scene briefly, conversationally.") {
-            case .ok(let text):  spoken = text
-            case .authFailure:   spoken = "Your Anthropic key isn't set up — check Info.plist."
-            case .networkError:  spoken = "I couldn't reach the vision service. Try again."
-            case .empty:         spoken = "I couldn't describe that one. Try a different angle."
+            case .ok(let text):   spoken = text
+            case .authFailure:    spoken = "Your Anthropic key isn't set up — check Info.plist."
+            case .connectivity:   spoken = "I can't reach the network. Check your connection."
+            case .transient:      spoken = "The vision service is slow right now — try again in a moment."
+            case .clientBug:      spoken = "Something's off with the request — check OSLog AnthropicClient."
+            case .empty:          spoken = "I couldn't describe that one. Try a different angle."
             }
             _ = await glasses.audio.speak(spoken)
         }
@@ -343,7 +358,7 @@ class VisionHandler(
         "Android: Photos.loadBase64(uri) bridges both data: and file: URIs into bytes ready for Claude Vision / GPT-4V request bodies. iOS: `photo.loadImage()` (extension on Photo) returns a UIImage; for base64 you encode the JPEG/PNG data yourself via Data.base64EncodedString().",
         "Vision LLM response time is 2-8 seconds p95; the user is staring at the glasses waiting. Consider an earcon (`glasses.audio.earcon(EarconSound.START)`) at capture time so they know it worked.",
         "VisionClient is a USER-PROVIDED stub — see getCodeExample('byok_anthropic') for the canonical Anthropic Claude Vision wrapper (request shape: content blocks with type:image / source:base64 + type:text). The byok_anthropic pattern is paste-ready in both Kotlin and Swift.",
-        "describe() returns LlmResult, not String. Pattern-match (Kotlin `when` / Swift `switch`) so AuthFailure, NetworkError, and Empty each get a distinct user-facing line. The R2 dogfood showed users hearing 'I couldn't describe that one.' equally for 'API key not set' and 'AI was unsure' — the sealed type forces the agent to give each its own message.",
+        "describe() returns LlmResult — 6 variants: Ok / AuthFailure / Connectivity / Transient / ClientBug / Empty. Pattern-match (Kotlin `when` / Swift `switch`) each into a distinct user-facing line. The R2 dogfood showed users hearing 'I couldn't describe that one.' equally for 'API key not set' and 'AI was unsure'; R3 added the 502-vs-DNS gap. The sealed type forces the agent to give each its own message AND lets the built-in retry loop handle Transient / Connectivity transparently before they surface to your handler.",
     ],
     relatedFeatures: ["capture_photo", "voice_command", "transcription_incremental"],
 };
@@ -580,11 +595,13 @@ struct ContentView: View {
 };
 const BYOK_ANTHROPIC = {
     pattern: "byok_anthropic",
-    title: "BYOK Anthropic Claude API client (text + Vision, OkHttp / URLSession)",
-    description: "Minimal AnthropicClient that voice_qa_assistant and photo_describe_voice reference. Two methods: `ask(question, history)` for text-only Q&A, `describe(imageBase64, mediaType, prompt)` for Claude Vision (image content blocks). There is no first-party Anthropic Kotlin SDK; this is the canonical OkHttp + kotlinx.serialization wrapper around POST /v1/messages. iOS uses URLSession + Codable. Paste, then wire the API key through resValue (Android) / Info.plist (iOS) per getCredentialGuide.",
+    title: "BYOK Anthropic Claude API client (text + Vision, OkHttp / URLSession, with retry + observability)",
+    description: "Minimal AnthropicClient that voice_qa_assistant and photo_describe_voice reference. Two methods: `ask(question, history)` for text-only Q&A, `describe(imageBase64, mediaType, prompt)` for Claude Vision (image content blocks). There is no first-party Anthropic Kotlin SDK; this is the canonical OkHttp + kotlinx.serialization wrapper around POST /v1/messages. iOS uses URLSession + Codable. Returns LlmResult (Ok / AuthFailure / Connectivity / Transient / ClientBug / Empty) — distinct failure variants for distinct user-facing remediations. Built-in retry-with-backoff (200ms / 800ms / 3.2s, 3 attempts) for Transient (429 + 5xx) and Connectivity (IOException) failures so most upstream blips never reach the caller. Optional `observability: glasses.observability` wiring — pass it and every call surfaces under getEventLog's 'ai' filter chip. Paste, then wire the API key through resValue (Android) / Info.plist (iOS) per getCredentialGuide.",
     code: {
-        kotlin: `import java.io.IOException
+        kotlin: `import com.extentos.glasses.core.ObservabilityClient
+import java.io.IOException
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.withContext
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
@@ -608,27 +625,42 @@ import okhttp3.RequestBody.Companion.toRequestBody
  * exhaustively checked by the compiler — adding a new variant forces
  * every handler to acknowledge the new case.
  *
- * The four variants distinguish failure modes that produce the SAME
- * empty-string symptom if you collapse them, and that need DIFFERENT
- * user-facing responses on a voice-glasses app:
- *   Ok          — speak / display the text.
- *   AuthFailure — key missing, invalid, or no billing. Actionable by the
- *                 dev (rotate / configure the key); not actionable by
- *                 the user. UX: "Your Anthropic key isn't set up."
- *   NetworkError— transient (no internet, DNS, timeout, 429 rate-limit,
- *                 5xx server). UX: "Try again in a moment."
- *   Empty       — 2xx with no text content. Usually means the model
- *                 couldn't make sense of the input. UX: "I couldn't
- *                 describe that one."
+ * F-R3-10 splits the previous \`NetworkError\` lump into three failure
+ * modes that have DIFFERENT remediations — collapsing them into one
+ * "try again" message confuses both the user (was it wifi? was it the
+ * AI?) and the agent debugging the flow (is retry-with-backoff going
+ * to help?).
  *
- * R2 dogfood F-R2-10: returning bare String collapses all three failure
- * modes into "" and the user hears the same recorded message for every
- * one — they can't tell "fix your key" from "the AI didn't understand".
+ *   Ok            — speak / display the text.
+ *   AuthFailure   — 401/403 OR blank key. Actionable by the dev (rotate
+ *                   / configure the key); not by the user. Never retried.
+ *                   UX: "Your Anthropic key isn't set up."
+ *   Connectivity  — IOException (DNS / no internet / TLS / socket
+ *                   timeout). Retry won't help until network returns.
+ *                   UX: "I can't reach the network — check your connection."
+ *   Transient     — 429 rate-limit OR 5xx server error. RETRIED inside
+ *                   post() with exponential backoff (200ms / 800ms /
+ *                   3.2s). If still failing after the retry budget,
+ *                   surfaces as this variant. UX: "The AI is slow right
+ *                   now — try again in a moment."
+ *   ClientBug     — 400 / 404 / 422 / any 4xx that isn't 401/403/429.
+ *                   The request itself is malformed; retry will never
+ *                   fix it. Surface loud in logs; UX is best-effort:
+ *                   "Something's off with the request" + log it for the
+ *                   dev to investigate.
+ *   Empty         — 2xx with no text content. Model couldn't make sense
+ *                   of the input. UX: "I couldn't describe that one."
+ *
+ * R2 dogfood F-R2-10 + R3 dogfood F-R3-10: bare String / single
+ * NetworkError variant produced the same user-facing message regardless
+ * of cause.
  */
 sealed interface LlmResult {
     data class Ok(val text: String) : LlmResult
     data object AuthFailure : LlmResult
-    data object NetworkError : LlmResult
+    data object Connectivity : LlmResult
+    data object Transient : LlmResult
+    data object ClientBug : LlmResult
     data object Empty : LlmResult
 }
 
@@ -637,6 +669,23 @@ class AnthropicClient(
     private val model: String = "claude-opus-4-7",
     private val maxTokens: Int = 1024,
     private val client: OkHttpClient = OkHttpClient(),
+    /**
+     * Optional: when provided, every ask() / describe() call is wrapped
+     * via observability.aiCall("anthropic.<method>") so it appears in
+     * getEventLog under the "ai" filter chip. Pass \`glasses.observability\`
+     * from your ExtentosGlasses instance. Default null = no wrapping
+     * (call is invisible to the simulator event log; you'll need adb
+     * logcat to diagnose failures).
+     */
+    private val observability: ObservabilityClient? = null,
+    /**
+     * Retry budget for Transient (5xx, 429) and Connectivity (IOException)
+     * failures. Each retry waits longer (200ms → 800ms → 3.2s). After
+     * the budget is exhausted the failure surfaces as a variant.
+     * Default 3 attempts total (initial + 2 retries) cap end-to-end at
+     * ~1.2s if all transient.
+     */
+    private val maxAttempts: Int = 3,
 ) {
     private val json = Json { ignoreUnknownKeys = true; encodeDefaults = true }
 
@@ -676,14 +725,16 @@ class AnthropicClient(
     /** Text-only Q&A. Anthropic's content field accepts either a bare String or a
      *  list of ContentBlock; we use the list shape so this client can also do Vision. */
     suspend fun ask(question: String, history: List<String> = emptyList()): LlmResult =
-        post(
-            messages = buildList {
-                for (turn in history) {
-                    add(Message("user", listOf(ContentBlock.Text(turn))))
-                }
-                add(Message("user", listOf(ContentBlock.Text(question))))
-            },
-        )
+        wrap("anthropic.ask") {
+            post(
+                messages = buildList {
+                    for (turn in history) {
+                        add(Message("user", listOf(ContentBlock.Text(turn))))
+                    }
+                    add(Message("user", listOf(ContentBlock.Text(question))))
+                },
+            )
+        }
 
     /** Vision: send one image (base64) + a text prompt. Use Photos.loadBase64(uri) and
      *  Photos.mediaTypeFromUri(uri) (from com.extentos.glasses.core.Photos) to source
@@ -693,83 +744,147 @@ class AnthropicClient(
         mediaType: String,
         prompt: String,
         system: String? = null,
-    ): LlmResult = post(
-        messages = listOf(
-            Message(
-                "user",
-                listOf(
-                    ContentBlock.Image(ImageSource(mediaType = mediaType, data = imageBase64)),
-                    ContentBlock.Text(prompt),
+    ): LlmResult = wrap("anthropic.describe", mapOf("media_type" to mediaType)) {
+        post(
+            messages = listOf(
+                Message(
+                    "user",
+                    listOf(
+                        ContentBlock.Image(ImageSource(mediaType = mediaType, data = imageBase64)),
+                        ContentBlock.Text(prompt),
+                    ),
                 ),
             ),
-        ),
-        system = system,
-    )
+            system = system,
+        )
+    }
 
-    // ---- Transport ----
+    // ---- Wrap each call in observability.aiCall when wired ----
+
+    private suspend fun wrap(
+        label: String,
+        metadata: Map<String, String> = emptyMap(),
+        block: suspend () -> LlmResult,
+    ): LlmResult {
+        val obs = observability ?: return block()
+        val baseMeta = buildMap {
+            put("model", model)
+            putAll(metadata)
+        }
+        return obs.aiCall(label, baseMeta) { block() }
+    }
 
-    private suspend fun post(messages: List<Message>, system: String? = null): LlmResult =
-        withContext(Dispatchers.IO) {
-            if (apiKey.isBlank()) return@withContext LlmResult.AuthFailure
-            val body = json.encodeToString(
-                Req.serializer(),
-                Req(model = model, maxTokens = maxTokens, messages = messages, system = system),
-            )
-            val request = Request.Builder()
-                .url("https://api.anthropic.com/v1/messages")
-                .header("x-api-key", apiKey)
-                .header("anthropic-version", "2023-06-01")
-                .header("content-type", "application/json")
-                .post(body.toRequestBody("application/json".toMediaType()))
-                .build()
-            try {
-                client.newCall(request).execute().use { response ->
-                    val payload = response.body?.string().orEmpty()
-                    when {
-                        // 401/403: invalid / missing key, no billing on the
-                        // account. Caller fixes config; user can't.
-                        response.code == 401 || response.code == 403 -> {
-                            android.util.Log.w("AnthropicClient", "Auth failure (\${response.code}): \${payload.take(500)}")
-                            LlmResult.AuthFailure
-                        }
-                        // 429 + 5xx + any other non-2xx: transient from the
-                        // app's perspective. Retry-with-backoff is the right
-                        // strategy; the user-facing message is "try again".
-                        !response.isSuccessful -> {
-                            android.util.Log.w("AnthropicClient", "HTTP \${response.code}: \${payload.take(500)}")
-                            LlmResult.NetworkError
-                        }
-                        else -> {
-                            val text = json.decodeFromString(Res.serializer(), payload)
-                                .content.firstOrNull { it.type == "text" }?.text.orEmpty().trim()
-                            if (text.isEmpty()) LlmResult.Empty else LlmResult.Ok(text)
-                        }
+    // ---- Transport with retry-with-backoff ----
+
+    private suspend fun post(messages: List<Message>, system: String? = null): LlmResult {
+        if (apiKey.isBlank()) return LlmResult.AuthFailure
+        val body = json.encodeToString(
+            Req.serializer(),
+            Req(model = model, maxTokens = maxTokens, messages = messages, system = system),
+        )
+        var attempt = 0
+        var lastFailure: LlmResult = LlmResult.Transient
+        while (attempt < maxAttempts) {
+            val result = withContext(Dispatchers.IO) { postOnce(body) }
+            when (result) {
+                // Definitive outcomes — return immediately, no retry.
+                is LlmResult.Ok,
+                LlmResult.AuthFailure,
+                LlmResult.ClientBug,
+                LlmResult.Empty -> return result
+                // Retryable: hold onto the variant, back off, try again.
+                LlmResult.Transient,
+                LlmResult.Connectivity -> {
+                    lastFailure = result
+                    attempt++
+                    if (attempt < maxAttempts) {
+                        // 200ms, 800ms, 3.2s — geometric x4. Caps total
+                        // wait at 4.2s across 3 retries. Tune via
+                        // maxAttempts if your UX wants more / less.
+                        delay(200L * (1L shl (2 * (attempt - 1))))
                     }
                 }
-            } catch (e: IOException) {
-                // No HTTP exchange happened — DNS failure, no internet,
-                // socket timeout. Same UX as a transient 5xx.
-                android.util.Log.w("AnthropicClient", "Network error: \${e.message}")
-                LlmResult.NetworkError
             }
         }
+        return lastFailure
+    }
+
+    private fun postOnce(body: String): LlmResult {
+        val request = Request.Builder()
+            .url("https://api.anthropic.com/v1/messages")
+            .header("x-api-key", apiKey)
+            .header("anthropic-version", "2023-06-01")
+            .header("content-type", "application/json")
+            .post(body.toRequestBody("application/json".toMediaType()))
+            .build()
+        return try {
+            client.newCall(request).execute().use { response ->
+                val payload = response.body?.string().orEmpty()
+                when {
+                    // 401/403: invalid / missing key, no billing on the
+                    // account. Caller fixes config; user can't. Never retried.
+                    response.code == 401 || response.code == 403 -> {
+                        android.util.Log.w("AnthropicClient", "Auth failure (\${response.code}): \${payload.take(500)}")
+                        LlmResult.AuthFailure
+                    }
+                    // 429 + 5xx: retryable upstream blip. The wrapper
+                    // loops with backoff before this surfaces to the caller.
+                    response.code == 429 || response.code in 500..599 -> {
+                        android.util.Log.w("AnthropicClient", "Transient (\${response.code}): \${payload.take(500)}")
+                        LlmResult.Transient
+                    }
+                    // Other 4xx (400, 404, 422, …): malformed request.
+                    // Retry will never fix it; surface loud so the dev
+                    // sees the bug in their request shape.
+                    response.code in 400..499 -> {
+                        android.util.Log.e("AnthropicClient", "Client bug (\${response.code}): \${payload.take(500)}")
+                        LlmResult.ClientBug
+                    }
+                    !response.isSuccessful -> {
+                        // Catch-all for the few non-2xx outside 4xx/5xx
+                        // (1xx/3xx in practice). Treat as transient.
+                        android.util.Log.w("AnthropicClient", "Unexpected status (\${response.code}): \${payload.take(500)}")
+                        LlmResult.Transient
+                    }
+                    else -> {
+                        val text = json.decodeFromString(Res.serializer(), payload)
+                            .content.firstOrNull { it.type == "text" }?.text.orEmpty().trim()
+                        if (text.isEmpty()) LlmResult.Empty else LlmResult.Ok(text)
+                    }
+                }
+            }
+        } catch (e: IOException) {
+            // No HTTP exchange happened — DNS failure, no internet,
+            // socket timeout. UX is "check your connection," not "the
+            // AI is slow" — distinguish in the sealed type.
+            android.util.Log.w("AnthropicClient", "Connectivity: \${e.message}")
+            LlmResult.Connectivity
+        }
+    }
 }
 
 // Wire-up — your handler retrieves the API key from the resource string
 // emitted by your build.gradle.kts (see getCredentialGuide('anthropic')
 // for the resValue pattern), then passes it to a single client instance
-// held at Application scope. Both ask() and describe() return LlmResult;
-// pattern-match to give the user the right message per failure mode.
+// held at Application scope. Pass glasses.observability so each call
+// surfaces under getEventLog's "ai" filter (F-R3-11). Both ask() and
+// describe() return LlmResult; pattern-match to give the user the
+// right message per failure mode.
 //
 //   val apiKey = context.getString(R.string.anthropic_api_key)
-//   val anthropic = AnthropicClient(apiKey)
+//   val anthropic = AnthropicClient(
+//       apiKey = apiKey,
+//       observability = glasses.observability,   // surfaces in getEventLog "ai" chip
+//   )
 //
 //   // text:
 //   val spoken = when (val r = anthropic.ask("How many bench reps today?")) {
-//       is LlmResult.Ok    -> r.text
-//       LlmResult.AuthFailure -> "Your Anthropic key isn't set up — add it to local.properties and rebuild."
-//       LlmResult.NetworkError -> "I couldn't reach the AI. Try again."
-//       LlmResult.Empty    -> "I didn't get an answer. Try rephrasing."
+//       is LlmResult.Ok      -> r.text
+//       LlmResult.AuthFailure  -> "Your Anthropic key isn't set up — add it to local.properties and rebuild."
+//       LlmResult.Connectivity -> "I can't reach the network. Check your connection."
+//       LlmResult.Transient    -> "The AI is slow right now — try again in a moment."
+//       LlmResult.ClientBug    -> "Something's off with the request — check logcat AnthropicClient:E for the response body."
+//       LlmResult.Empty        -> "I didn't get an answer. Try rephrasing."
 //   }
 //   glasses.audio.speak(spoken)
 //
@@ -783,31 +898,41 @@ class AnthropicClient(
 //   val result = anthropic.describe(b64, mt, "What card is showing?")
 //   // when(result) { is LlmResult.Ok -> result.text; ...other cases... }`,
         swift: `import Foundation
+import GlassesCore
 
 /// Outcome of a single ask/describe call. Sealed via Swift enum so a
 /// \`switch result\` on this is exhaustively checked — adding a new
 /// case forces every handler to acknowledge it.
 ///
-/// The four cases distinguish failure modes that produce the SAME
-/// empty-string symptom if you flatten them, and that need DIFFERENT
-/// user-facing responses on a voice-glasses app:
-///   .ok          — speak / display the text.
-///   .authFailure — key missing, invalid, or no billing. Actionable by
-///                  the dev; not by the user. UX: "Your Anthropic key
-///                  isn't set up."
-///   .networkError— transient (no internet, DNS, timeout, 429, 5xx).
-///                  UX: "Try again in a moment."
-///   .empty       — 2xx with no text content. Usually means the model
-///                  couldn't make sense of the input. UX: "I couldn't
-///                  describe that one."
+/// F-R3-10 splits the previous \`networkError\` lump into three failure
+/// modes that have DIFFERENT remediations — collapsing them into one
+/// "try again" message confuses both the user (was it wifi? was it the
+/// AI?) and the agent debugging the flow (is retry-with-backoff going
+/// to help?).
 ///
-/// R2 dogfood F-R2-10: throwing/empty-string semantics collapsed all
-/// three failure modes into one, so the user heard the same recorded
-/// message regardless of cause.
+///   .ok           — speak / display the text.
+///   .authFailure  — 401/403 OR blank key. Actionable by the dev (rotate
+///                   / configure the key); not by the user. Never retried.
+///                   UX: "Your Anthropic key isn't set up."
+///   .connectivity — URLSession threw (DNS / no internet / TLS / timeout).
+///                   Retry won't help until network returns.
+///                   UX: "I can't reach the network — check your connection."
+///   .transient    — 429 rate-limit OR 5xx server error. RETRIED inside
+///                   post() with exponential backoff (200ms / 800ms /
+///                   3.2s). If still failing after the retry budget,
+///                   surfaces as this case. UX: "The AI is slow right
+///                   now — try again in a moment."
+///   .clientBug    — 400 / 404 / 422 / any 4xx that isn't 401/403/429.
+///                   The request itself is malformed; retry will never
+///                   fix it. Surface loud in logs; UX is best-effort.
+///   .empty        — 2xx with no text content. Model couldn't make sense
+///                   of the input. UX: "I couldn't describe that one."
 enum LlmResult {
     case ok(String)
     case authFailure
-    case networkError
+    case connectivity
+    case transient
+    case clientBug
     case empty
 }
 
@@ -815,12 +940,26 @@ actor AnthropicClient {
     private let apiKey: String
     private let model: String
     private let maxTokens: Int
+    private let observability: (any ObservabilityClient)?
+    private let maxAttempts: Int
     private let endpoint = URL(string: "https://api.anthropic.com/v1/messages")!
 
-    init(apiKey: String, model: String = "claude-opus-4-7", maxTokens: Int = 1024) {
+    /// Pass \`glasses.observability\` from your ExtentosGlasses instance to
+    /// surface each call in getEventLog under the "ai" filter chip (F-R3-11).
+    /// \`maxAttempts\` controls the retry budget for .transient / .connectivity
+    /// failures (200ms / 800ms / 3.2s exponential backoff).
+    init(
+        apiKey: String,
+        model: String = "claude-opus-4-7",
+        maxTokens: Int = 1024,
+        observability: (any ObservabilityClient)? = nil,
+        maxAttempts: Int = 3
+    ) {
         self.apiKey = apiKey
         self.model = model
         self.maxTokens = maxTokens
+        self.observability = observability
+        self.maxAttempts = maxAttempts
     }
 
     // ---- Wire schema ----
@@ -872,7 +1011,9 @@ actor AnthropicClient {
             Message(role: "user", content: [.text($0)])
         }
         messages.append(Message(role: "user", content: [.text(question)]))
-        return await post(messages: messages, system: nil)
+        return await wrap(label: "anthropic.ask") {
+            await post(messages: messages, system: nil)
+        }
     }
 
     /// Vision: one image (base64) + a text prompt. Source the imageBase64 +
@@ -893,25 +1034,67 @@ actor AnthropicClient {
                 ],
             ),
         ]
-        return await post(messages: messages, system: system)
+        return await wrap(label: "anthropic.describe", metadata: ["media_type": mediaType]) {
+            await post(messages: messages, system: system)
+        }
+    }
+
+    // ---- Wrap each call in observability.aiCall when wired ----
+
+    private func wrap(
+        label: String,
+        metadata: [String: String] = [:],
+        block: () async -> LlmResult
+    ) async -> LlmResult {
+        guard let obs = observability else { return await block() }
+        var meta = metadata
+        meta["model"] = model
+        return await obs.aiCall(label: label, metadata: meta) {
+            await block()
+        }
     }
 
-    // ---- Transport ----
+    // ---- Transport with retry-with-backoff ----
 
     private func post(messages: [Message], system: String?) async -> LlmResult {
         guard !apiKey.isEmpty else { return .authFailure }
-        var request = URLRequest(url: endpoint)
-        request.httpMethod = "POST"
+        let body: Data
         do {
-            request.httpBody = try JSONEncoder().encode(
+            body = try JSONEncoder().encode(
                 Req(model: model, max_tokens: maxTokens, messages: messages, system: system)
             )
         } catch {
-            // Encoding error — typically a programming bug, not a network
-            // condition. Surface as networkError since it's not auth and
-            // not "the model returned nothing"; the handler will retry.
-            return .networkError
+            // Encoding error — programming bug. Surface as clientBug so
+            // the dev sees it loud; retry will never fix it.
+            return .clientBug
+        }
+
+        var attempt = 0
+        var lastFailure: LlmResult = .transient
+        while attempt < maxAttempts {
+            let result = await postOnce(body: body)
+            switch result {
+            // Definitive — return immediately, no retry.
+            case .ok, .authFailure, .clientBug, .empty:
+                return result
+            // Retryable.
+            case .transient, .connectivity:
+                lastFailure = result
+                attempt += 1
+                if attempt < maxAttempts {
+                    // 200ms, 800ms, 3.2s.
+                    let backoffMs = UInt64(200) << (2 * UInt64(attempt - 1))
+                    try? await Task.sleep(nanoseconds: backoffMs * 1_000_000)
+                }
+            }
         }
+        return lastFailure
+    }
+
+    private func postOnce(body: Data) async -> LlmResult {
+        var request = URLRequest(url: endpoint)
+        request.httpMethod = "POST"
+        request.httpBody = body
         request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
         request.setValue("2023-06-01", forHTTPHeaderField: "anthropic-version")
         request.setValue("application/json", forHTTPHeaderField: "content-type")
@@ -921,20 +1104,24 @@ actor AnthropicClient {
         do {
             (data, response) = try await URLSession.shared.data(for: request)
         } catch {
-            // No HTTP exchange — DNS / no internet / timeout. Same UX
-            // as a transient 5xx.
-            return .networkError
+            // No HTTP exchange — DNS / no internet / TLS / timeout.
+            return .connectivity
         }
 
         if let http = response as? HTTPURLResponse {
             switch http.statusCode {
             case 401, 403:
                 return .authFailure
+            case 429, 500...599:
+                return .transient
+            case 400...499:
+                // Other 4xx — malformed request, not retryable.
+                return .clientBug
             case 200..<300:
                 break
             default:
-                // 429 + 5xx + everything else non-2xx → retryable.
-                return .networkError
+                // 1xx / 3xx unexpected → treat as transient.
+                return .transient
             }
         }
 
@@ -944,8 +1131,9 @@ actor AnthropicClient {
             return text.isEmpty ? .empty : .ok(text)
         } catch {
             // 2xx with an undecodable body — treat as empty rather than
-            // network so the user-facing message reflects "got something
-            // back, didn't understand it" rather than "couldn't reach".
+            // a network class so the user-facing message reflects "got
+            // something back, didn't understand it" rather than "couldn't
+            // reach".
             return .empty
         }
     }
@@ -953,20 +1141,26 @@ actor AnthropicClient {
 
 // Wire-up — your handler reads the API key from Info.plist (which gets
 // it via xcconfig / env var — see getCredentialGuide for the storage
-// pattern), then passes it to a single actor instance. Both ask() and
-// describe() return LlmResult; switch on it to give the user the right
-// message per failure mode.
+// pattern), then passes it to a single actor instance. Pass
+// glasses.observability so each call surfaces under getEventLog's "ai"
+// filter (F-R3-11). Both ask() and describe() return LlmResult; switch
+// on it to give the user the right message per failure mode.
 //
 //   let key = Bundle.main.object(forInfoDictionaryKey: "ANTHROPIC_API_KEY") as? String ?? ""
-//   let anthropic = AnthropicClient(apiKey: key)
+//   let anthropic = AnthropicClient(
+//       apiKey: key,
+//       observability: glasses.observability   // surfaces in getEventLog "ai" chip
+//   )
 //
 //   // text:
 //   let spoken: String
 //   switch await anthropic.ask(question: "How many bench reps today?") {
-//   case .ok(let text): spoken = text
-//   case .authFailure:  spoken = "Your Anthropic key isn't set up — check Info.plist."
-//   case .networkError: spoken = "I couldn't reach the AI. Try again."
-//   case .empty:        spoken = "I didn't get an answer. Try rephrasing."
+//   case .ok(let text):   spoken = text
+//   case .authFailure:    spoken = "Your Anthropic key isn't set up — check Info.plist."
+//   case .connectivity:   spoken = "I can't reach the network. Check your connection."
+//   case .transient:      spoken = "The AI is slow right now — try again in a moment."
+//   case .clientBug:      spoken = "Something's off with the request — check OSLog AnthropicClient for the response body."
+//   case .empty:          spoken = "I didn't get an answer. Try rephrasing."
 //   }
 //   _ = await glasses.audio.speak(spoken)
 //
@@ -985,7 +1179,7 @@ actor AnthropicClient {
 //   )
 //   // switch answer { case .ok(let t): ...; case .authFailure: ...; ... }`,
     },
-    explanation: "Minimal direct client supporting BOTH text Q&A (`ask`) and Claude Vision (`describe`). There's no first-party Anthropic Kotlin SDK; this is the wire-protocol wrapper voice_qa_assistant and photo_describe_voice patterns reference as `AnthropicClient`. Kotlin uses OkHttp + kotlinx-serialization with a `JsonClassDiscriminator(\"type\")` sealed ContentBlock that mirrors Anthropic's polymorphic content shape (text + image). Swift uses URLSession + Codable with manual encode/decode for the same polymorphism. The customer holds one instance at Application scope and passes it to handlers via DI.",
+    explanation: "Minimal direct client supporting BOTH text Q&A (`ask`) and Claude Vision (`describe`). There's no first-party Anthropic Kotlin SDK; this is the wire-protocol wrapper voice_qa_assistant and photo_describe_voice patterns reference as `AnthropicClient`. Kotlin uses OkHttp + kotlinx-serialization with a `JsonClassDiscriminator(\"type\")` sealed ContentBlock that mirrors Anthropic's polymorphic content shape (text + image). Swift uses URLSession + Codable with manual encode/decode for the same polymorphism. The customer holds one instance at Application scope and passes it to handlers via DI. F-R3-10 split the failure mode out of one `NetworkError` into five distinct LlmResult variants (Connectivity / Transient / ClientBug / AuthFailure / Empty) so different remediations show up as different user-facing messages, and added a retry-with-backoff loop (200ms / 800ms / 3.2s, 3 attempts) for Transient + Connectivity cases. F-R3-11 added optional `observability: glasses.observability` wiring — pass it and every call surfaces under getEventLog's 'ai' filter chip with timing + success/error metadata.",
     gotchas: [
         "API key MUST come from a build-injected resource (resValue on Android, xcconfig on iOS). Don't paste literals — they leak into git. See getCredentialGuide for the storage pattern.",
         "Anthropic-version header is required and version-pinned — bump '2023-06-01' when Anthropic releases a new API version that adds features you need.",
@@ -993,7 +1187,9 @@ actor AnthropicClient {
         "max_tokens defaults to 1024 here — bump for longer answers, but the glasses TTS engine will speak whatever comes back, so consider trimming on your side before speak() rather than asking for unbounded length. For Vision specifically, 256 is often plenty (you typically want a short action: hit / stand / split, not paragraphs).",
         "history is a list of prior user turns. For real multi-turn you'll likely want to interleave 'user' and 'assistant' roles — extend the schema's role enum and pass alternating turns.",
         "OkHttp's .execute() blocks the calling thread — wrapping in withContext(Dispatchers.IO) keeps it off the main dispatcher. Don't call ask() / describe() from the UI thread directly.",
-        "Vision LLM response p95 is 2-8 seconds. Play an earcon (`glasses.audio.earcon(EarconSound.START)`) BEFORE the call so the user knows the request fired.",
+        "Vision LLM response p95 is 2-8 seconds. Play an earcon (`glasses.audio.earcon(EarconSound.START)`) BEFORE the call so the user knows the request fired. The retry-with-backoff loop adds up to ~4.2s in the worst-case Transient path, so plan UX timing accordingly (or lower maxAttempts).",
+        "LlmResult has 6 variants — Ok / AuthFailure / Connectivity / Transient / ClientBug / Empty. Each has a distinct user-facing message; don't collapse them. The compile-time exhaustive `when` (Kotlin) / `switch` (Swift) makes the requirement explicit — adding a new variant breaks every caller until they handle it. Don't try/catch around the call; the sealed type IS the error channel.",
+        "Pass `observability: glasses.observability` to surface each call in getEventLog under the 'ai' filter chip. Without it, BYOK calls are invisible to the simulator event log — debugging a silent failure requires `adb logcat AnthropicClient:V` (Android) or OSLog filtered by `AnthropicClient` (iOS). The wrapper is zero-overhead off-simulator transports (RealMeta / LocalSim).",
     ],
     relatedFeatures: ["capture_photo"],
     requiredDependencies: {