@adia-ai/llm 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -8,6 +8,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _No pending changes._
 
+## [0.5.5] - 2026-05-14
+
+### Removed — §188 (v0.5.5) — replace `handleLlmPassthrough` with exe.dev LLM Gateway
+
+**-155 LOC** in `packages/llm/server.js` (692 → 537 lines).
+
+Deleted:
+
+- `LLM_PASSTHROUGH_UPSTREAMS` const + provider-specific adapter map
+- `MODEL_ALLOWLIST` + `MAX_TOKENS_CEILING` env-driven guardrails
+- `handleLlmPassthrough()` function (body parsing, model gating, header scrub, fetch + SSE stream pipe)
+- `handleLlmHealthz()` function
+- 2 route dispatchers (`/api/llm/*` + `/api/llm/healthz`)
+
+These existed to proxy LLM API calls from the browser to upstream providers (Anthropic/OpenAI/Google) with API key injection, model allowlist enforcement, max_tokens ceiling, origin/referer scrub. The §181 implementation predated the discovery that exe.dev (the platform hosting `ui-kit.exe.xyz`) provides this natively at `http://169.254.169.254/gateway/llm/<provider>/<rest>`.
+
+**Production deployment** routes `/api/llm/*` via Caddy reverse_proxy to the exe.dev gateway (see `infra/caddy/llm-gateway.snippet` + `docs/guides/production-llm-proxy-deployment.md`). The browser code path (`packages/llm/llm-bridge.js`) is unchanged — relative `/api/llm/anthropic/v1/messages` resolves identically; Caddy intercepts before this server sees the request.
+
+**Local dev (`npm run dev`) unchanged**: Vite proxy at `vite.config.js:38-80` continues to use the developer's own `ANTHROPIC_API_KEY`. The gateway is link-local (`169.254.169.254`), VM-internal only; localhost dev doesn't reach it.
+
+**What stays in `server.js`**: `/api/chat`, `/api/generate`, `/api/convert-html` — AdiaUI-specific business logic, not generic LLM proxying.
+
+### Lost vs §181 (intentional)
+
+- Model allowlist enforcement (Haiku-only floor at the proxy)
+- `max_tokens` ceiling capping at the proxy
+
+These were defenses against per-key API billing drain when AdiaUI owned the API key. With subscription-billed exe.dev gateway, the subscription IS the cost cap. Per user direction, accepted.
+
+Commit `656b39dd1`. See root CHANGELOG and journal §181-§188 for the full architectural arc.
+
 ## [0.5.4] - 2026-05-14
 
 ### Changed — lockstep ride-along; no source changes

package/README.md

@@ -133,6 +133,31 @@ Either contract works — the client auto-detects which one your proxy
 implements by URL shape. Pick the one that matches your existing
 infrastructure.
 
+#### Platform-native gateways (no proxy code needed)
+
+If your VM runs on a managed platform that provides an **LLM Gateway**
+natively (e.g. **exe.dev** at `http://169.254.169.254/gateway/llm/<provider>/<rest>`
+on every VM, included in subscription), the cleanest production deploy
+skips both contracts above and just **reverse-proxies `/api/llm/*`
+through Caddy/nginx directly to the platform endpoint**. No API key
+in app config, no hand-rolled proxy code, no per-cycle maintenance —
+the platform handles auth, billing, model selection.
+
+The AdiaUI repo demonstrates this pattern. `infra/caddy/llm-gateway.snippet`
+holds a drop-in Caddyfile fragment for exe.dev VMs. The §188 (v0.5.5)
+arc deleted ~155 LOC of hand-rolled passthrough from `server.js` in
+favor of this approach. See `docs/specs/exe-dev-platform-reference.md`
++ `docs/guides/production-llm-proxy-deployment.md` for the full
+recipe and `docs/journal/2026/05/2026-05-14.md §185-§188` for the
+architectural migration arc.
+
+**Stage 0b recon checklist**: before hand-rolling a proxy, check whether
+your platform provides one natively. Look for `LLM Gateway` / `AI` /
+`Inference` in the platform's docs. Other platforms with similar
+gateways: Cloudflare AI Gateway, AWS Bedrock proxy, Azure OpenAI
+private endpoints. Match shape; check pricing; prefer platform-native
+over hand-rolled when available.
+
 ## Subpath exports
 
 | Subpath | Purpose |

package/llm-bridge.js

@@ -55,6 +55,51 @@ function resolveBaseUrl(provider) {
   return proxyMap[provider];
 }
 
+/**
+ * §181 (v0.5.5) — Is the browser running on a production host (not a
+ * local Vite dev server)? Used by createAdapter() to decide whether
+ * to construct a real bridge that routes through the same-origin proxy
+ * even when no API key is visible to the browser.
+ */
+function isProductionHost() {
+  if (!IS_BROWSER) return false;
+  const host = window.location?.hostname || '';
+  if (!host) return false;
+  if (host === 'localhost' || host === '127.0.0.1' || host === '0.0.0.0') return false;
+  if (host.endsWith('.local')) return false;
+  if (/^10\./.test(host)) return false;
+  if (/^192\.168\./.test(host)) return false;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return false;
+  return true;
+}
+
+/**
+ * §181 (v0.5.5) — Build a bridge for the production-browser case
+ * where there's no client-side API key but the page can reach a
+ * same-origin proxy at /api/llm/<provider>/<rest>. The proxy strips
+ * the incoming auth header and injects its own server-side key.
+ *
+ * Uses a sentinel "browser-uses-proxy" string for the apiKey so the
+ * underlying client passes its non-empty check. The sentinel never
+ * reaches the upstream provider — the proxy discards it.
+ */
+async function createBrowserProxyBridge(provider, modelOpt) {
+  const createClient = await getCreateClient();
+  if (!createClient) {
+    console.warn('LLM Bridge: LLM module not available. Using stub adapter.');
+    return new StubLLMAdapter();
+  }
+  const model = modelOpt || DEFAULT_MODELS[provider] || 'claude-haiku-4-5-20251001';
+  const proxyUrl = resolveBaseUrl(provider);
+  const client = createClient({
+    provider,
+    apiKey: 'browser-uses-server-side-proxy-key',  // sentinel; proxy ignores it
+    model,
+    ...(proxyUrl ? { proxyUrl } : {}),
+  });
+  return new AdiaUILLMBridge(client, model, provider);
+}
+
 // ── Factory ──────────────────────────────────────────────────────────────
 
 /**
@@ -73,7 +118,20 @@ export async function createAdapter(opts = {}) {
   const provider = opts.provider || getEnv('LLM_PROVIDER') || detectProvider();
   const model = opts.model || getEnv('LLM_MODEL') || undefined;
 
-  if (provider === 'stub') return new StubLLMAdapter();
+  if (provider === 'stub') {
+    // §181 (v0.5.5) — browser on a production host: even though
+    // detectProvider() returned 'stub' (no env vars in the browser),
+    // the page can still make real LLM calls via the same-origin
+    // proxy at /api/llm/<provider>/<rest>. The proxy strips the
+    // incoming x-api-key / Authorization header and re-injects its
+    // own server-side key. The sentinel below is a non-empty
+    // placeholder so the bridge passes the !apiKey gate; it never
+    // reaches the upstream provider.
+    if (IS_BROWSER && isProductionHost()) {
+      return createBrowserProxyBridge('anthropic', opts.model);
+    }
+    return new StubLLMAdapter();
+  }
 
   // Resolve API key for the detected provider
   const apiKey = opts.apiKey || getEnv(`${provider.toUpperCase()}_API_KEY`) || getEnv('ANTHROPIC_API_KEY') || getEnv('OPENAI_API_KEY') || getEnv('GOOGLE_API_KEY');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adia-ai/llm",
-  "version": "0.5.4",
-  "description": "Provider-agnostic LLM client — anthropic / openai / gemini adapters with a unified chat() + streamChat() facade. Used by AdiaUI's chat-shell and the A2UI generation pipeline; works in browser (with proxyUrl) and Node.",
+  "version": "0.5.5",
+  "description": "Provider-agnostic LLM client \u2014 anthropic / openai / gemini adapters with a unified chat() + streamChat() facade. Used by AdiaUI's chat-shell and the A2UI generation pipeline; works in browser (with proxyUrl) and Node.",
   "type": "module",
   "exports": {
     ".": "./index.js",