@genesislcap/blank-app-seed 5.27.2-prerelease.3 → 5.28.1

package/.genx/scripts/generate-test-apps.sh

@@ -6,7 +6,9 @@
 # routes), a "full" app driven by .genx/tests/fixtures/routes-full.json
 # (every tile type: entity-manager with permissions/custom events/eventing/FDC3,
 # grid-pro with listener/reqrep, chart, smart-form), and an "fdc3" app with
-# FDC3 channels enabled — then runs the ox lint pipeline with zero tolerance:
+# FDC3 channels enabled, plus for React an "ai" app driven by .genx/tests/fixtures/ai-config.json
+# (the AI chat panel, whose configuration carries a prompt full of Handlebars) — then runs the ox lint
+# pipeline with zero tolerance:
 #
 #   oxlint . --deny-warnings   # zero errors, zero warnings
 #   oxfmt --check .            # formatting is already canonical
@@ -24,7 +26,9 @@
 #              By default an app is deleted as soon as it passes, so a run only
 #              ever holds one app's node_modules at a time. Failing apps are
 #              always kept.
-#   BUILD=1    additionally run `npx tsc --noEmit` and `npm run build` per app
+#   BUILD=1    additionally run `npx tsc --noEmit` and `npm run build` per app, and for the React
+#              ai app check that the assistant is built into a chunk of its own, and that the seed's
+#              .genx/ai-consumer.json is within what the installed assistant reads (C-15A.6 S-6)
 #
 # Installs use the app's own bootstrap semantics (plain `npm install`) — NOT
 # --legacy-peer-deps, which would skip the ag-grid peer deps and break builds.
@@ -33,6 +37,7 @@ set -uo pipefail
 
 SEED_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 FIXTURE="$SEED_DIR/.genx/tests/fixtures/routes-full.json"
+AI_FIXTURE="$SEED_DIR/.genx/tests/fixtures/ai-config.json"
 
 if [ $# -gt 0 ]; then
   FRAMEWORKS=("$@")
@@ -55,6 +60,23 @@ fi
 
 FAILURES=()
 
+# The assistant loads in a chunk of its own once the layout mounts. The code behind the assistant's
+# registration and the bubble ('pulse-ring' is the bubble's own markup) must be in that chunk and in no
+# other: the entry chunk and the PBC chunk both load at startup. Both names survive minification.
+check_assistant_chunk() {
+  local entry chunk marker other
+  entry="dist/$(grep -oE 'assets/index-[^"]+\.js' dist/index.html | head -1)"
+  chunk="$(ls dist/assets/assistant-*.js 2>/dev/null | head -1)"
+  [ -n "$chunk" ] || { echo "no assistant-*.js chunk in dist/assets"; return 1; }
+  [ -f "$entry" ] || { echo "no entry chunk named in dist/index.html"; return 1; }
+  for marker in registerGenesisAssistant pulse-ring; do
+    grep -q "$marker" "$chunk" || { echo "$marker is not in $chunk"; return 1; }
+    other="$(grep -l "$marker" dist/assets/*.js | grep -vxF "$chunk")"
+    [ -z "$other" ] || { echo "$marker is also in $other"; return 1; }
+  done
+  ! grep -q foundation-ai-chat-bubble "$entry" || { echo "the entry chunk $entry names the chat bubble"; return 1; }
+}
+
 run_lint_checks() {
   local app_dir="$1" label="$2"
   (
@@ -72,12 +94,21 @@ run_lint_checks() {
       npx tsc --noEmit || exit 1
       echo "--- [$label] npm run build"
       npm run build || exit 1
+      if [ "$label" = "react-ai" ]; then
+        echo "--- [$label] the assistant is built into a chunk of its own"
+        check_assistant_chunk || exit 1
+        echo "--- [$label] the seed's AI declaration is within what the installed assistant reads"
+        node "$SEED_DIR/.genx/scripts/check-ai-declaration.mjs" "$SEED_DIR/.genx/ai-consumer.json" . || exit 1
+      fi
     fi
   )
 }
 
 for fw in "${FRAMEWORKS[@]}"; do
-  for variant in default full fdc3; do
+  variants=(default full fdc3)
+  # The chat panel is React only, like the AI gate in configure.js.
+  [ "$fw" = "react" ] && variants+=(ai)
+  for variant in "${variants[@]}"; do
     label="$fw-$variant"
     app_dir="$WORK_DIR/$label"
     rm -rf "$app_dir"
@@ -86,6 +117,9 @@ for fw in "${FRAMEWORKS[@]}"; do
     if [ "$variant" = "full" ]; then
       extra_args=(--routes "$(cat "$FIXTURE")")
     fi
+    if [ "$variant" = "ai" ]; then
+      extra_args=(--ui "$(cat "$AI_FIXTURE")")
+    fi
     if [ "$variant" = "fdc3" ]; then
       extra_args=(--ui '{"fdc3":{"channels":[{"name":"positions","type":"position"},{"name":"instrumentChannel","type":"fdc3.instrument"}]}}')
     fi
@@ -115,7 +149,7 @@ if [ ${#FAILURES[@]} -gt 0 ]; then
   exit 1
 fi
 
-echo "All generated apps are lint-clean: ${FRAMEWORKS[*]} (default + full + fdc3)"
+echo "All generated apps are lint-clean: ${FRAMEWORKS[*]} (default + full + fdc3, and ai for React)"
 if [ "${KEEP:-0}" = "1" ]; then
   echo "Generated apps kept in $WORK_DIR"
 elif [ "$OWNS_WORK_DIR" = "1" ]; then

package/.genx/templates/react/ai/assistant-host.ts.hbs

@@ -0,0 +1,30 @@
+import { css, customElement, GenesisElement } from '@genesislcap/web-core';
+
+const styles = css`
+  :host,
+  foundation-ai-assistant {
+    display: flex;
+    width: 100%;
+    height: 100%;
+  }
+`;
+
+/**
+ * Holds the assistant in the chat bubble's dialog. The bubble gives the assistant its close button by
+ * looking for it in this element's shadow root when the dialog opens, so it has to be there by then.
+ *
+ * The assistant's code loads when this element reaches the page rather than with the app. The bubble
+ * and the popout manager around it come from the same package, and upgrade when it arrives.
+ */
+@customElement({ name: 'genesis-app-assistant', styles })
+export class AiAssistantHost extends GenesisElement {
+  connectedCallback(): void {
+    super.connectedCallback();
+    void import('./assistant').then(({ mountAssistant }) => {
+      // The layout may have rebuilt its targets while the code loaded.
+      if (this.isConnected && this.shadowRoot) {
+        mountAssistant(this.shadowRoot);
+      }
+    });
+  }
+}

package/.genx/templates/react/ai/assistant.ts.hbs

@@ -0,0 +1,52 @@
+import '@genesislcap/ai-assistant';
+import type { FoundationAiAssistant } from '@genesislcap/ai-assistant';
+import { type GenesisAiConfig, registerGenesisAssistant } from '@genesislcap/ai-assistant/genesis';
+import { getUser } from '@genesislcap/foundation-user';
+import { extensions } from '../extensions';
+import aiConfig from './ai-config.json';
+
+// The right the app's chat proxy demands. Genesis Create grants it through the AI_CHAT_USER profile.
+const AI_CHAT_RIGHT = 'AI_CHAT';
+const NO_RIGHT = `You need the ${AI_CHAT_RIGHT} right to use the assistant. An administrator can add you to the AI_CHAT_USER profile.`;
+
+// Registered once, when this module first loads and before any assistant element exists: an element that
+// connects first keeps a provider that does nothing for the rest of the page's life.
+const registration = registerGenesisAssistant({
+  config: aiConfig as GenesisAiConfig,
+  extensions,
+});
+
+// One assistant for the page, kept across the layout rebuilding its targets (it does on every
+// reconnect). Its conversation is kept in memory under `session-key` for the page's life, one per
+// signed-in user; a reload starts a new one.
+let assistant: FoundationAiAssistant | undefined;
+
+// Checked on every mount: the user can change while the layout is off the page (the login page has
+// none), and a block written then never reaches the assistant's store.
+function applyBlocks(target: FoundationAiAssistant): void {
+  if (registration.blockedReason) {
+    target.setBlocked(true, registration.blockedReason);
+    return;
+  }
+  // Without the right the router refuses every call, and the chat would only show a generic error. So
+  // the assistant stays blocked, saying why and sending nothing. Only a block of its own is lifted.
+  const noRight = !getUser().hasPermission(AI_CHAT_RIGHT);
+  const blockedForRight = target.blocked && target.blockedReason === NO_RIGHT;
+  if (noRight !== blockedForRight) {
+    target.setBlocked(noRight, noRight ? NO_RIGHT : null);
+  }
+}
+
+export function mountAssistant(host: ParentNode): void {
+  const sessionKey = `genesis-app-assistant:${getUser().userName}`;
+  if (!assistant) {
+    assistant = document.createElement('foundation-ai-assistant') as FoundationAiAssistant;
+    assistant.setAttribute('session-key', sessionKey);
+    assistant.agents = registration.agents;
+  }
+  host.append(assistant);
+  // Set while connected, so a different user switches the assistant to a session of their own and the
+  // previous one, with its history, is torn down.
+  assistant.setAttribute('session-key', sessionKey);
+  applyBlocks(assistant);
+}

package/.genx/templates/react/ai/extensions.ts.hbs

@@ -0,0 +1,17 @@
+// Your own additions to the AI assistant. This file is yours; Genesis Create's UI Builder may edit it
+// too. It imports nothing, so it still compiles if the assistant is ever removed: the assistant checks
+// it against GenesisAssistantExtensions (from @genesislcap/ai-assistant/genesis) where it reads it.
+//
+// A tool is a definition the model sees and a handler that runs it, under one name, for example:
+//
+//   toolDefinitions: [
+//     {
+//       name: 'current_time',
+//       description: 'The current date and time.',
+//       parameters: { type: 'object', properties: {} },
+//     },
+//   ],
+//   toolHandlers: { current_time: async () => new Date().toISOString() },
+//
+// A tool may not reuse the name of one the app generates from its data (req_* and event_*).
+export const extensions = {};

package/.genx/templates/react/ai/pbc-elements.ts.hbs

@@ -0,0 +1,17 @@
+import type { AppElement } from '@genesislcap/foundation-shell/app';
+import { html } from '@genesislcap/web-core';
+import '../../ai/generated/assistant-host';
+
+/**
+ * The AI assistant, in a chat bubble added after every page's content (the layout's 'layout-end' target).
+ */
+export const aiAssistant: AppElement = {
+  targetId: 'layout-end',
+  elements: html`
+    <foundation-ai-popout-manager>
+      <foundation-ai-chat-bubble title="AI Assistant">
+        <genesis-app-assistant slot="dialog-content"></genesis-app-assistant>
+      </foundation-ai-chat-bubble>
+    </foundation-ai-popout-manager>
+  `,
+};

package/.genx/templates/server/ai-service-web-handler.kts.hbs

@@ -0,0 +1,394 @@
+// Exempts only the build-time auth-map scan: this proxy returns no entity rows. The AI_CHAT right
+// below is still enforced by the router on every call.
+@file:global.genesis.commons.annotation.AuthDisabled
+
+/*
+ * AI chat proxy — generated with this application, safe to edit.
+ *
+ * Your app's own endpoint for the chat panel: the browser talks to this, and this talks to the
+ * vendor with YOUR key. The key is read from the environment that starts the server, never from a
+ * file in this project: set AI_ANTHROPIC_API_KEY (or AI_GEMINI_API_KEY) there and restart it. A
+ * user needs the AI_CHAT right to call these.
+ */
+import com.fasterxml.jackson.core.JsonFactory
+import com.fasterxml.jackson.core.JsonProcessingException
+import com.fasterxml.jackson.core.StreamReadConstraints
+import com.fasterxml.jackson.core.exc.StreamConstraintsException
+import com.fasterxml.jackson.databind.JsonNode
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.fasterxml.jackson.databind.node.ObjectNode
+import global.genesis.config.system.SystemDefinitionService
+import global.genesis.message.core.HttpStatusCode
+import java.net.URI
+import java.net.http.HttpClient
+import java.net.http.HttpRequest as JdkHttpRequest
+import java.net.http.HttpResponse as JdkHttpResponse
+import java.net.http.HttpTimeoutException
+import java.time.Duration
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.future.await
+
+webHandlers("ai-service") {
+
+    val systemDefinition = inject<SystemDefinitionService>()
+    // Bounded parsing: at this 5 MiB document limit, a body of tiny objects would build a tree many
+    // times its own size. A real chat turn is far inside these limits. The router lets a little more
+    // through (6 MiB), so a body just over this limit is answered here, with REQUEST_TOO_LARGE.
+    val mapper = ObjectMapper(
+        JsonFactory.builder()
+            .streamReadConstraints(
+                StreamReadConstraints.builder()
+                    .maxDocumentLength(5_242_880L)
+                    .maxTokenCount(250_000L)
+                    .maxNestingDepth(64)
+                    .build()
+            )
+            .build()
+    )
+    val http = HttpClient.newBuilder()
+        .connectTimeout(Duration.ofSeconds(20))
+        .build()
+
+    // An upstream status the platform enum does not know would throw on the way out, so anything
+    // unrecognised becomes a plain bad gateway. 529 (the vendors' "overloaded") is not in the enum
+    // either, and it maps to 503 so a client's own retry ladder treats it as retryable.
+    fun upstreamStatus(code: Int): HttpStatusCode = when (code) {
+        529 -> HttpStatusCode.ServiceUnavailable
+        else -> try {
+            HttpStatusCode.valueOf(code)
+        } catch (e: IllegalArgumentException) {
+            HttpStatusCode.BadGateway
+        }
+    }
+
+    // A system-definition read can throw: an encrypted item with a missing or wrong GenesisKey. So every
+    // read goes through here, and only the exception's type is logged. One that escaped would be logged
+    // by the platform with the caller's session, and its message (the key's length, even) could reach
+    // the browser.
+    fun readItem(name: String): Result<String?> = try {
+        Result.success(systemDefinition.get(name).orElse(null))
+    } catch (e: Exception) {
+        LOG.warn("ai-service: could not read " + name + ": " + e.javaClass.simpleName)
+        Result.failure(e)
+    }
+
+    // The keys come straight from the process environment, never from the system definition: a build
+    // writes every system-definition item, a GENESIS_SYSDEF_ one included, in plain text into
+    // build/genesis-home/generated/cfg/generated-system-definition.json, so a key read that way ends
+    // up in every copy of build/.
+    fun keyFor(vendor: String): String = java.lang.System.getenv("AI_" + vendor + "_API_KEY")?.trim() ?: ""
+
+    // A key set the old way is not used: the proxy answers as if none were set. A plain one is already
+    // in the build files. Said once, without the value.
+    for (vendor in listOf("ANTHROPIC", "GEMINI")) {
+        if (java.lang.System.getenv("GENESIS_SYSDEF_AI_" + vendor + "_API_KEY") != null) {
+            LOG.warn(
+                "ai-service: GENESIS_SYSDEF_AI_" + vendor + "_API_KEY is written into the app's build files, " +
+                    "so it is not used; set AI_" + vendor + "_API_KEY instead, delete the app's build " +
+                    "directory and rotate the key"
+            )
+        }
+        if (java.lang.System.getenv("GENESIS_ENCRYPTED_SYSDEF_AI_" + vendor + "_API_KEY") != null) {
+            LOG.warn(
+                "ai-service: GENESIS_ENCRYPTED_SYSDEF_AI_" + vendor + "_API_KEY is not read; set AI_" + vendor +
+                    "_API_KEY instead"
+            )
+        }
+    }
+
+    // The limits this app was generated with. They live here, not in a system-definition file,
+    // because a generator may rewrite that file; a system-definition item of the same name overrides
+    // them (GENESIS_SYSDEF_AI_ALLOWED_MODELS, GENESIS_SYSDEF_AI_MAX_OUTPUT_TOKENS).
+    val defaultAllowedModels = "{{AI.allowedModels}}"
+    val defaultMaxOutputTokens = "{{AI.maxOutputTokens}}"
+
+    // The model a request asks for has to be one this app allows, whatever the browser sent: the
+    // panel is not the only thing that can post here. AI_ALLOWED_MODELS set but EMPTY refuses every
+    // model, so a setting that failed to load is never an open door to the most expensive one.
+    val allowedModels = (readItem("AI_ALLOWED_MODELS").getOrElse { "" } ?: defaultAllowedModels)
+        .split(",")
+        .map { it.trim() }
+        .filter { it.isNotEmpty() }
+    if (allowedModels.isEmpty()) {
+        LOG.warn("ai-service: AI_ALLOWED_MODELS is empty or unreadable, so every chat request will be refused")
+    }
+
+    // A cap is a whole number from 1 to 1000000. An override that is not one is ignored, with a
+    // warning that names the item, rather than turning into a cap nobody chose.
+    fun tokenCap(raw: String?): Int? = raw?.trim()?.toIntOrNull()?.takeIf { it in 1..1_000_000 }
+    val generatedMaxOutputTokens = tokenCap(defaultMaxOutputTokens) ?: 16000
+    val maxOutputTokens = readItem("AI_MAX_OUTPUT_TOKENS").getOrNull()?.let { raw ->
+        tokenCap(raw) ?: generatedMaxOutputTokens.also {
+            LOG.warn("ai-service: AI_MAX_OUTPUT_TOKENS is not a whole number from 1 to 1000000, so the generated default applies")
+        }
+    } ?: generatedMaxOutputTokens
+
+    // Clamp DOWN to the cap, and never below 1: a request asking for less keeps what it asked for.
+    fun clamp(requested: Int): Int = requested.coerceIn(1, maxOutputTokens)
+
+    // A model id is also a path segment in the Gemini URL, so even an allowed one must be a bare id.
+    val modelId = Regex("[A-Za-z0-9][A-Za-z0-9._-]*")
+
+    fun modelAllowed(model: String): Boolean = modelId.matches(model) && allowedModels.contains(model)
+
+    // A key with a character a request header cannot carry (a pasted zero-width space, a smart quote)
+    // makes the request builder throw, and the platform echoes that exception, key and all.
+    val keyChars = Regex("[\\x21-\\x7E]+")
+
+    // Whatever a vendor sends back, the key does not go to the browser in it.
+    fun withoutKey(text: String, apiKey: String): String = text.replace(apiKey, "[redacted]")
+
+    grouping("anthropic") {
+        // No transaction: the proxy touches no rows, and one would hold a pooled database connection
+        // for the whole vendor call, starving every other request that needs one.
+        endpoint<String, Any>(POST, "chat", transactional = false) {
+            // No produces() and no accepts(): each adds a required header, matched by its exact name,
+            // so the panel's Accept: application/x-ndjson, or a proxy sending a lowercase content-type,
+            // would get a 406. The body is parsed as JSON anyway, and replies go out as JSON.
+
+            // Never set requiresAuth = false: it makes this endpoint anonymous and drops the AI_CHAT
+            // check, and the build's security scan still reports the endpoint as secure.
+            permissioning {
+                permissionCodes("AI_CHAT")
+            }
+
+            handleRequest {
+                val apiKey = keyFor("ANTHROPIC")
+                if (apiKey.isEmpty()) {
+                    // 424, never 503: a client retries a 503 and the user waits instead of being
+                    // told the one thing that fixes this.
+                    error(
+                        HttpStatusCode.FailedDependency,
+                        mapOf(
+                            "code" to "NO_API_KEY",
+                            "error" to "No anthropic API key is configured for this application. " +
+                                "Set AI_ANTHROPIC_API_KEY in the server's environment and restart."
+                        )
+                    )
+                }
+                if (!keyChars.matches(apiKey)) {
+                    error(
+                        HttpStatusCode.FailedDependency,
+                        mapOf(
+                            "code" to "BAD_API_KEY",
+                            "error" to "The anthropic API key configured for this application contains characters " +
+                                "an API key cannot have. Set AI_ANTHROPIC_API_KEY again and restart."
+                        )
+                    )
+                }
+
+                val payload = try {
+                    mapper.readTree(body) as? ObjectNode
+                } catch (e: StreamConstraintsException) {
+                    error(
+                        HttpStatusCode.RequestTooLong,
+                        mapOf("code" to "REQUEST_TOO_LARGE", "error" to "The request is larger or more deeply nested than this endpoint accepts.")
+                    )
+                } catch (e: JsonProcessingException) {
+                    null
+                } ?: error(
+                        HttpStatusCode.BadRequest,
+                        mapOf("code" to "BAD_REQUEST", "error" to "The request body must be a JSON object.")
+                    )
+
+                // The chat panel never streams through this proxy, and a streamed reply would hold the
+                // call open with no timeout once its headers arrived.
+                if (payload.path("stream").asBoolean(false)) {
+                    error(
+                        HttpStatusCode.BadRequest,
+                        mapOf("code" to "BAD_REQUEST", "error" to "Streaming is not supported by this endpoint.")
+                    )
+                }
+
+                val model = payload.path("model").asText("")
+                if (!modelAllowed(model)) {
+                    error(
+                        HttpStatusCode.BadRequest,
+                        mapOf(
+                            "code" to "MODEL_NOT_ALLOWED",
+                            "error" to "Model '" + model + "' is not in AI_ALLOWED_MODELS for this application.",
+                            "allowedModels" to allowedModels
+                        )
+                    )
+                }
+
+                val requestedMaxTokens = payload.path("max_tokens").asInt(maxOutputTokens)
+                payload.put("max_tokens", clamp(requestedMaxTokens))
+
+                // No fallback models: each would be another model and token size to hold to the limits
+                // above, and Anthropic needs a beta header to accept them. Refused, not passed through.
+                val fallbacks = payload.get("fallbacks")
+                if (fallbacks != null && !fallbacks.isNull) {
+                    error(
+                        HttpStatusCode.BadRequest,
+                        mapOf("code" to "FALLBACKS_NOT_SUPPORTED", "error" to "Fallback models are not supported by this endpoint.")
+                    )
+                }
+
+                val response = try {
+                    val upstream = JdkHttpRequest.newBuilder()
+                        .uri(URI.create("https://api.anthropic.com/v1/messages"))
+                        .timeout(Duration.ofSeconds(280))
+                        .header("content-type", "application/json")
+                        .header("x-api-key", apiKey)
+                        .header("anthropic-version", "2023-06-01")
+                        .POST(JdkHttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(payload)))
+                        .build()
+                    // Async, so no thread is held while the vendor works. Nothing cancels the call once it is
+                    // sent: a caller who goes away does not stop it, and it is billed as usual.
+                    http.sendAsync(upstream, JdkHttpResponse.BodyHandlers.ofString()).await()
+                } catch (e: CancellationException) {
+                    throw e
+                } catch (e: Exception) {
+                    // Only the type is logged: an exception's message can carry what the request was
+                    // built from, and one that escapes is logged by the platform with the caller's cookies.
+                    LOG.warn("ai-service: anthropic call failed: " + e.javaClass.simpleName)
+                    val timedOut = e is HttpTimeoutException || e.cause is HttpTimeoutException
+                    error(
+                        if (timedOut) HttpStatusCode.GatewayTimeout else HttpStatusCode.BadGateway,
+                        mapOf("code" to "VENDOR_UNREACHABLE", "error" to "The AI vendor could not be reached. Try again.")
+                    )
+                }
+
+                if (response.statusCode() !in 200..299) {
+                    // The vendor's own body travels back untouched — a billing refusal or a rate
+                    // limit says more than anything this proxy could put in its place.
+                    LOG.warn("ai-service: anthropic returned " + response.statusCode())
+                    error(upstreamStatus(response.statusCode()), withoutKey(response.body(), apiKey))
+                }
+
+                // Declared Any, so the router writes this String as its own bytes labelled application/json,
+                // whatever the browser's Accept says. (A String type would label it with that Accept, and
+                // buildResponse/jsonBody grows the router's composer cache by one entry per reply.)
+                withoutKey(response.body(), apiKey)
+            }
+        }
+    }
+
+    grouping("gemini") {
+        // No transaction: the proxy touches no rows, and one would hold a pooled database connection
+        // for the whole vendor call, starving every other request that needs one.
+        endpoint<String, Any>(POST, "chat", transactional = false) {
+            // No produces() and no accepts(): each adds a required header, matched by its exact name,
+            // so the panel's Accept: application/x-ndjson, or a proxy sending a lowercase content-type,
+            // would get a 406. The body is parsed as JSON anyway, and replies go out as JSON.
+
+            // Never set requiresAuth = false: it makes this endpoint anonymous and drops the AI_CHAT
+            // check, and the build's security scan still reports the endpoint as secure.
+            permissioning {
+                permissionCodes("AI_CHAT")
+            }
+
+            handleRequest {
+                val apiKey = keyFor("GEMINI")
+                if (apiKey.isEmpty()) {
+                    // 424, never 503: a client retries a 503 and the user waits instead of being
+                    // told the one thing that fixes this.
+                    error(
+                        HttpStatusCode.FailedDependency,
+                        mapOf(
+                            "code" to "NO_API_KEY",
+                            "error" to "No gemini API key is configured for this application. " +
+                                "Set AI_GEMINI_API_KEY in the server's environment and restart."
+                        )
+                    )
+                }
+                if (!keyChars.matches(apiKey)) {
+                    error(
+                        HttpStatusCode.FailedDependency,
+                        mapOf(
+                            "code" to "BAD_API_KEY",
+                            "error" to "The gemini API key configured for this application contains characters " +
+                                "an API key cannot have. Set AI_GEMINI_API_KEY again and restart."
+                        )
+                    )
+                }
+
+                val payload = try {
+                    mapper.readTree(body) as? ObjectNode
+                } catch (e: StreamConstraintsException) {
+                    error(
+                        HttpStatusCode.RequestTooLong,
+                        mapOf("code" to "REQUEST_TOO_LARGE", "error" to "The request is larger or more deeply nested than this endpoint accepts.")
+                    )
+                } catch (e: JsonProcessingException) {
+                    null
+                } ?: error(
+                        HttpStatusCode.BadRequest,
+                        mapOf("code" to "BAD_REQUEST", "error" to "The request body must be a JSON object.")
+                    )
+
+                val model = payload.path("model").asText("")
+                if (!modelAllowed(model)) {
+                    error(
+                        HttpStatusCode.BadRequest,
+                        mapOf(
+                            "code" to "MODEL_NOT_ALLOWED",
+                            "error" to "Model '" + model + "' is not in AI_ALLOWED_MODELS for this application.",
+                            "allowedModels" to allowedModels
+                        )
+                    )
+                }
+
+                // The model addresses the endpoint in the URL, so it must not also ride in the body.
+                payload.remove("model")
+
+                // Gemini also reads the snake_case spellings, which would sit beside the camelCase fields
+                // the limits below set, and escape them. The chat panel never sends them.
+                val snakeCase = listOf("generation_config").filter { payload.has(it) } +
+                    listOf("max_output_tokens", "candidate_count").filter { payload.path("generationConfig").has(it) }
+                if (snakeCase.isNotEmpty()) {
+                    error(
+                        HttpStatusCode.BadRequest,
+                        mapOf("code" to "BAD_REQUEST", "error" to "Use the camelCase field names; " + snakeCase.joinToString() + " is not accepted.")
+                    )
+                }
+
+                val generationConfig = payload.path("generationConfig") as? ObjectNode
+                    ?: mapper.createObjectNode().also { payload.set<JsonNode>("generationConfig", it) }
+                val requestedMaxTokens = generationConfig.path("maxOutputTokens").asInt(maxOutputTokens)
+                generationConfig.put("maxOutputTokens", clamp(requestedMaxTokens))
+                // One candidate: each extra one is generated, and billed, up to the same ceiling again.
+                if (generationConfig.has("candidateCount")) {
+                    generationConfig.put("candidateCount", 1)
+                }
+
+                val response = try {
+                    val upstream = JdkHttpRequest.newBuilder()
+                        .uri(URI.create("https://generativelanguage.googleapis.com/v1beta/models/" + model + ":generateContent"))
+                        .timeout(Duration.ofSeconds(280))
+                        .header("content-type", "application/json")
+                        .header("x-goog-api-key", apiKey)
+                        .POST(JdkHttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(payload)))
+                        .build()
+                    // Async, so no thread is held while the vendor works. Nothing cancels the call once it is
+                    // sent: a caller who goes away does not stop it, and it is billed as usual.
+                    http.sendAsync(upstream, JdkHttpResponse.BodyHandlers.ofString()).await()
+                } catch (e: CancellationException) {
+                    throw e
+                } catch (e: Exception) {
+                    // Only the type is logged: an exception's message can carry what the request was
+                    // built from, and one that escapes is logged by the platform with the caller's cookies.
+                    LOG.warn("ai-service: gemini call failed: " + e.javaClass.simpleName)
+                    val timedOut = e is HttpTimeoutException || e.cause is HttpTimeoutException
+                    error(
+                        if (timedOut) HttpStatusCode.GatewayTimeout else HttpStatusCode.BadGateway,
+                        mapOf("code" to "VENDOR_UNREACHABLE", "error" to "The AI vendor could not be reached. Try again.")
+                    )
+                }
+
+                if (response.statusCode() !in 200..299) {
+                    // The vendor's own body travels back untouched — a billing refusal or a rate
+                    // limit says more than anything this proxy could put in its place.
+                    LOG.warn("ai-service: gemini returned " + response.statusCode())
+                    error(upstreamStatus(response.statusCode()), withoutKey(response.body(), apiKey))
+                }
+
+                // Declared Any, so the router writes this String as its own bytes labelled application/json,
+                // whatever the browser's Accept says. (A String type would label it with that Accept, and
+                // buildResponse/jsonBody grows the router's composer cache by one entry per reply.)
+                withoutKey(response.body(), apiKey)
+            }
+        }
+    }
+}