@warmdrift/kgauto-compiler 2.0.0-alpha.57 → 2.0.0-alpha.59

package/dist/chunk-B4INZ32V.mjs

@@ -0,0 +1,185 @@
+// src/key-health.ts
+var JSON_HEADERS = { "Content-Type": "application/json" };
+function jsonResponse(status, body) {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+function bearerOf(req) {
+  const header = req.headers.get("Authorization") ?? "";
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  return match?.[1]?.trim() ?? "";
+}
+function requireString(name, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`createKeyHealthRoute: ${name} is required`);
+  }
+  return value;
+}
+function envKey(env, name) {
+  const v = env[name];
+  if (typeof v !== "string") return void 0;
+  const trimmed = v.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+var PROBE_SPECS = [
+  {
+    provider: "anthropic",
+    canonicalEnvName: "ANTHROPIC_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.anthropic.com/v1/models?limit=1",
+      headers: { "x-api-key": key, "anthropic-version": "2023-06-01" }
+    })
+  },
+  {
+    provider: "deepseek",
+    canonicalEnvName: "DEEPSEEK_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.deepseek.com/user/balance",
+      headers: { Authorization: `Bearer ${key}` }
+    }),
+    parseBalanceUsd: (body) => {
+      const infos = body?.balance_infos;
+      if (!Array.isArray(infos) || infos.length === 0) return void 0;
+      const first = infos[0];
+      if (first?.currency !== "USD") return void 0;
+      const n = Number(first.total_balance);
+      return Number.isFinite(n) ? n : void 0;
+    }
+  },
+  {
+    provider: "google",
+    canonicalEnvName: "GEMINI_API_KEY",
+    buildRequest: (key) => ({
+      url: `https://generativelanguage.googleapis.com/v1beta/models?pageSize=1&key=${encodeURIComponent(key)}`,
+      headers: {}
+    })
+  },
+  {
+    provider: "openai",
+    canonicalEnvName: "OPENAI_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.openai.com/v1/models",
+      headers: { Authorization: `Bearer ${key}` }
+    })
+  }
+];
+function createKeyHealthRoute(config) {
+  const appId = requireString("appId", config.appId);
+  const ingestSecret = requireString("ingestSecret", config.ingestSecret);
+  const fetchFn = config.fetchImpl ?? fetch;
+  const timeoutMs = config.timeoutMs ?? 3e3;
+  async function probeProvider(spec, env) {
+    let key;
+    let envName = spec.canonicalEnvName;
+    if (spec.provider === "google") {
+      const gemini = envKey(env, "GEMINI_API_KEY");
+      const google = envKey(env, "GOOGLE_API_KEY");
+      const aiSdk = envKey(env, "GOOGLE_GENERATIVE_AI_API_KEY");
+      key = gemini ?? google ?? aiSdk;
+      envName = gemini ? "GEMINI_API_KEY" : google ? "GOOGLE_API_KEY" : aiSdk ? "GOOGLE_GENERATIVE_AI_API_KEY" : "GEMINI_API_KEY";
+    } else {
+      key = envKey(env, spec.canonicalEnvName);
+    }
+    if (!key) {
+      return {
+        provider: spec.provider,
+        env: envName,
+        present: false,
+        valid: null,
+        detail: "key_absent"
+      };
+    }
+    const base = {
+      provider: spec.provider,
+      env: envName,
+      present: true,
+      valid: null
+    };
+    const { url, headers } = spec.buildRequest(key);
+    const started = Date.now();
+    let res;
+    try {
+      res = await fetchFn(url, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (err) {
+      const isTimeout = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+      return {
+        ...base,
+        latency_ms: Date.now() - started,
+        // NEVER echo err.message — provider errors could theoretically carry
+        // request context; a fixed vocabulary keeps key material impossible.
+        detail: isTimeout ? "timeout" : "network_error"
+      };
+    }
+    const latencyMs = Date.now() - started;
+    if (res.ok) {
+      const result = {
+        ...base,
+        valid: true,
+        status: res.status,
+        latency_ms: latencyMs
+      };
+      if (spec.parseBalanceUsd) {
+        try {
+          const body = await res.json();
+          const balance = spec.parseBalanceUsd(body);
+          if (balance !== void 0) result.balance_usd = balance;
+        } catch {
+        }
+      }
+      return result;
+    }
+    if (res.status === 401 || res.status === 403) {
+      return { ...base, valid: false, status: res.status, latency_ms: latencyMs };
+    }
+    return {
+      ...base,
+      valid: null,
+      status: res.status,
+      latency_ms: latencyMs,
+      detail: `http_${res.status}`
+    };
+  }
+  async function handle(req) {
+    try {
+      if (req.method !== "GET") {
+        return jsonResponse(405, { error: "method_not_allowed" });
+      }
+      if (bearerOf(req) !== ingestSecret) {
+        return jsonResponse(401, { error: "unauthorized" });
+      }
+      const env = config.env ?? process.env;
+      const settled = await Promise.allSettled(
+        PROBE_SPECS.map((spec) => probeProvider(spec, env))
+      );
+      const keys = settled.map((s, i) => {
+        if (s.status === "fulfilled") return s.value;
+        const spec = PROBE_SPECS[i];
+        return {
+          provider: spec.provider,
+          env: spec.canonicalEnvName,
+          present: true,
+          valid: null,
+          detail: "probe_failed"
+        };
+      });
+      keys.sort((a, b) => a.provider.localeCompare(b.provider));
+      const body = {
+        app_id: appId,
+        checked_at: (/* @__PURE__ */ new Date()).toISOString(),
+        keys
+      };
+      return jsonResponse(200, body);
+    } catch (err) {
+      void err;
+      return jsonResponse(500, { error: "key_health_internal_error" });
+    }
+  }
+  return { handle };
+}
+
+export {
+  createKeyHealthRoute
+};

package/dist/index.d.mts

@@ -3,6 +3,7 @@ export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithG
 import { ModelProfile, ArchetypeConvention } from './profiles.mjs';
 export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.mjs';
 export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.mjs';
+export { KeyHealthConfig, KeyHealthProvider, KeyHealthResponseBody, KeyHealthResult, KeyHealthRoute, createKeyHealthRoute } from './key-health.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.mjs';
 
@@ -414,6 +415,28 @@ interface BrainConfig {
      * arms the tracking, so good actors never see a false warning.
      */
     warnOnDiscardedCompile?: boolean;
+    /**
+     * alpha.59 — per-leg timeout (ms) applied to every brain WRITE POST
+     * (record() primary + advisory secondary, recordOutcome(),
+     * recordShadowProbe()) via `AbortSignal.timeout`. Default 10000.
+     *
+     * Why: `sync: true` puts these fetches on the USER path (Edge consumers
+     * await record() before responding), and alpha.56's representation
+     * passthrough added a second sequential POST (advisory secondary) to that
+     * same path — an unbounded hang on either leg holds the user to the Edge
+     * limit (GE's `brainconfig-first-class-timeout` filing; GE bounded it at
+     * 3s via a hand-rolled fetchImpl wrapper every sync consumer had to
+     * rediscover).
+     *
+     * A fired timeout follows each leg's existing degraded-brain path
+     * (fire-and-forget: swallowed via onError; sync: `persistence_failed`
+     * result — never a throw into the user path). Wraps the configured
+     * `fetchImpl` rather than replacing it, so it composes with
+     * consumer-supplied impls. Set `0` to disable (pre-alpha.59 unbounded
+     * behavior). Brain-query reads (config tables) are cached + SWR and are
+     * not affected.
+     */
+    timeoutMs?: number;
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithG
 import { ModelProfile, ArchetypeConvention } from './profiles.js';
 export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.js';
 export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.js';
+export { KeyHealthConfig, KeyHealthProvider, KeyHealthResponseBody, KeyHealthResult, KeyHealthRoute, createKeyHealthRoute } from './key-health.js';
 import { IntentArchetypeName } from './dialect.js';
 export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.js';
 
@@ -414,6 +415,28 @@ interface BrainConfig {
      * arms the tracking, so good actors never see a false warning.
      */
     warnOnDiscardedCompile?: boolean;
+    /**
+     * alpha.59 — per-leg timeout (ms) applied to every brain WRITE POST
+     * (record() primary + advisory secondary, recordOutcome(),
+     * recordShadowProbe()) via `AbortSignal.timeout`. Default 10000.
+     *
+     * Why: `sync: true` puts these fetches on the USER path (Edge consumers
+     * await record() before responding), and alpha.56's representation
+     * passthrough added a second sequential POST (advisory secondary) to that
+     * same path — an unbounded hang on either leg holds the user to the Edge
+     * limit (GE's `brainconfig-first-class-timeout` filing; GE bounded it at
+     * 3s via a hand-rolled fetchImpl wrapper every sync consumer had to
+     * rediscover).
+     *
+     * A fired timeout follows each leg's existing degraded-brain path
+     * (fire-and-forget: swallowed via onError; sync: `persistence_failed`
+     * result — never a throw into the user path). Wraps the configured
+     * `fetchImpl` rather than replacing it, so it composes with
+     * consumer-supplied impls. Set `0` to disable (pre-alpha.59 unbounded
+     * behavior). Brain-query reads (config tables) are cached + SWR and are
+     * not affected.
+     */
+    timeoutMs?: number;
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;

package/dist/index.js

@@ -52,6 +52,7 @@ __export(index_exports, {
   configureBrain: () => configureBrain,
   countTokens: () => countTokens,
   createBrainForwardRoutes: () => createBrainForwardRoutes,
+  createKeyHealthRoute: () => createKeyHealthRoute,
   deriveFamilyFromModelId: () => deriveFamilyFromModelId,
   deriveOwnership: () => deriveOwnership,
   execute: () => execute,
@@ -4416,6 +4417,15 @@ function resolvePricingAt(modelId, at = /* @__PURE__ */ new Date()) {
 }
 
 // src/brain.ts
+var DEFAULT_BRAIN_WRITE_TIMEOUT_MS = 1e4;
+function brainWriteFetch(config) {
+  const base = config.fetchImpl ?? fetch;
+  const timeoutMs = config.timeoutMs ?? DEFAULT_BRAIN_WRITE_TIMEOUT_MS;
+  if (timeoutMs <= 0 || typeof AbortSignal === "undefined" || typeof AbortSignal.timeout !== "function") {
+    return base;
+  }
+  return (input, init) => base(input, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+}
 var activeConfig;
 function configureBrain(config) {
   const endpoint = config.endpoint.replace(/\/outcomes\/?$/, "");
@@ -4561,7 +4571,7 @@ async function record(input) {
   }
   const payload = buildPayload(input, reg);
   const config = activeConfig;
-  const fetchFn = config.fetchImpl ?? fetch;
+  const fetchFn = brainWriteFetch(config);
   const send = async () => {
     let outcomeId;
     try {
@@ -4730,9 +4740,9 @@ function buildAdvisoryRow(outcomeId, a) {
     code: a.code,
     level: a.level,
     message: a.message,
-    ...a.recommendationType ? { recommendation_type: a.recommendationType } : {},
-    ...a.suggestion ? { suggestion: a.suggestion } : {},
-    ...a.docsUrl ? { docs_url: a.docsUrl } : {}
+    recommendation_type: a.recommendationType ?? null,
+    suggestion: a.suggestion ?? null,
+    docs_url: a.docsUrl ?? null
   };
 }
 async function recordOutcome(input) {
@@ -4740,7 +4750,7 @@ async function recordOutcome(input) {
     return { ok: false, reason: "brain_not_configured" };
   }
   const config = activeConfig;
-  const fetchFn = config.fetchImpl ?? fetch;
+  const fetchFn = brainWriteFetch(config);
   const payload = {
     outcome_id: input.outcomeId,
     outcome: input.outcome,
@@ -4815,7 +4825,7 @@ function buildShadowProbeRow(input) {
 async function recordShadowProbe(input) {
   if (!activeConfig) return;
   const config = activeConfig;
-  const fetchFn = config.fetchImpl ?? fetch;
+  const fetchFn = brainWriteFetch(config);
   const row = buildShadowProbeRow(input);
   const send = async () => {
     try {
@@ -6935,6 +6945,188 @@ function createBrainForwardRoutes(config) {
   return { handle, segments: KNOWN_SEGMENTS };
 }
 
+// src/key-health.ts
+var JSON_HEADERS2 = { "Content-Type": "application/json" };
+function jsonResponse2(status, body) {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS2 });
+}
+function bearerOf2(req) {
+  const header = req.headers.get("Authorization") ?? "";
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  return match?.[1]?.trim() ?? "";
+}
+function requireString2(name, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`createKeyHealthRoute: ${name} is required`);
+  }
+  return value;
+}
+function envKey(env, name) {
+  const v = env[name];
+  if (typeof v !== "string") return void 0;
+  const trimmed = v.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+var PROBE_SPECS = [
+  {
+    provider: "anthropic",
+    canonicalEnvName: "ANTHROPIC_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.anthropic.com/v1/models?limit=1",
+      headers: { "x-api-key": key, "anthropic-version": "2023-06-01" }
+    })
+  },
+  {
+    provider: "deepseek",
+    canonicalEnvName: "DEEPSEEK_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.deepseek.com/user/balance",
+      headers: { Authorization: `Bearer ${key}` }
+    }),
+    parseBalanceUsd: (body) => {
+      const infos = body?.balance_infos;
+      if (!Array.isArray(infos) || infos.length === 0) return void 0;
+      const first = infos[0];
+      if (first?.currency !== "USD") return void 0;
+      const n = Number(first.total_balance);
+      return Number.isFinite(n) ? n : void 0;
+    }
+  },
+  {
+    provider: "google",
+    canonicalEnvName: "GEMINI_API_KEY",
+    buildRequest: (key) => ({
+      url: `https://generativelanguage.googleapis.com/v1beta/models?pageSize=1&key=${encodeURIComponent(key)}`,
+      headers: {}
+    })
+  },
+  {
+    provider: "openai",
+    canonicalEnvName: "OPENAI_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.openai.com/v1/models",
+      headers: { Authorization: `Bearer ${key}` }
+    })
+  }
+];
+function createKeyHealthRoute(config) {
+  const appId = requireString2("appId", config.appId);
+  const ingestSecret = requireString2("ingestSecret", config.ingestSecret);
+  const fetchFn = config.fetchImpl ?? fetch;
+  const timeoutMs = config.timeoutMs ?? 3e3;
+  async function probeProvider(spec, env) {
+    let key;
+    let envName = spec.canonicalEnvName;
+    if (spec.provider === "google") {
+      const gemini = envKey(env, "GEMINI_API_KEY");
+      const google = envKey(env, "GOOGLE_API_KEY");
+      const aiSdk = envKey(env, "GOOGLE_GENERATIVE_AI_API_KEY");
+      key = gemini ?? google ?? aiSdk;
+      envName = gemini ? "GEMINI_API_KEY" : google ? "GOOGLE_API_KEY" : aiSdk ? "GOOGLE_GENERATIVE_AI_API_KEY" : "GEMINI_API_KEY";
+    } else {
+      key = envKey(env, spec.canonicalEnvName);
+    }
+    if (!key) {
+      return {
+        provider: spec.provider,
+        env: envName,
+        present: false,
+        valid: null,
+        detail: "key_absent"
+      };
+    }
+    const base = {
+      provider: spec.provider,
+      env: envName,
+      present: true,
+      valid: null
+    };
+    const { url, headers } = spec.buildRequest(key);
+    const started = Date.now();
+    let res;
+    try {
+      res = await fetchFn(url, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (err) {
+      const isTimeout = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+      return {
+        ...base,
+        latency_ms: Date.now() - started,
+        // NEVER echo err.message — provider errors could theoretically carry
+        // request context; a fixed vocabulary keeps key material impossible.
+        detail: isTimeout ? "timeout" : "network_error"
+      };
+    }
+    const latencyMs = Date.now() - started;
+    if (res.ok) {
+      const result = {
+        ...base,
+        valid: true,
+        status: res.status,
+        latency_ms: latencyMs
+      };
+      if (spec.parseBalanceUsd) {
+        try {
+          const body = await res.json();
+          const balance = spec.parseBalanceUsd(body);
+          if (balance !== void 0) result.balance_usd = balance;
+        } catch {
+        }
+      }
+      return result;
+    }
+    if (res.status === 401 || res.status === 403) {
+      return { ...base, valid: false, status: res.status, latency_ms: latencyMs };
+    }
+    return {
+      ...base,
+      valid: null,
+      status: res.status,
+      latency_ms: latencyMs,
+      detail: `http_${res.status}`
+    };
+  }
+  async function handle(req) {
+    try {
+      if (req.method !== "GET") {
+        return jsonResponse2(405, { error: "method_not_allowed" });
+      }
+      if (bearerOf2(req) !== ingestSecret) {
+        return jsonResponse2(401, { error: "unauthorized" });
+      }
+      const env = config.env ?? process.env;
+      const settled = await Promise.allSettled(
+        PROBE_SPECS.map((spec) => probeProvider(spec, env))
+      );
+      const keys = settled.map((s, i) => {
+        if (s.status === "fulfilled") return s.value;
+        const spec = PROBE_SPECS[i];
+        return {
+          provider: spec.provider,
+          env: spec.canonicalEnvName,
+          present: true,
+          valid: null,
+          detail: "probe_failed"
+        };
+      });
+      keys.sort((a, b) => a.provider.localeCompare(b.provider));
+      const body = {
+        app_id: appId,
+        checked_at: (/* @__PURE__ */ new Date()).toISOString(),
+        keys
+      };
+      return jsonResponse2(200, body);
+    } catch (err) {
+      void err;
+      return jsonResponse2(500, { error: "key_health_internal_error" });
+    }
+  }
+  return { handle };
+}
+
 // src/oracle.ts
 var DEFAULT_DIMENSIONS = ["correctness", "completeness", "conciseness", "format"];
 var judgeCallTimes = [];
@@ -7395,6 +7587,7 @@ function compile2(ir, opts) {
   configureBrain,
   countTokens,
   createBrainForwardRoutes,
+  createKeyHealthRoute,
   deriveFamilyFromModelId,
   deriveOwnership,
   execute,

package/dist/index.mjs

@@ -12,6 +12,9 @@ import {
   isArchetype,
   learningKey
 } from "./chunk-5TI6PNSK.mjs";
+import {
+  createKeyHealthRoute
+} from "./chunk-B4INZ32V.mjs";
 import {
   ABSOLUTE_FLOOR,
   ARCHETYPE_FLOOR_DEFAULT,
@@ -2572,6 +2575,15 @@ function resolvePricingAt(modelId, at = /* @__PURE__ */ new Date()) {
 }
 
 // src/brain.ts
+var DEFAULT_BRAIN_WRITE_TIMEOUT_MS = 1e4;
+function brainWriteFetch(config) {
+  const base = config.fetchImpl ?? fetch;
+  const timeoutMs = config.timeoutMs ?? DEFAULT_BRAIN_WRITE_TIMEOUT_MS;
+  if (timeoutMs <= 0 || typeof AbortSignal === "undefined" || typeof AbortSignal.timeout !== "function") {
+    return base;
+  }
+  return (input, init) => base(input, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+}
 var activeConfig;
 function configureBrain(config) {
   const endpoint = config.endpoint.replace(/\/outcomes\/?$/, "");
@@ -2717,7 +2729,7 @@ async function record(input) {
   }
   const payload = buildPayload(input, reg);
   const config = activeConfig;
-  const fetchFn = config.fetchImpl ?? fetch;
+  const fetchFn = brainWriteFetch(config);
   const send = async () => {
     let outcomeId;
     try {
@@ -2886,9 +2898,9 @@ function buildAdvisoryRow(outcomeId, a) {
     code: a.code,
     level: a.level,
     message: a.message,
-    ...a.recommendationType ? { recommendation_type: a.recommendationType } : {},
-    ...a.suggestion ? { suggestion: a.suggestion } : {},
-    ...a.docsUrl ? { docs_url: a.docsUrl } : {}
+    recommendation_type: a.recommendationType ?? null,
+    suggestion: a.suggestion ?? null,
+    docs_url: a.docsUrl ?? null
   };
 }
 async function recordOutcome(input) {
@@ -2896,7 +2908,7 @@ async function recordOutcome(input) {
     return { ok: false, reason: "brain_not_configured" };
   }
   const config = activeConfig;
-  const fetchFn = config.fetchImpl ?? fetch;
+  const fetchFn = brainWriteFetch(config);
   const payload = {
     outcome_id: input.outcomeId,
     outcome: input.outcome,
@@ -2971,7 +2983,7 @@ function buildShadowProbeRow(input) {
 async function recordShadowProbe(input) {
   if (!activeConfig) return;
   const config = activeConfig;
-  const fetchFn = config.fetchImpl ?? fetch;
+  const fetchFn = brainWriteFetch(config);
   const row = buildShadowProbeRow(input);
   const send = async () => {
     try {
@@ -4673,6 +4685,7 @@ export {
   configureBrain,
   countTokens,
   createBrainForwardRoutes,
+  createKeyHealthRoute,
   deriveFamilyFromModelId,
   deriveOwnership,
   execute,

package/dist/key-health.d.mts

@@ -0,0 +1,121 @@
+/**
+ * `@warmdrift/kgauto-compiler/key-health` — per-consumer provider-key health
+ * endpoint factory (alpha.58, KG-fleet-v1 phase 1).
+ *
+ * ## Why this exists
+ *
+ * Consumers (playbacksam, inspire-central, tt-intelligence, global-expansion)
+ * hold their own provider API keys in their own Vercel envs — the library
+ * never sees keys centrally, by design. That means the operator dashboard has
+ * no way to answer "is PB's DeepSeek key still valid?" without a per-consumer
+ * probe surface. This factory is that surface: the consumer mounts ONE route,
+ * the dashboard polls it with the consumer's existing `KGAUTO_INGEST_SECRET`
+ * bearer, and gets back a validity grid for every canonical provider key.
+ *
+ * Probes are the cheapest authenticated GETs each provider offers (model
+ * listings; DeepSeek's balance endpoint) — never a completion call, zero
+ * token cost. Keys themselves NEVER appear in any response: only presence,
+ * validity, HTTP status, latency, and (DeepSeek only) account balance.
+ *
+ * Same design contract as `createBrainForwardRoutes` (brain-proxy.ts):
+ * web-standard Request→Response, never throws (every path returns a
+ * `Response`), bearer gate, runs on Edge/Workers/Node.
+ *
+ * ## Mounting recipes
+ *
+ * ### (a) Next.js app-router route handler — ONE file
+ *
+ *   // app/api/kgauto/v2/keyhealth/route.ts
+ *   import { createKeyHealthRoute } from '@warmdrift/kgauto-compiler/key-health';
+ *   const routes = createKeyHealthRoute({
+ *     appId: 'playbacksam',
+ *     ingestSecret: process.env.KGAUTO_INGEST_SECRET!,
+ *   });
+ *   export const GET = (req: Request) => routes.handle(req);
+ *
+ *   // middleware.ts — if the app gates routes behind auth middleware, the
+ *   // existing brain-proxy public-path prefix ('/api/kgauto/v2/') already
+ *   // covers this route. If the allowlist is per-path, add
+ *   // '/api/kgauto/v2/keyhealth' or server-to-server GETs 307 to /login
+ *   // (the tt-intel middleware-drift shape — see brain-proxy.ts).
+ *
+ * ### (b) Plain per-file Vercel function
+ *
+ *   // api/kgauto/keyhealth.ts
+ *   export const config = { runtime: 'edge' };
+ *   import { createKeyHealthRoute } from '@warmdrift/kgauto-compiler/key-health';
+ *   const routes = createKeyHealthRoute({
+ *     appId: 'inspire-central',
+ *     ingestSecret: process.env.KGAUTO_INGEST_SECRET!,
+ *   });
+ *   export default (req: Request) => routes.handle(req);
+ *
+ * ## Wire shape (LOCKED CONTRACT with the operator dashboard — do not rename)
+ *
+ *   200 {
+ *     app_id: string,
+ *     checked_at: string,          // ISO timestamp
+ *     keys: [                      // sorted by provider name
+ *       {
+ *         provider: 'anthropic' | 'deepseek' | 'google' | 'openai',
+ *         env: string,             // canonical env var name probed
+ *         present: boolean,        // key present (non-empty after trim)
+ *         valid: boolean | null,   // true 2xx / false 401·403 / null unknown
+ *         status?: number,         // probe HTTP status when a response landed
+ *         latency_ms?: number,     // probe round-trip
+ *         balance_usd?: number,    // DeepSeek only, when currency is USD
+ *         detail?: string,         // e.g. 'timeout', 'http_500', 'key_absent'
+ *       }
+ *     ]
+ *   }
+ */
+type KeyHealthProvider = 'anthropic' | 'deepseek' | 'google' | 'openai';
+interface KeyHealthConfig {
+    /** Consumer app id echoed as `app_id` in the response (e.g. 'playbacksam'). */
+    appId: string;
+    /** Bearer token the poller must present (consumer's existing KGAUTO_INGEST_SECRET). */
+    ingestSecret: string;
+    /** Optional fetch impl for tests. */
+    fetchImpl?: typeof fetch;
+    /** Env source; defaults to process.env. Test injection point. */
+    env?: Record<string, string | undefined>;
+    /** Per-provider probe timeout in ms. Default 3000. */
+    timeoutMs?: number;
+}
+interface KeyHealthResult {
+    provider: KeyHealthProvider;
+    /** Canonical env var name probed (the resolved one for Google). */
+    env: string;
+    /** Key present (non-empty after trim) in env. */
+    present: boolean;
+    /** true = provider accepted the key (2xx); false = rejected (401/403); null = unknown (absent / timeout / 5xx / 429 / network). */
+    valid: boolean | null;
+    /** HTTP status of the probe, when a response landed. */
+    status?: number;
+    /** Probe round-trip in ms, when a probe ran. */
+    latency_ms?: number;
+    /** DeepSeek only: account balance in USD when the balance API reports USD. */
+    balance_usd?: number;
+    /** Failure class when valid is null with a probe attempted (e.g. 'timeout', 'http_500') or 'key_absent'. */
+    detail?: string;
+}
+interface KeyHealthResponseBody {
+    app_id: string;
+    checked_at: string;
+    keys: KeyHealthResult[];
+}
+interface KeyHealthRoute {
+    /**
+     * Web-standard handler. GET only. Never throws — every error path returns
+     * a `Response`.
+     */
+    handle(req: Request): Promise<Response>;
+}
+/**
+ * Create the per-consumer key-health route. See module docstring for the
+ * mounting recipes ((a) Next.js route handler, (b) per-file Vercel function)
+ * and the locked wire shape.
+ */
+declare function createKeyHealthRoute(config: KeyHealthConfig): KeyHealthRoute;
+
+export { type KeyHealthConfig, type KeyHealthProvider, type KeyHealthResponseBody, type KeyHealthResult, type KeyHealthRoute, createKeyHealthRoute };

package/dist/key-health.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `@warmdrift/kgauto-compiler/key-health` — per-consumer provider-key health
+ * endpoint factory (alpha.58, KG-fleet-v1 phase 1).
+ *
+ * ## Why this exists
+ *
+ * Consumers (playbacksam, inspire-central, tt-intelligence, global-expansion)
+ * hold their own provider API keys in their own Vercel envs — the library
+ * never sees keys centrally, by design. That means the operator dashboard has
+ * no way to answer "is PB's DeepSeek key still valid?" without a per-consumer
+ * probe surface. This factory is that surface: the consumer mounts ONE route,
+ * the dashboard polls it with the consumer's existing `KGAUTO_INGEST_SECRET`
+ * bearer, and gets back a validity grid for every canonical provider key.
+ *
+ * Probes are the cheapest authenticated GETs each provider offers (model
+ * listings; DeepSeek's balance endpoint) — never a completion call, zero
+ * token cost. Keys themselves NEVER appear in any response: only presence,
+ * validity, HTTP status, latency, and (DeepSeek only) account balance.
+ *
+ * Same design contract as `createBrainForwardRoutes` (brain-proxy.ts):
+ * web-standard Request→Response, never throws (every path returns a
+ * `Response`), bearer gate, runs on Edge/Workers/Node.
+ *
+ * ## Mounting recipes
+ *
+ * ### (a) Next.js app-router route handler — ONE file
+ *
+ *   // app/api/kgauto/v2/keyhealth/route.ts
+ *   import { createKeyHealthRoute } from '@warmdrift/kgauto-compiler/key-health';
+ *   const routes = createKeyHealthRoute({
+ *     appId: 'playbacksam',
+ *     ingestSecret: process.env.KGAUTO_INGEST_SECRET!,
+ *   });
+ *   export const GET = (req: Request) => routes.handle(req);
+ *
+ *   // middleware.ts — if the app gates routes behind auth middleware, the
+ *   // existing brain-proxy public-path prefix ('/api/kgauto/v2/') already
+ *   // covers this route. If the allowlist is per-path, add
+ *   // '/api/kgauto/v2/keyhealth' or server-to-server GETs 307 to /login
+ *   // (the tt-intel middleware-drift shape — see brain-proxy.ts).
+ *
+ * ### (b) Plain per-file Vercel function
+ *
+ *   // api/kgauto/keyhealth.ts
+ *   export const config = { runtime: 'edge' };
+ *   import { createKeyHealthRoute } from '@warmdrift/kgauto-compiler/key-health';
+ *   const routes = createKeyHealthRoute({
+ *     appId: 'inspire-central',
+ *     ingestSecret: process.env.KGAUTO_INGEST_SECRET!,
+ *   });
+ *   export default (req: Request) => routes.handle(req);
+ *
+ * ## Wire shape (LOCKED CONTRACT with the operator dashboard — do not rename)
+ *
+ *   200 {
+ *     app_id: string,
+ *     checked_at: string,          // ISO timestamp
+ *     keys: [                      // sorted by provider name
+ *       {
+ *         provider: 'anthropic' | 'deepseek' | 'google' | 'openai',
+ *         env: string,             // canonical env var name probed
+ *         present: boolean,        // key present (non-empty after trim)
+ *         valid: boolean | null,   // true 2xx / false 401·403 / null unknown
+ *         status?: number,         // probe HTTP status when a response landed
+ *         latency_ms?: number,     // probe round-trip
+ *         balance_usd?: number,    // DeepSeek only, when currency is USD
+ *         detail?: string,         // e.g. 'timeout', 'http_500', 'key_absent'
+ *       }
+ *     ]
+ *   }
+ */
+type KeyHealthProvider = 'anthropic' | 'deepseek' | 'google' | 'openai';
+interface KeyHealthConfig {
+    /** Consumer app id echoed as `app_id` in the response (e.g. 'playbacksam'). */
+    appId: string;
+    /** Bearer token the poller must present (consumer's existing KGAUTO_INGEST_SECRET). */
+    ingestSecret: string;
+    /** Optional fetch impl for tests. */
+    fetchImpl?: typeof fetch;
+    /** Env source; defaults to process.env. Test injection point. */
+    env?: Record<string, string | undefined>;
+    /** Per-provider probe timeout in ms. Default 3000. */
+    timeoutMs?: number;
+}
+interface KeyHealthResult {
+    provider: KeyHealthProvider;
+    /** Canonical env var name probed (the resolved one for Google). */
+    env: string;
+    /** Key present (non-empty after trim) in env. */
+    present: boolean;
+    /** true = provider accepted the key (2xx); false = rejected (401/403); null = unknown (absent / timeout / 5xx / 429 / network). */
+    valid: boolean | null;
+    /** HTTP status of the probe, when a response landed. */
+    status?: number;
+    /** Probe round-trip in ms, when a probe ran. */
+    latency_ms?: number;
+    /** DeepSeek only: account balance in USD when the balance API reports USD. */
+    balance_usd?: number;
+    /** Failure class when valid is null with a probe attempted (e.g. 'timeout', 'http_500') or 'key_absent'. */
+    detail?: string;
+}
+interface KeyHealthResponseBody {
+    app_id: string;
+    checked_at: string;
+    keys: KeyHealthResult[];
+}
+interface KeyHealthRoute {
+    /**
+     * Web-standard handler. GET only. Never throws — every error path returns
+     * a `Response`.
+     */
+    handle(req: Request): Promise<Response>;
+}
+/**
+ * Create the per-consumer key-health route. See module docstring for the
+ * mounting recipes ((a) Next.js route handler, (b) per-file Vercel function)
+ * and the locked wire shape.
+ */
+declare function createKeyHealthRoute(config: KeyHealthConfig): KeyHealthRoute;
+
+export { type KeyHealthConfig, type KeyHealthProvider, type KeyHealthResponseBody, type KeyHealthResult, type KeyHealthRoute, createKeyHealthRoute };

package/dist/key-health.js

@@ -0,0 +1,209 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/key-health.ts
+var key_health_exports = {};
+__export(key_health_exports, {
+  createKeyHealthRoute: () => createKeyHealthRoute
+});
+module.exports = __toCommonJS(key_health_exports);
+var JSON_HEADERS = { "Content-Type": "application/json" };
+function jsonResponse(status, body) {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+function bearerOf(req) {
+  const header = req.headers.get("Authorization") ?? "";
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  return match?.[1]?.trim() ?? "";
+}
+function requireString(name, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`createKeyHealthRoute: ${name} is required`);
+  }
+  return value;
+}
+function envKey(env, name) {
+  const v = env[name];
+  if (typeof v !== "string") return void 0;
+  const trimmed = v.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+var PROBE_SPECS = [
+  {
+    provider: "anthropic",
+    canonicalEnvName: "ANTHROPIC_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.anthropic.com/v1/models?limit=1",
+      headers: { "x-api-key": key, "anthropic-version": "2023-06-01" }
+    })
+  },
+  {
+    provider: "deepseek",
+    canonicalEnvName: "DEEPSEEK_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.deepseek.com/user/balance",
+      headers: { Authorization: `Bearer ${key}` }
+    }),
+    parseBalanceUsd: (body) => {
+      const infos = body?.balance_infos;
+      if (!Array.isArray(infos) || infos.length === 0) return void 0;
+      const first = infos[0];
+      if (first?.currency !== "USD") return void 0;
+      const n = Number(first.total_balance);
+      return Number.isFinite(n) ? n : void 0;
+    }
+  },
+  {
+    provider: "google",
+    canonicalEnvName: "GEMINI_API_KEY",
+    buildRequest: (key) => ({
+      url: `https://generativelanguage.googleapis.com/v1beta/models?pageSize=1&key=${encodeURIComponent(key)}`,
+      headers: {}
+    })
+  },
+  {
+    provider: "openai",
+    canonicalEnvName: "OPENAI_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.openai.com/v1/models",
+      headers: { Authorization: `Bearer ${key}` }
+    })
+  }
+];
+function createKeyHealthRoute(config) {
+  const appId = requireString("appId", config.appId);
+  const ingestSecret = requireString("ingestSecret", config.ingestSecret);
+  const fetchFn = config.fetchImpl ?? fetch;
+  const timeoutMs = config.timeoutMs ?? 3e3;
+  async function probeProvider(spec, env) {
+    let key;
+    let envName = spec.canonicalEnvName;
+    if (spec.provider === "google") {
+      const gemini = envKey(env, "GEMINI_API_KEY");
+      const google = envKey(env, "GOOGLE_API_KEY");
+      const aiSdk = envKey(env, "GOOGLE_GENERATIVE_AI_API_KEY");
+      key = gemini ?? google ?? aiSdk;
+      envName = gemini ? "GEMINI_API_KEY" : google ? "GOOGLE_API_KEY" : aiSdk ? "GOOGLE_GENERATIVE_AI_API_KEY" : "GEMINI_API_KEY";
+    } else {
+      key = envKey(env, spec.canonicalEnvName);
+    }
+    if (!key) {
+      return {
+        provider: spec.provider,
+        env: envName,
+        present: false,
+        valid: null,
+        detail: "key_absent"
+      };
+    }
+    const base = {
+      provider: spec.provider,
+      env: envName,
+      present: true,
+      valid: null
+    };
+    const { url, headers } = spec.buildRequest(key);
+    const started = Date.now();
+    let res;
+    try {
+      res = await fetchFn(url, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (err) {
+      const isTimeout = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+      return {
+        ...base,
+        latency_ms: Date.now() - started,
+        // NEVER echo err.message — provider errors could theoretically carry
+        // request context; a fixed vocabulary keeps key material impossible.
+        detail: isTimeout ? "timeout" : "network_error"
+      };
+    }
+    const latencyMs = Date.now() - started;
+    if (res.ok) {
+      const result = {
+        ...base,
+        valid: true,
+        status: res.status,
+        latency_ms: latencyMs
+      };
+      if (spec.parseBalanceUsd) {
+        try {
+          const body = await res.json();
+          const balance = spec.parseBalanceUsd(body);
+          if (balance !== void 0) result.balance_usd = balance;
+        } catch {
+        }
+      }
+      return result;
+    }
+    if (res.status === 401 || res.status === 403) {
+      return { ...base, valid: false, status: res.status, latency_ms: latencyMs };
+    }
+    return {
+      ...base,
+      valid: null,
+      status: res.status,
+      latency_ms: latencyMs,
+      detail: `http_${res.status}`
+    };
+  }
+  async function handle(req) {
+    try {
+      if (req.method !== "GET") {
+        return jsonResponse(405, { error: "method_not_allowed" });
+      }
+      if (bearerOf(req) !== ingestSecret) {
+        return jsonResponse(401, { error: "unauthorized" });
+      }
+      const env = config.env ?? process.env;
+      const settled = await Promise.allSettled(
+        PROBE_SPECS.map((spec) => probeProvider(spec, env))
+      );
+      const keys = settled.map((s, i) => {
+        if (s.status === "fulfilled") return s.value;
+        const spec = PROBE_SPECS[i];
+        return {
+          provider: spec.provider,
+          env: spec.canonicalEnvName,
+          present: true,
+          valid: null,
+          detail: "probe_failed"
+        };
+      });
+      keys.sort((a, b) => a.provider.localeCompare(b.provider));
+      const body = {
+        app_id: appId,
+        checked_at: (/* @__PURE__ */ new Date()).toISOString(),
+        keys
+      };
+      return jsonResponse(200, body);
+    } catch (err) {
+      void err;
+      return jsonResponse(500, { error: "key_health_internal_error" });
+    }
+  }
+  return { handle };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createKeyHealthRoute
+});

package/dist/key-health.mjs

@@ -0,0 +1,6 @@
+import {
+  createKeyHealthRoute
+} from "./chunk-B4INZ32V.mjs";
+export {
+  createKeyHealthRoute
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.57",
+  "version": "2.0.0-alpha.59",
   "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -26,6 +26,11 @@
       "import": "./dist/brain-proxy.mjs",
       "require": "./dist/brain-proxy.js"
     },
+    "./key-health": {
+      "types": "./dist/key-health.d.ts",
+      "import": "./dist/key-health.mjs",
+      "require": "./dist/key-health.js"
+    },
     "./glassbox": {
       "types": "./dist/glassbox/index.d.ts",
       "import": "./dist/glassbox/index.mjs",
@@ -52,7 +57,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/dialect.ts src/profiles.ts src/brain-proxy.ts src/glassbox/index.ts src/glassbox-routes/index.ts src/glassbox-routes/format.ts src/glassbox-routes/react/index.ts --format cjs,esm --dts --clean --external react --external react-dom",
+    "build": "tsup src/index.ts src/dialect.ts src/profiles.ts src/brain-proxy.ts src/key-health.ts src/glassbox/index.ts src/glassbox-routes/index.ts src/glassbox-routes/format.ts src/glassbox-routes/react/index.ts --format cjs,esm --dts --clean --external react --external react-dom",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",