@warmdrift/kgauto-compiler 2.0.0-alpha.7 → 2.0.0-alpha.71

package/dist/chunk-URFQR3SB.mjs

@@ -0,0 +1,203 @@
+// src/version.ts
+var LIBRARY_VERSION = "2.0.0-alpha.71";
+
+// 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: "moonshot",
+    canonicalEnvName: "MOONSHOT_API_KEY",
+    buildRequest: (key) => ({
+      url: "https://api.moonshot.ai/v1/models",
+      headers: { Authorization: `Bearer ${key}` }
+    })
+  },
+  {
+    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 if (spec.provider === "moonshot") {
+      const moonshot = envKey(env, "MOONSHOT_API_KEY");
+      const kimi = envKey(env, "KIMI_API_KEY");
+      key = moonshot ?? kimi;
+      envName = moonshot ? "MOONSHOT_API_KEY" : kimi ? "KIMI_API_KEY" : "MOONSHOT_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(),
+        library_version: LIBRARY_VERSION,
+        keys
+      };
+      return jsonResponse(200, body);
+    } catch (err) {
+      void err;
+      return jsonResponse(500, { error: "key_health_internal_error" });
+    }
+  }
+  return { handle };
+}
+
+export {
+  LIBRARY_VERSION,
+  createKeyHealthRoute
+};

package/dist/dialect.d.mts

@@ -12,8 +12,15 @@
  * The brain learns by `(archetype, model, shape)` tuples. Apps that declare
  * the same tuple inherit each other's mutations.
  *
- * v1 is intentionally small (9 archetypes, 5 shape dimensions). New entries
- * arrive in v2/v3 from real usage signals — never speculatively.
+ * v1 is intentionally small (10 archetypes, 5 shape dimensions). New entries
+ * arrive from real usage signals — never speculatively.
+ *
+ * Versioning note (alpha.62): `judge` was added as an ADDITIVE 10th entry
+ * under dialect-v1 rather than bumping to v2. Bumping the version string
+ * would fragment every existing learning key (`v1::…` → `v2::…`) for a
+ * purely additive vocabulary change; existing keys are untouched and judge
+ * keys are new, so no collision is possible. A v2 bump is reserved for
+ * changes that alter the MEANING of existing entries or the shape hash.
  */
 declare const DIALECT_VERSION: "v1";
 declare const INTENT_ARCHETYPES: {
@@ -62,6 +69,11 @@ declare const INTENT_ARCHETYPES: {
         readonly description: "Change format or style while preserving content";
         readonly examples: ["markdown → html", "formal → casual", "translate"];
     };
+    readonly judge: {
+        readonly name: "judge";
+        readonly description: "Pairwise comparison of two candidate outputs for the same input";
+        readonly examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"];
+    };
 };
 type IntentArchetypeName = keyof typeof INTENT_ARCHETYPES;
 declare const ALL_ARCHETYPES: IntentArchetypeName[];
@@ -82,6 +94,32 @@ interface ShapeSignature {
     /** Whether the prompt includes few-shot examples. */
     hasExamples: boolean;
 }
+/**
+ * SINGLE source of truth for a call's output shape.
+ *
+ * Two independent expressions of this concept used to exist — `computeShape`
+ * (three-valued, feeding `compile_outcomes.shape_key`) and compile()'s Factor C
+ * screen (two-valued). They disagreed on exactly one case: tools present with
+ * no `structuredOutput`, which the shape signature calls `tool_call` and the
+ * screen called `text`. That gap let alpha.68's shape-altering discipline gates
+ * fire on tool-call surfaces — the surface class the design contract names as
+ * forbidden, because labelling claims inside a tool-call envelope manufactures
+ * the structured-output violations alpha.66 ships a retry for.
+ *
+ * A consumer `declared` value WINS over inference. The inference cannot see
+ * that an agentic surface carrying tools ultimately emits prose, so it is
+ * deliberately conservative — wrongly firing a shape-altering rule breaks a
+ * parser, wrongly withholding one only forgoes a lift. `constraints.outputMode`
+ * is the escape hatch for surfaces that know better.
+ *
+ * Takes the facts rather than a `PromptIR` so `dialect.ts` stays
+ * dependency-free (`ir.ts` imports THIS module, not the reverse).
+ */
+declare function resolveOutputMode(args: {
+    declared?: OutputMode;
+    structuredOutput?: boolean;
+    toolCount: number;
+}): OutputMode;
 declare function bucketContext(tokens: number): ContextBucket;
 declare function bucketToolCount(count: number): ToolCountBucket;
 declare function bucketHistory(turnCount: number): HistoryDepth;
@@ -96,4 +134,4 @@ declare function hashShape(s: ShapeSignature): string;
  */
 declare function learningKey(archetype: IntentArchetypeName, model: string, shape: ShapeSignature): string;
 
-export { ALL_ARCHETYPES, type ContextBucket, DIALECT_VERSION, type HistoryDepth, INTENT_ARCHETYPES, type IntentArchetypeName, type OutputMode, type ShapeSignature, type ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey };
+export { ALL_ARCHETYPES, type ContextBucket, DIALECT_VERSION, type HistoryDepth, INTENT_ARCHETYPES, type IntentArchetypeName, type OutputMode, type ShapeSignature, type ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey, resolveOutputMode };

package/dist/dialect.d.ts

@@ -12,8 +12,15 @@
  * The brain learns by `(archetype, model, shape)` tuples. Apps that declare
  * the same tuple inherit each other's mutations.
  *
- * v1 is intentionally small (9 archetypes, 5 shape dimensions). New entries
- * arrive in v2/v3 from real usage signals — never speculatively.
+ * v1 is intentionally small (10 archetypes, 5 shape dimensions). New entries
+ * arrive from real usage signals — never speculatively.
+ *
+ * Versioning note (alpha.62): `judge` was added as an ADDITIVE 10th entry
+ * under dialect-v1 rather than bumping to v2. Bumping the version string
+ * would fragment every existing learning key (`v1::…` → `v2::…`) for a
+ * purely additive vocabulary change; existing keys are untouched and judge
+ * keys are new, so no collision is possible. A v2 bump is reserved for
+ * changes that alter the MEANING of existing entries or the shape hash.
  */
 declare const DIALECT_VERSION: "v1";
 declare const INTENT_ARCHETYPES: {
@@ -62,6 +69,11 @@ declare const INTENT_ARCHETYPES: {
         readonly description: "Change format or style while preserving content";
         readonly examples: ["markdown → html", "formal → casual", "translate"];
     };
+    readonly judge: {
+        readonly name: "judge";
+        readonly description: "Pairwise comparison of two candidate outputs for the same input";
+        readonly examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"];
+    };
 };
 type IntentArchetypeName = keyof typeof INTENT_ARCHETYPES;
 declare const ALL_ARCHETYPES: IntentArchetypeName[];
@@ -82,6 +94,32 @@ interface ShapeSignature {
     /** Whether the prompt includes few-shot examples. */
     hasExamples: boolean;
 }
+/**
+ * SINGLE source of truth for a call's output shape.
+ *
+ * Two independent expressions of this concept used to exist — `computeShape`
+ * (three-valued, feeding `compile_outcomes.shape_key`) and compile()'s Factor C
+ * screen (two-valued). They disagreed on exactly one case: tools present with
+ * no `structuredOutput`, which the shape signature calls `tool_call` and the
+ * screen called `text`. That gap let alpha.68's shape-altering discipline gates
+ * fire on tool-call surfaces — the surface class the design contract names as
+ * forbidden, because labelling claims inside a tool-call envelope manufactures
+ * the structured-output violations alpha.66 ships a retry for.
+ *
+ * A consumer `declared` value WINS over inference. The inference cannot see
+ * that an agentic surface carrying tools ultimately emits prose, so it is
+ * deliberately conservative — wrongly firing a shape-altering rule breaks a
+ * parser, wrongly withholding one only forgoes a lift. `constraints.outputMode`
+ * is the escape hatch for surfaces that know better.
+ *
+ * Takes the facts rather than a `PromptIR` so `dialect.ts` stays
+ * dependency-free (`ir.ts` imports THIS module, not the reverse).
+ */
+declare function resolveOutputMode(args: {
+    declared?: OutputMode;
+    structuredOutput?: boolean;
+    toolCount: number;
+}): OutputMode;
 declare function bucketContext(tokens: number): ContextBucket;
 declare function bucketToolCount(count: number): ToolCountBucket;
 declare function bucketHistory(turnCount: number): HistoryDepth;
@@ -96,4 +134,4 @@ declare function hashShape(s: ShapeSignature): string;
  */
 declare function learningKey(archetype: IntentArchetypeName, model: string, shape: ShapeSignature): string;
 
-export { ALL_ARCHETYPES, type ContextBucket, DIALECT_VERSION, type HistoryDepth, INTENT_ARCHETYPES, type IntentArchetypeName, type OutputMode, type ShapeSignature, type ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey };
+export { ALL_ARCHETYPES, type ContextBucket, DIALECT_VERSION, type HistoryDepth, INTENT_ARCHETYPES, type IntentArchetypeName, type OutputMode, type ShapeSignature, type ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey, resolveOutputMode };

package/dist/dialect.js

@@ -28,7 +28,8 @@ __export(dialect_exports, {
   bucketToolCount: () => bucketToolCount,
   hashShape: () => hashShape,
   isArchetype: () => isArchetype,
-  learningKey: () => learningKey
+  learningKey: () => learningKey,
+  resolveOutputMode: () => resolveOutputMode
 });
 module.exports = __toCommonJS(dialect_exports);
 var DIALECT_VERSION = "v1";
@@ -77,12 +78,22 @@ var INTENT_ARCHETYPES = {
     name: "transform",
     description: "Change format or style while preserving content",
     examples: ["markdown \u2192 html", "formal \u2192 casual", "translate"]
+  },
+  judge: {
+    name: "judge",
+    description: "Pairwise comparison of two candidate outputs for the same input",
+    examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"]
   }
 };
 var ALL_ARCHETYPES = Object.keys(INTENT_ARCHETYPES);
 function isArchetype(name) {
   return name in INTENT_ARCHETYPES;
 }
+function resolveOutputMode(args) {
+  if (args.declared) return args.declared;
+  if (args.structuredOutput === true) return "json";
+  return args.toolCount > 0 ? "tool_call" : "text";
+}
 function bucketContext(tokens) {
   if (tokens < 1e3) return "tiny";
   if (tokens < 4e3) return "small";
@@ -123,5 +134,6 @@ function learningKey(archetype, model, shape) {
   bucketToolCount,
   hashShape,
   isArchetype,
-  learningKey
+  learningKey,
+  resolveOutputMode
 });

package/dist/dialect.mjs

@@ -7,8 +7,9 @@ import {
   bucketToolCount,
   hashShape,
   isArchetype,
-  learningKey
-} from "./chunk-5TI6PNSK.mjs";
+  learningKey,
+  resolveOutputMode
+} from "./chunk-BVEXV5KC.mjs";
 export {
   ALL_ARCHETYPES,
   DIALECT_VERSION,
@@ -18,5 +19,6 @@ export {
   bucketToolCount,
   hashShape,
   isArchetype,
-  learningKey
+  learningKey,
+  resolveOutputMode
 };

package/dist/glassbox/index.d.mts

@@ -0,0 +1,59 @@
+import { G as GlassboxEvent } from '../types-BDFrJkma.mjs';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-BDFrJkma.mjs';
+import '../ir-CnnJST_N.mjs';
+import '../dialect.mjs';
+
+/**
+ * subscribe(traceId) — public Glass-Box subscription export.
+ *
+ * Consumer route handlers (e.g. Vercel Edge `/api/glassbox/stream`) import
+ * this and bridge the ReadableStream to SSE. The browser-side panel then
+ * renders events in real time:
+ *
+ *   import { subscribe } from '@warmdrift/kgauto-compiler/glassbox';
+ *
+ *   export async function GET(req: Request) {
+ *     const { searchParams } = new URL(req.url);
+ *     const traceId = searchParams.get('traceId');
+ *     if (!traceId) return new Response('missing traceId', { status: 400 });
+ *     const stream = subscribe(traceId);
+ *     // ... bridge ReadableStream<GlassboxEvent> → SSE here ...
+ *   }
+ *
+ * Stream behavior:
+ *   - Emits events for `traceId` as they're published.
+ *   - Closes cleanly 60s after the last event (rolling TTL).
+ *   - If no events arrive within 60s of subscription, closes empty.
+ *   - Multiple subscribers on the same traceId all fan out.
+ *
+ * No replay: subscribe() picks up only events published AFTER subscription.
+ * Replay is the brain-poll surface's job (see design doc).
+ */
+
+/**
+ * Subscribe to Glass-Box events for a traceId. Returns a ReadableStream
+ * that yields GlassboxEvent objects until the per-trace TTL elapses.
+ *
+ * Cancelling the stream (consumer disconnect, AbortController, etc.) tears
+ * down the subscription cleanly via the underlying adapter.
+ */
+declare function subscribe(traceId: string): ReadableStream<GlassboxEvent>;
+/**
+ * Subscribe to Glass-Box events for ALL traces under an appId — the
+ * "tail-all" surface (alpha.26). Backs the extension's default Live mode:
+ * rather than needing a specific traceId ahead of time, the panel sees
+ * every event for the configured consumer as calls happen.
+ *
+ * Per-app routing fires only when emit call-sites pass `appId` (the typed
+ * builders thread `ir.appId` automatically). Per-trace channel continues to
+ * fire for `subscribe(traceId)` callers — both arms are independent.
+ *
+ * Cross-tenant isolation: the consumer's `/api/glassbox/stream` uses the
+ * factory's configured appId — no caller-supplied `?appId=` URL parameter,
+ * so a consumer cannot subscribe to another consumer's stream.
+ */
+declare function subscribeApp({ appId, }: {
+    appId: string;
+}): ReadableStream<GlassboxEvent>;
+
+export { GlassboxEvent, subscribe, subscribeApp };

package/dist/glassbox/index.d.ts

@@ -0,0 +1,59 @@
+import { G as GlassboxEvent } from '../types-B--CYzMo.js';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-B--CYzMo.js';
+import '../ir-BEQ28muo.js';
+import '../dialect.js';
+
+/**
+ * subscribe(traceId) — public Glass-Box subscription export.
+ *
+ * Consumer route handlers (e.g. Vercel Edge `/api/glassbox/stream`) import
+ * this and bridge the ReadableStream to SSE. The browser-side panel then
+ * renders events in real time:
+ *
+ *   import { subscribe } from '@warmdrift/kgauto-compiler/glassbox';
+ *
+ *   export async function GET(req: Request) {
+ *     const { searchParams } = new URL(req.url);
+ *     const traceId = searchParams.get('traceId');
+ *     if (!traceId) return new Response('missing traceId', { status: 400 });
+ *     const stream = subscribe(traceId);
+ *     // ... bridge ReadableStream<GlassboxEvent> → SSE here ...
+ *   }
+ *
+ * Stream behavior:
+ *   - Emits events for `traceId` as they're published.
+ *   - Closes cleanly 60s after the last event (rolling TTL).
+ *   - If no events arrive within 60s of subscription, closes empty.
+ *   - Multiple subscribers on the same traceId all fan out.
+ *
+ * No replay: subscribe() picks up only events published AFTER subscription.
+ * Replay is the brain-poll surface's job (see design doc).
+ */
+
+/**
+ * Subscribe to Glass-Box events for a traceId. Returns a ReadableStream
+ * that yields GlassboxEvent objects until the per-trace TTL elapses.
+ *
+ * Cancelling the stream (consumer disconnect, AbortController, etc.) tears
+ * down the subscription cleanly via the underlying adapter.
+ */
+declare function subscribe(traceId: string): ReadableStream<GlassboxEvent>;
+/**
+ * Subscribe to Glass-Box events for ALL traces under an appId — the
+ * "tail-all" surface (alpha.26). Backs the extension's default Live mode:
+ * rather than needing a specific traceId ahead of time, the panel sees
+ * every event for the configured consumer as calls happen.
+ *
+ * Per-app routing fires only when emit call-sites pass `appId` (the typed
+ * builders thread `ir.appId` automatically). Per-trace channel continues to
+ * fire for `subscribe(traceId)` callers — both arms are independent.
+ *
+ * Cross-tenant isolation: the consumer's `/api/glassbox/stream` uses the
+ * factory's configured appId — no caller-supplied `?appId=` URL parameter,
+ * so a consumer cannot subscribe to another consumer's stream.
+ */
+declare function subscribeApp({ appId, }: {
+    appId: string;
+}): ReadableStream<GlassboxEvent>;
+
+export { GlassboxEvent, subscribe, subscribeApp };