npm - @adia-ai/llm - Versions diffs - 0.5.4 → 0.5.6 - Mend

@adia-ai/llm 0.5.4 → 0.5.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -3,11 +3,46 @@
 All notable changes to this package are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 _No pending changes._
+## [0.5.6] - 2026-05-14
+### Fixed — §190 (v0.5.6) — `loadGenerators()` resolves packages-root in both dev + prod
+`server.js` learns to resolve `_packagesRoot` first-existing-wins between the dev layout (repo-relative `packages/<name>/…`) and prod layout (rsync'd `/srv/adia-ui/dist/packages/<name>/…` per `scripts/build/site.mjs`). Pre-§190 the generator imports referenced the dev path absolutely, which failed at runtime on the production VM after the §188 cutover took the LLM-gateway path live but left `/api/generate` (zettel + mcp generator imports) unresolved. The fix: cache `_packagesRoot` once, fall back across layouts, then use it for every dynamic import path. Tested locally via `node packages/llm/server.js` against both layouts; production verified by operator post-deploy.
+Plus README polish noting the §188 LLM-gateway routing + the dev-vs-prod packages-root resolution. No public API change.
+## [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
@@ -19,28 +54,21 @@ Tracking the v0.5.4 cycle's prop-fidelity arcs (§163 transpiler fix,
 §164 chunk re-harvest, §165 validator check #19, §166a/b/c audit-script
 family slots 12+13 + smoke shift-left): see root `CHANGELOG.md` for the
 full narrative. This package carries no source changes this cycle.
 ## [0.5.3] - 2026-05-14
 _No pending changes._
 ## [0.5.2] - 2026-05-13
 _Lockstep ride-along (no source change)._
 ## [0.5.1] - 2026-05-13
 _Lockstep ride-along (no source change)._
 ## [0.5.0] - 2026-05-13
 _Lockstep ride-along (no source change)._
 ## [0.4.9] - 2026-05-13
 _No pending changes._
 ## [0.4.8] - 2026-05-12
 ### Ride-along (no source changes)
@@ -48,7 +76,6 @@ _No pending changes._
 Lockstep PATCH cut alongside `@adia-ai/web-components@0.4.8` (§80 event-types codegen for 38 non-form primitives + §85 class-subpath script fix + §89 icons.js split + B+C+D consumer-friction infra), `@adia-ai/web-modules@0.4.8` (FEEDBACK-02 #1 `.d.ts` shipment + `composes:` ADR-0027 wiring), `@adia-ai/a2ui-compose@0.4.8` (§87 zettel `ensureBooted()` race fix + §88 free-form composition mode), `@adia-ai/a2ui-corpus@0.4.8` (catalog regen ride-along), `@adia-ai/a2ui-mcp@0.4.8` (§87 eval threshold rebaseline). Source byte-identical to v0.4.7.
 Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). See root [CHANGELOG.md `## [0.4.8]`](../../../CHANGELOG.md) for the cut narrative.
 ## [0.4.7] - 2026-05-12
 ### Ride-along (no source changes)
@@ -56,19 +83,16 @@ Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4
 Lockstep PATCH cut alongside `@adia-ai/web-components@0.4.7` (§74 `.d.ts` codegen for 73 non-form primitives + §77 non-side-effect `class` subpath per component + class.js helper extractions in agent + toolbar primitives), `@adia-ai/web-modules@0.4.7`, `@adia-ai/a2ui-compose@0.4.7` (§72 `getComponentCatalog()` reads canonical catalog), `@adia-ai/a2ui-corpus@0.4.7` (§72 `corpus/patterns/` + `corpus/compositions/` retired from disk + tarball — v0.4.6 §65 carry-over closed), `@adia-ai/a2ui-mcp@0.4.7`, `@adia-ai/a2ui-retrieval@0.4.7` (§72 vocab reads canonical catalog + dead pattern-embeddings retired). Source byte-identical to v0.4.6.
 Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). See root [CHANGELOG.md `## [0.4.7]`](../../../CHANGELOG.md) for the cut narrative.
 ## [0.4.6] - 2026-05-12
 ### Changed — README currency sweep
 - **`README.md`** — currency + consumer-guide sweep aligned with v0.4.6 [Unreleased] (commit `c94374c9`). Doc-only; no API change.
 ## [0.4.5] - 2026-05-12
 ### Changed — doc-comment refresh (§54)
 - **`models.js`** — header docstring path-rename `apps/genui/gen-ui-ux/` → `apps/genui/app/factory-chat/`. Cross-doc sweep from the §54 GenUI overhaul rename arc. No API change.
 ## [0.4.4] - 2026-05-12
 ### Ride-along (no source changes)
@@ -76,7 +100,6 @@ Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4
 Lockstep PATCH cut alongside `@adia-ai/web-components@0.4.4` (14 yaml gap closures from corpus simplification arc), `@adia-ai/a2ui-runtime@0.4.4` (registry expansion +27 web-modules + renderer kebab-case fix), `@adia-ai/a2ui-compose@0.4.4` (composition-library rename + transpiler `<a>` → Link), `@adia-ai/a2ui-corpus@0.4.4` (corpus simplification arc §36–§51), `@adia-ai/a2ui-mcp@0.4.4` (`get_fragment` tool retirement). Source byte-identical to v0.4.3.
 Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). See root [CHANGELOG.md `## [0.4.4]`](../../../CHANGELOG.md) for the cut narrative.
 ## [0.4.3] - 2026-05-11
 ### Added
@@ -88,7 +111,6 @@ Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4
 Lockstep PATCH cut alongside `@adia-ai/web-components@0.4.3` (input-ui type=number locale + thousands grouping + hold-to-repeat) + `@adia-ai/a2ui-compose@0.4.3` + `@adia-ai/a2ui-retrieval@0.4.3` (process.env browser-compat fix) + `@adia-ai/a2ui-corpus@0.4.3` (catalog regen + chunks re-harvest with new settings-appearance pattern). Apart from the `llm-bridge.js` addition above, source byte-identical to v0.4.2.
 Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). See root [CHANGELOG.md `## [0.4.3]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.4.2] - 2026-05-11
 ### Ride-along (no source changes)
@@ -96,7 +118,6 @@ Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4
 Lockstep PATCH cut alongside `@adia-ai/web-components@0.4.2` (`<input-ui type="number">` rewrite drops native `<input type=number>` wrapping) + `@adia-ai/web-modules@0.4.2` (`<editor-sidebar>` grid-track width-mirror fix). Source byte-identical to v0.4.1.
 Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). See root [CHANGELOG.md `## [0.4.2]`](../../../CHANGELOG.md) for the cut narrative.
 ## [0.4.1] - 2026-05-10
 ### Ride-along (no source changes)
@@ -104,7 +125,6 @@ Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4
 Lockstep PATCH cut alongside `@adia-ai/web-modules@0.4.1` (simple cluster) + `@adia-ai/a2ui-validator@0.4.1` (Phase 3 foundation) + `@adia-ai/a2ui-corpus@0.4.1` (fragment metrics reconciliation). Source byte-identical to v0.4.0.
 Internal `@adia-ai/*` dep ranges bumped from `^0.4.0` to `^0.4.1`. See root [CHANGELOG.md `## [0.4.1]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.4.0] - 2026-05-10
 ### Ride-along (no source changes)
@@ -112,25 +132,21 @@ Internal `@adia-ai/*` dep ranges bumped from `^0.4.0` to `^0.4.1`. See root [CHA
 Lockstep MINOR cut alongside `@adia-ai/web-modules@0.4.0` (ADR-0024 legacy shell shapes retired). Source byte-identical to v0.3.6.
 Internal `@adia-ai/*` dep ranges bumped from `^0.3.0` to `^0.4.0`. See root [CHANGELOG.md `## [0.4.0]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.3.6] - 2026-05-10
 ### Ride-along (no source changes)
 Lockstep version bump only — source byte-identical to v0.3.5. Internal `@adia-ai/*` dep ranges remain at `^0.3.0`. See root [CHANGELOG.md `## [0.3.6]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.3.5] - 2026-05-07
 ### Ride-along (no source changes)
 Lockstep version bump only — source byte-identical to v0.3.4. Internal `@adia-ai/*` dep ranges remain at `^0.3.0`. See root [CHANGELOG.md `## [0.3.5]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.3.4] - 2026-05-07
 ### Ride-along (no source changes)
 Lockstep version bump only — source byte-identical to v0.3.3. Internal `@adia-ai/*` dep ranges remain at `^0.3.0`. See root [CHANGELOG.md `## [0.3.4]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.3.3] - 2026-05-07
 **Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` ranges stay at `^0.3.0` (patch-cut asymmetry — caret floats `0.3.x`).
@@ -171,7 +187,6 @@ Lockstep version bump only — source byte-identical to v0.3.3. Internal `@adia-
   - `adapters/client.test.js` (4) — createClient defaults + override
   - `llm-stub.test.js` (8) — StubLLMAdapter contract for free-tier evals
 - New `npm run test:llm` script for package-scoped runs.
 ## [0.3.2] - 2026-05-06
 **9-package lockstep patch cut to v0.3.2.** All lockstep members share
@@ -186,7 +201,6 @@ version only.
 ### Changed
 - `version`: `0.3.1` → `0.3.2`.
 ## [0.3.1] - 2026-05-06
 **9-package lockstep patch cut.** All 9 published `@adia-ai/*` packages bump 0.3.0 → 0.3.1 per [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).
@@ -197,7 +211,6 @@ This package itself ships **no source changes** in v0.3.1. The cut bumps version
 - `version`: `0.3.0` → `0.3.1`.
 - Internal `@adia-ai/*` dep ranges: unchanged at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).
 ## [0.3.0] - 2026-05-05
 **Initial release as the 9th `@adia-ai/*` lockstep package.** Joins the lockstep at the cut version. All 9 published `@adia-ai/*` packages now share one version, governed by [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy).

package/README.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.6",
+  "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",