DocsSearchBridge.kt

    fun search(
        state: SearchState,
        query: String,
        onTextDelta: ((String) -> Unit)? = null
    ): SearchResult {
        val t0 = System.nanoTime()
        info("search(): query='$query' thread=${state.thread.localThreadId}")

        val retrieval = runCatching {
            SemanticRetrievalService.query(
                SemanticRetrievalQueryRequest(
                    query = query,
                    limit = maxHits,
                    rebuildIfEmpty = true,
                    includeCapsule = true,
                    includeSource = true
                )
            )
        }.onFailure { warn("semantic retrieval failed: ${it.message}") }.getOrNull()

        val hits = retrieval?.results.orEmpty()
        val glsl = runCatching { GlslIncludeLibraryIndex.contextAttachmentFor(query) }
            .onFailure { warn("glsl include lookup failed: ${it.message}") }
            .getOrNull()

        if (hits.isEmpty() && glsl == null) {
            // An answer with nothing behind it reads exactly like one with sources. Refuse instead.
            warn("no local retrieval context for query; refusing to answer ungrounded")
            val why = if (retrieval == null) "the local search index could not be queried"
                else "nothing in Field's indexed documentation, source or workspace matched"
            return SearchResult(
                success = false,
                text = "No answer: $why. Try other words, or name a function, class or page.",
                newState = state,
            )
        }
        info("retrieved ${hits.size} hit(s)${if (glsl != null) " + glsl includes" else ""}")

        val context = buildContext(hits, glsl?.code)
        val prompt = buildString {
            if (context.isNotBlank()) {
                appendLine("Retrieved Field4 context for the question below. Ground your answer in it and cite file paths.")
                appendLine()
                appendLine(context)
                appendLine()
            }
            append("Question: ")
            append(query)
        }

        trace?.log("DOCS_SEARCH_QUERY", "thread=${state.thread.localThreadId} hits=${hits.size}\n$prompt")

        return try {
            val result = bridge.send(
                state = state.thread,
                userPrompt = prompt,
                maxOutputTokens = 16384L,
                onTextDelta = onTextDelta
            )
            val text = result.text
            if (text.isBlank()) warn("search(): synthesis returned no text")
            val ms = (System.nanoTime() - t0) / 1_000_000
            info("search() complete: chars=${text.length} time=${ms}ms")
            trace?.log("DOCS_SEARCH_RESPONSE", "thread=${state.thread.localThreadId} chars=${text.length}\n$text")
            SearchResult(success = text.isNotBlank(), text = text, newState = state)
        } catch (e: Exception) {
            error("search() failed: ${e.message}")
            SearchResult(success = false, text = "Error: ${e.message}", newState = state)
        }
    }

    private fun buildContext(hits: List<SemanticRetrievalHit>, glslIncludes: String?): String {
        val sb = StringBuilder()
        hits.forEachIndexed { i, hit ->
            val body = hit.sourcePreview.ifBlank { hit.capsule }.trim()
            sb.appendLine("[${i + 1}] ${hit.path}${if (hit.line > 0) ":${hit.line}" else ""}${if (hit.symbol.isNotBlank()) "  (${hit.symbol})" else ""}")
            if (hit.title.isNotBlank() && hit.title != hit.symbol) sb.appendLine(hit.title)
            if (body.isNotBlank()) {
                val lang = hit.language.ifBlank { "" }
                sb.appendLine("```$lang")
                sb.appendLine(truncate(body, perHitChars))
                sb.appendLine("```")
            }
            sb.appendLine()
        }
        if (!glslIncludes.isNullOrBlank()) {
            sb.appendLine("[GLSL include libraries]")
            sb.appendLine("```glsl")
            sb.appendLine(truncate(glslIncludes, perHitChars * 2))
            sb.appendLine("```")
        }
        return sb.toString().trim()
    }

    private fun truncate(s: String, max: Int): String =
        if (s.length <= max) s else s.take(max) + "\n… (truncated)"
}