@extentos/mcp-server 0.0.75 → 0.0.77

package/dist/tools/data/codeExamples.d.ts

@@ -1,3 +1,35 @@
+/** Gradle dependency a pattern needs the host app to add. */
+export interface RequiredGradleDep {
+    /** Configuration name as it appears in `dependencies { ... }`. */
+    configuration: "implementation" | "debugImplementation" | "testImplementation" | "androidTestImplementation";
+    /** Maven coordinate string, e.g. "com.squareup.okhttp3:okhttp:4.12.0". */
+    notation: string;
+    /** Which file the dep block lives in. */
+    appliedIn: "app/build.gradle.kts";
+}
+/** Gradle plugin a pattern needs the host app to declare. */
+export interface RequiredGradlePlugin {
+    /** Plugin id, e.g. "org.jetbrains.kotlin.plugin.serialization". */
+    id: string;
+    /** Version string — only set on the root declaration. */
+    version?: string;
+    /** Which file the plugin block lives in. */
+    appliedIn: "root build.gradle.kts" | "app/build.gradle.kts";
+    /** When true, root declaration carries `apply false`; the app file
+     *  declares the same plugin id with no version to actually apply it. */
+    applyFalse?: boolean;
+    /** Free-text caveat the agent should read before applying. */
+    note?: string;
+}
+/** Swift Package Manager dependency a pattern needs (iOS host). */
+export interface RequiredSwiftPackage {
+    /** Repository URL. */
+    url: string;
+    /** Version spec, e.g. "1.2.0" used with `.upToNextMajor(from:)`. */
+    from: string;
+    /** Library products to add to the target. */
+    products: string[];
+}
 export interface CodeExample {
     pattern: string;
     title: string;
@@ -9,6 +41,27 @@ export interface CodeExample {
     explanation: string;
     gotchas: string[];
     relatedFeatures: string[];
+    /**
+     * Extra Gradle / SPM deps the host app must add for this pattern's
+     * `code` block to compile. Omitted on patterns that need nothing
+     * beyond the SDK + stdlib. Surfaced verbatim by getCodeExample so
+     * agents can merge the union of deps from every pattern they use into
+     * the build files without scraping `code` comments (R2 F-R2-8).
+     */
+    requiredDependencies?: {
+        android?: RequiredGradleDep[];
+        iosSwiftPackages?: RequiredSwiftPackage[];
+    };
+    /**
+     * Gradle plugins this pattern needs. Plugins typically appear TWICE:
+     * once in the root `build.gradle.kts` plugins block (with `version` +
+     * `applyFalse: true`), once in `app/build.gradle.kts` plugins block
+     * (with no version) to actually take effect. iOS has no plugin
+     * concept; SPM handles its own bootstrapping.
+     */
+    requiredPlugins?: {
+        android?: RequiredGradlePlugin[];
+    };
 }
 export declare const CODE_EXAMPLES: Record<string, CodeExample>;
 export declare const CODE_EXAMPLE_PATTERNS: string[];

package/dist/tools/data/codeExamples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codeExamples.d.ts","sourceRoot":"","sources":["../../../src/tools/data/codeExamples.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAu1BD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAQrD,CAAC;AAEF,eAAO,MAAM,qBAAqB,UAAoC,CAAC"}
+{"version":3,"file":"codeExamples.d.ts","sourceRoot":"","sources":["../../../src/tools/data/codeExamples.ts"],"names":[],"mappings":"AAeA,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,aAAa,EAAE,gBAAgB,GAAG,qBAAqB,GAAG,oBAAoB,GAAG,2BAA2B,CAAC;IAC7G,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,SAAS,EAAE,sBAAsB,CAAC;CACnC;AAED,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,SAAS,EAAE,uBAAuB,GAAG,sBAAsB,CAAC;IAC5D;4EACwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE;QACrB,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;QAC9B,gBAAgB,CAAC,EAAE,oBAAoB,EAAE,CAAC;KAC3C,CAAC;IACF;;;;;;OAMG;IACH,eAAe,CAAC,EAAE;QAChB,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;KAClC,CAAC;CACH;AAshCD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAQrD,CAAC;AAEF,eAAO,MAAM,qBAAqB,UAAoC,CAAC"}

package/dist/tools/data/codeExamples.js

@@ -10,6 +10,7 @@
 // app_callback, no triggers/blocks/actions DSL. Customer-side LLM
 // clients are referenced as `anthropic` / `vision` / `repo` without
 // importing — agents wire those to their existing backend.
+import { VERSION_INFO } from "./version.js";
 const VOICE_QA_ASSISTANT = {
     pattern: "voice_qa_assistant",
     title: "Voice Q&A assistant (wake + question + LLM + speak)",
@@ -56,11 +57,19 @@ class CoachHandler(
                 val question = recording.transcript.trim()
                 if (question.isEmpty() || "stop" in question.lowercase()) break
 
-                val answer = anthropic.ask(
+                // 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.
+                val spoken = when (val r = anthropic.ask(
                     question = question,
                     workoutHistory = workouts.recent(),
-                )
-                glasses.audio.speak(answer)
+                )) {
+                    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."
+                }
+                glasses.audio.speak(spoken)
             }
         }
     }
@@ -105,12 +114,17 @@ class CoachHandler(
             let question = recording.transcript.trimmingCharacters(in: .whitespaces)
             if question.isEmpty || question.lowercased().contains("stop") { break }
 
-            if let answer = try? await anthropic.ask(
-                question: question,
-                workoutHistory: workouts.recent()
-            ) {
-                _ = await glasses.audio.speak(answer)
+            // 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.
+            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."
             }
+            _ = await glasses.audio.speak(spoken)
         }
     }
 
@@ -130,6 +144,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').",
     ],
     relatedFeatures: ["voice_command", "transcription_incremental", "record_audio"],
 };
@@ -252,12 +267,21 @@ class VisionHandler(
             }
             val mediaType = Photos.mediaTypeFromUri(uri) ?: "image/jpeg"
 
-            val description = vision.describe(
+            // describe() returns LlmResult — pattern-match 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
+            // (user can't distinguish "fix your key" from "AI was unsure").
+            val spoken = when (val r = vision.describe(
                 imageBase64 = base64,
                 mediaType = mediaType,
                 prompt = "Describe this scene briefly, conversationally.",
-            )
-            glasses.audio.speak(description.ifBlank { "I couldn't describe that one." })
+            )) {
+                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."
+            }
+            glasses.audio.speak(spoken)
         }
     }
 
@@ -294,14 +318,17 @@ class VisionHandler(
             // Decode via the bundled extension; pass the bytes to
             // your vision LLM however it expects them (base64, Data).
             let image = await photo.loadImage()
-            let description = (try? await vision.describe(
-                image: image,
-                prompt: "Describe this scene briefly, conversationally."
-            )) ?? ""
-            let answer = description.isEmpty
-                ? "I couldn't describe that one."
-                : description
-            _ = await glasses.audio.speak(answer)
+            // 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.
+            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."
+            }
+            _ = await glasses.audio.speak(spoken)
         }
     }
 
@@ -316,6 +343,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.",
     ],
     relatedFeatures: ["capture_photo", "voice_command", "transcription_incremental"],
 };
@@ -555,7 +583,8 @@ const 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.",
     code: {
-        kotlin: `import kotlinx.coroutines.Dispatchers
+        kotlin: `import java.io.IOException
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
@@ -566,10 +595,42 @@ import okhttp3.OkHttpClient
 import okhttp3.Request
 import okhttp3.RequestBody.Companion.toRequestBody
 
-// build.gradle.kts:
-//   implementation("com.squareup.okhttp3:okhttp:4.12.0")
-//   implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
-//   plugins { id("org.jetbrains.kotlin.plugin.serialization") }
+// Required deps + plugins are exposed structurally on this example's
+// response (getCodeExample.requiredDependencies / requiredPlugins) so
+// the agent can merge them into build files without re-reading this
+// comment. See the response for the exact configuration + appliedIn
+// fields. R2 F-R2-8 — formerly the agent had to scrape gradle hints
+// from inline comments and forget the root plugins {} entry, breaking
+// the kotlinx-serialization compile.
+
+/**
+ * Outcome of a single ask/describe call. Sealed so when(result) is
+ * 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."
+ *
+ * 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".
+ */
+sealed interface LlmResult {
+    data class Ok(val text: String) : LlmResult
+    data object AuthFailure : LlmResult
+    data object NetworkError : LlmResult
+    data object Empty : LlmResult
+}
 
 class AnthropicClient(
     private val apiKey: String,
@@ -614,7 +675,7 @@ 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()): String =
+    suspend fun ask(question: String, history: List<String> = emptyList()): LlmResult =
         post(
             messages = buildList {
                 for (turn in history) {
@@ -632,7 +693,7 @@ class AnthropicClient(
         mediaType: String,
         prompt: String,
         system: String? = null,
-    ): String = post(
+    ): LlmResult = post(
         messages = listOf(
             Message(
                 "user",
@@ -647,9 +708,9 @@ class AnthropicClient(
 
     // ---- Transport ----
 
-    private suspend fun post(messages: List<Message>, system: String? = null): String =
+    private suspend fun post(messages: List<Message>, system: String? = null): LlmResult =
         withContext(Dispatchers.IO) {
-            if (apiKey.isBlank()) return@withContext ""
+            if (apiKey.isBlank()) return@withContext LlmResult.AuthFailure
             val body = json.encodeToString(
                 Req.serializer(),
                 Req(model = model, maxTokens = maxTokens, messages = messages, system = system),
@@ -661,14 +722,35 @@ class AnthropicClient(
                 .header("content-type", "application/json")
                 .post(body.toRequestBody("application/json".toMediaType()))
                 .build()
-            client.newCall(request).execute().use { response ->
-                val payload = response.body?.string() ?: return@withContext ""
-                if (!response.isSuccessful) {
-                    android.util.Log.w("AnthropicClient", "HTTP \${response.code}: \${payload.take(500)}")
-                    return@withContext ""
+            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)
+                        }
+                    }
                 }
-                json.decodeFromString(Res.serializer(), payload)
-                    .content.firstOrNull { it.type == "text" }?.text.orEmpty().trim()
+            } 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
             }
         }
 }
@@ -676,13 +758,20 @@ class AnthropicClient(
 // 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:
+// held at Application scope. 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)
 //
 //   // text:
-//   val answer = anthropic.ask("How many bench reps did I do today?")
+//   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."
+//   }
+//   glasses.audio.speak(spoken)
 //
 //   // vision (paired with capture_photo + Photos helpers):
 //   val photo = glasses.camera.capturePhoto(
@@ -691,9 +780,37 @@ class AnthropicClient(
 //   val uri = photo.uri ?: return
 //   val b64 = Photos.loadBase64(uri) ?: return
 //   val mt = Photos.mediaTypeFromUri(uri) ?: "image/jpeg"
-//   val answer = anthropic.describe(b64, mt, "What card is showing?")`,
+//   val result = anthropic.describe(b64, mt, "What card is showing?")
+//   // when(result) { is LlmResult.Ok -> result.text; ...other cases... }`,
         swift: `import Foundation
 
+/// 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."
+///
+/// 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.
+enum LlmResult {
+    case ok(String)
+    case authFailure
+    case networkError
+    case empty
+}
+
 actor AnthropicClient {
     private let apiKey: String
     private let model: String
@@ -749,13 +866,13 @@ actor AnthropicClient {
 
     // ---- Public API ----
 
-    /// Text-only Q&A.
-    func ask(question: String, history: [String] = []) async throws -> String {
+    /// Text-only Q&A. Non-throwing: any error becomes an LlmResult case.
+    func ask(question: String, history: [String] = []) async -> LlmResult {
         var messages = history.map {
             Message(role: "user", content: [.text($0)])
         }
         messages.append(Message(role: "user", content: [.text(question)]))
-        return try await post(messages: messages, system: nil)
+        return await post(messages: messages, system: nil)
     }
 
     /// Vision: one image (base64) + a text prompt. Source the imageBase64 +
@@ -766,7 +883,7 @@ actor AnthropicClient {
         mediaType: String,
         prompt: String,
         system: String? = nil,
-    ) async throws -> String {
+    ) async -> LlmResult {
         let messages = [
             Message(
                 role: "user",
@@ -776,45 +893,82 @@ actor AnthropicClient {
                 ],
             ),
         ]
-        return try await post(messages: messages, system: system)
+        return await post(messages: messages, system: system)
     }
 
     // ---- Transport ----
 
-    private func post(messages: [Message], system: String?) async throws -> String {
-        guard !apiKey.isEmpty else { return "" }
+    private func post(messages: [Message], system: String?) async -> LlmResult {
+        guard !apiKey.isEmpty else { return .authFailure }
         var request = URLRequest(url: endpoint)
         request.httpMethod = "POST"
-        request.httpBody = try JSONEncoder().encode(
-            Req(model: model, max_tokens: maxTokens, messages: messages, system: system)
-        )
+        do {
+            request.httpBody = 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
+        }
         request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
         request.setValue("2023-06-01", forHTTPHeaderField: "anthropic-version")
         request.setValue("application/json", forHTTPHeaderField: "content-type")
 
-        let (data, response) = try await URLSession.shared.data(for: request)
-        if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
-            let body = String(data: data, encoding: .utf8) ?? "HTTP \\(http.statusCode)"
-            throw NSError(
-                domain: "Anthropic",
-                code: http.statusCode,
-                userInfo: [NSLocalizedDescriptionKey: body]
-            )
+        let data: Data
+        let response: URLResponse
+        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
+        }
+
+        if let http = response as? HTTPURLResponse {
+            switch http.statusCode {
+            case 401, 403:
+                return .authFailure
+            case 200..<300:
+                break
+            default:
+                // 429 + 5xx + everything else non-2xx → retryable.
+                return .networkError
+            }
+        }
+
+        do {
+            let decoded = try JSONDecoder().decode(Res.self, from: data)
+            let text = decoded.content.first(where: { $0.type == "text" })?.text ?? ""
+            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".
+            return .empty
         }
-        let decoded = try JSONDecoder().decode(Res.self, from: data)
-        return decoded.content.first(where: { $0.type == "text" })?.text ?? ""
     }
 }
 
 // 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:
+// 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.
 //
 //   let key = Bundle.main.object(forInfoDictionaryKey: "ANTHROPIC_API_KEY") as? String ?? ""
 //   let anthropic = AnthropicClient(apiKey: key)
 //
 //   // text:
-//   let answer = try await anthropic.ask(question: "How many bench reps today?")
+//   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."
+//   }
+//   _ = await glasses.audio.speak(spoken)
 //
 //   // vision (paired with capture_photo + photo.loadImage helpers):
 //   let result = await glasses.camera.capturePhoto(
@@ -824,11 +978,12 @@ actor AnthropicClient {
 //   guard let image = await photo.loadImage(),
 //         let jpeg = image.jpegData(compressionQuality: 0.85) else { return }
 //   let b64 = jpeg.base64EncodedString()
-//   let answer = try await anthropic.describe(
+//   let answer = await anthropic.describe(
 //       imageBase64: b64,
 //       mediaType: "image/jpeg",
 //       prompt: "What's the next blackjack move?"
-//   )`,
+//   )
+//   // 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.",
     gotchas: [
@@ -841,6 +996,43 @@ actor AnthropicClient {
         "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.",
     ],
     relatedFeatures: ["capture_photo"],
+    requiredDependencies: {
+        android: [
+            {
+                configuration: "implementation",
+                notation: "com.squareup.okhttp3:okhttp:4.12.0",
+                appliedIn: "app/build.gradle.kts",
+            },
+            {
+                configuration: "implementation",
+                notation: "org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3",
+                appliedIn: "app/build.gradle.kts",
+            },
+        ],
+        // iOS uses URLSession + Codable from the standard library — no
+        // extra SPM dependency required.
+        iosSwiftPackages: [],
+    },
+    requiredPlugins: {
+        android: [
+            // The serialization plugin needs BOTH declarations to take effect:
+            // version+applyFalse in the root, version-less in the app file.
+            // Forgetting the root entry yields "Plugin not found"; forgetting
+            // the app entry yields a compile failure on @Serializable.
+            {
+                id: "org.jetbrains.kotlin.plugin.serialization",
+                version: VERSION_INFO.android.kotlinVersion,
+                appliedIn: "root build.gradle.kts",
+                applyFalse: true,
+                note: "Version MUST match the kotlin.android plugin version (both come from the Kotlin distribution).",
+            },
+            {
+                id: "org.jetbrains.kotlin.plugin.serialization",
+                appliedIn: "app/build.gradle.kts",
+                note: "No version here — inherits from the root declaration. Sits alongside id(\"com.android.application\") and id(\"org.jetbrains.kotlin.android\").",
+            },
+        ],
+    },
 };
 export const CODE_EXAMPLES = {
     voice_qa_assistant: VOICE_QA_ASSISTANT,

package/dist/tools/data/codeExamples.js.map

@@ -1 +1 @@
-{"version":3,"file":"codeExamples.js","sourceRoot":"","sources":["../../../src/tools/data/codeExamples.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,sEAAsE;AACtE,sEAAsE;AACtE,uDAAuD;AACvD,sCAAsC;AACtC,EAAE;AACF,qEAAqE;AACrE,uDAAuD;AACvD,wEAAwE;AACxE,kEAAkE;AAClE,oEAAoE;AACpE,2DAA2D;AAe3D,MAAM,kBAAkB,GAAgB;IACtC,OAAO,EAAE,oBAAoB;IAC7B,KAAK,EAAE,qDAAqD;IAC5D,WAAW,EACT,kSAAkS;IACpS,IAAI,EAAE;QACJ,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmDV;QACE,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgDT;KACC;IACD,WAAW,EACT,ggCAAggC;IAClgC,OAAO,EAAE;QACP,yXAAyX;QACzX,gbAAgb;QAChb,qXAAqX;QACrX,mSAAmS;QACnS,oSAAoS;QACpS,ySAAyS;QACzS,msBAAmsB;QACnsB,sIAAsI;QACtI,+HAA+H;QAC/H,yKAAyK;QACzK,0WAA0W;KAC3W;IACD,eAAe,EAAE,CAAC,eAAe,EAAE,2BAA2B,EAAE,cAAc,CAAC;CAChF,CAAC;AAEF,MAAM,cAAc,GAAgB;IAClC,OAAO,EAAE,gBAAgB;IACzB,KAAK,EAAE,gDAAgD;IACvD,WAAW,EACT,uMAAuM;IACzM,IAAI,EAAE;QACJ,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BV;QACE,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgCT;KACC;IACD,WAAW,EACT,+ZAA+Z;IACja,OAAO,EAAE;QACP,8IAA8I;QAC9I,6PAA6P;QAC7P,kLAAkL;KACnL;IACD,eAAe,EAAE,CAAC,2BAA2B,CAAC;CAC/C,CAAC;AAEF,MAAM,oBAAoB,GAAgB;IACxC,OAAO,EAAE,sBAAsB;IAC/B,KAAK,EAAE,gDAAgD;IACvD,WAAW,EACT,0NAA0N;IAC5N,IAAI,EAAE;QACJ,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDV;QACE,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2CT;KACC;IACD,WAAW,EACT,gWAAgW;IAClW,OAAO,EAAE;QACP,4OAA4O;QAC5O,4KAA4K;QAC5K,yGAAyG;QACzG,iRAAiR;QACjR,iMAAiM;QACjM,gRAAgR;KACjR;IACD,eAAe,EAAE,CAAC,eAAe,EAAE,eAAe,EAAE,2BAA2B,CAAC;CACjF,CAAC;AAEF,MAAM,qBAAqB,GAAgB;IACzC,OAAO,EAAE,uBAAuB;IAChC,KAAK,EAAE,+CAA+C;IACtD,WAAW,EACT,yLAAyL;IAC3L,IAAI,EAAE;QACJ,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA4BU;QAClB,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;yBAyBc;KACtB;IACD,WAAW,EACT,4QAA4Q;IAC9Q,OAAO,EAAE;QACP,gNAAgN;QAChN,2KAA2K;QAC3K,6LAA6L;KAC9L;IACD,eAAe,EAAE,CAAC,2BAA2B,CAAC;CAC/C,CAAC;AAEF,MAAM,WAAW,GAAgB;IAC/B,OAAO,EAAE,aAAa;IACtB,KAAK,EAAE,sCAAsC;IAC7C,WAAW,EACT,sKAAsK;IACxK,IAAI,EAAE;QACJ,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0CV;QACE,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqCT;KACC;IACD,WAAW,EACT,yQAAyQ;IAC3Q,OAAO,EAAE;QACP,iNAAiN;QACjN,2GAA2G;KAC5G;IACD,eAAe,EAAE,CAAC,eAAe,EAAE,cAAc,EAAE,2BAA2B,CAAC;CAChF,CAAC;AAEF,MAAM,qBAAqB,GAAgB;IACzC,OAAO,EAAE,uBAAuB;IAChC,KAAK,EAAE,8CAA8C;IACrD,WAAW,EACT,+NAA+N;IACjO,IAAI,EAAE;QACJ,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;kDAwBsC;QAC9C,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BT;KACC;IACD,WAAW,EACT,+TAA+T;IACjU,OAAO,EAAE;QACP,kMAAkM;QAClM,6QAA6Q;QAC7Q,iMAAiM;KAClM;IACD,eAAe,EAAE,EAAE;CACpB,CAAC;AAEF,MAAM,cAAc,GAAgB;IAClC,OAAO,EAAE,gBAAgB;IACzB,KAAK,EAAE,uEAAuE;IAC9E,WAAW,EACT,0eAA0e;IAC5e,IAAI,EAAE;QACJ,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uEAwI2D;QACnE,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwIJ;KACJ;IACD,WAAW,EACT,olBAAolB;IACtlB,OAAO,EAAE;QACP,qLAAqL;QACrL,oJAAoJ;QACpJ,yWAAyW;QACzW,yUAAyU;QACzU,sLAAsL;QACtL,sLAAsL;QACtL,yJAAyJ;KAC1J;IACD,eAAe,EAAE,CAAC,eAAe,CAAC;CACnC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAgC;IACxD,kBAAkB,EAAE,kBAAkB;IACtC,cAAc,EAAE,cAAc;IAC9B,oBAAoB,EAAE,oBAAoB;IAC1C,qBAAqB,EAAE,qBAAqB;IAC5C,WAAW,EAAE,WAAW;IACxB,qBAAqB,EAAE,qBAAqB;IAC5C,cAAc,EAAE,cAAc;CAC/B,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE,CAAC"}
+{"version":3,"file":"codeExamples.js","sourceRoot":"","sources":["../../../src/tools/data/codeExamples.ts"],"names":[],"mappings":"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"}

package/dist/tools/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IAMpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,EAAE,KAAK,CAAC;KAC7B,CAAC;CACH;AAMD,eAAO,MAAM,eAAe,EAAE,OAAO,EAwXpC,CAAC;AAEF,eAAO,MAAM,SAAS,QAAyB,CAAC;AAShD,wBAAgB,iCAAiC,CAC/C,IAAI,GAAE,SAAS,OAAO,EAAoB,GACzC,IAAI,CAiBN"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IAMpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,EAAE,KAAK,CAAC;KAC7B,CAAC;CACH;AAMD,eAAO,MAAM,eAAe,EAAE,OAAO,EAsXpC,CAAC;AAEF,eAAO,MAAM,SAAS,QAAyB,CAAC;AAShD,wBAAgB,iCAAiC,CAC/C,IAAI,GAAE,SAAS,OAAO,EAAoB,GACzC,IAAI,CAiBN"}

package/dist/tools/definitions.js

@@ -234,7 +234,7 @@ export const toolDefinitions = [
     },
     {
         name: "getEventLog",
-        description: "Fetch structured event trace inside a simulator session. Primary debugging tool for *why is my handler not seeing what I expect* — transcripts not arriving, photo capture failing, toggle changes not propagating, speak getting cut off, connection dropping. Events are grouped by capability layer (transport / audio / camera / speak / toggle / stream / system) so you can filter to just the surface you're investigating. USE to diagnose which capability primitive is misbehaving. DON'T USE for static configuration checking (use validateIntegration) or for live session phase (use getSimulatorStatus).",
+        description: "Fetch structured event trace inside a simulator session. Primary debugging tool for *why is my handler not seeing what I expect* — transcripts not arriving, photo capture failing, toggle changes not propagating, speak getting cut off, connection dropping. Events are grouped into six chips (errors / voice / camera / ai / lifecycle / custom) — one chip per event, with `errors` absorbing every severity≥warn row regardless of modality. To see e.g. voice activity plus voice errors, fetch the chips separately and union them. USE to diagnose which capability primitive is misbehaving. DON'T USE for static configuration checking (use validateIntegration) or for live session phase (use getSimulatorStatus). **Scope (R2 F-R2-12):** captures only the simulator's WebSocket relay — transport + SDK primitives (audio, camera, speak, toggles, voice triggers, runtime events). Customer-side direct-HTTP calls (BYOK Anthropic / OpenAI / Gemini / etc.) NEVER traverse the wire and so are invisible here — those failures surface in logcat (Android) or OSLog (iOS). When debugging a flow that mixes SDK primitives with external APIs (e.g. capture_photo → vision LLM → speak), combine getEventLog with the platform log surface; a getEventLog showing capture_photo + photo_result + speak with nothing in between is the signature of a silent BYOK failure.",
         inputSchema: {
             type: "object",
             properties: {
@@ -244,15 +244,13 @@ export const toolDefinitions = [
                     enum: [
                         "all",
                         "errors",
-                        "transport",
-                        "audio",
+                        "voice",
                         "camera",
-                        "speak",
-                        "toggles",
-                        "streams",
-                        "system",
+                        "ai",
+                        "lifecycle",
+                        "custom",
                     ],
-                    description: "Layer to filter the event stream by. 'all' (default) returns every event; 'errors' returns only severity≥error; the remaining values scope to one capability layer.",
+                    description: "Chip to filter the event stream by. 'all' (default) returns every event. 'errors' returns severity≥warn events across all modalities. 'voice' / 'camera' / 'ai' cover hardware/integration capabilities (severity=info only — failures land under 'errors'). 'lifecycle' covers connection / session / pairing / hardware / runtime state. 'custom' is the open-world catch-all for app-emitted event types the platform did not anticipate.",
                 },
                 limit: { type: "integer", minimum: 1 },
                 since: { type: "string" },