@warmdrift/kgauto-compiler 2.0.0-alpha.17 → 2.0.0-alpha.18

package/dist/glassbox-routes/index.mjs

@@ -0,0 +1,269 @@
+import {
+  subscribe
+} from "../chunk-VZGMWKRT.mjs";
+import "../chunk-NUTC7NUC.mjs";
+
+// src/glassbox-routes/auth.ts
+import { Buffer } from "buffer";
+import { timingSafeEqual } from "crypto";
+var JSON_HEADERS = { "Content-Type": "application/json" };
+function jsonError(status, code) {
+  return new Response(JSON.stringify({ error: code }), {
+    status,
+    headers: JSON_HEADERS
+  });
+}
+function tokensEqual(a, b) {
+  if (a.length !== b.length) return false;
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+function checkAuth(req, config) {
+  const authHeader = req.headers.get("Authorization") ?? "";
+  const match = /^Bearer\s+(.+)$/i.exec(authHeader);
+  const provided = match?.[1]?.trim() ?? "";
+  if (!provided || !tokensEqual(provided, config.installToken)) {
+    return jsonError(401, "unauthorized");
+  }
+  const origin = req.headers.get("Origin") ?? "";
+  const expected = `chrome-extension://${config.extensionId}`;
+  if (origin !== expected) {
+    return jsonError(403, "forbidden_origin");
+  }
+  return null;
+}
+
+// src/glassbox-routes/proxy.ts
+var JSON_HEADERS2 = {
+  "Content-Type": "application/json",
+  "Cache-Control": "no-store"
+};
+var DEFAULT_LIMIT = 20;
+var MAX_LIMIT = 100;
+function jsonResponse(status, body) {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS2 });
+}
+function jsonError2(status, code) {
+  return jsonResponse(status, { error: code });
+}
+function applyScrub(row, scrub) {
+  if (!scrub || row == null || typeof row !== "object") return row;
+  try {
+    return scrub(row);
+  } catch {
+    return row;
+  }
+}
+function parseLimit(raw) {
+  if (!raw) return DEFAULT_LIMIT;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT;
+  return Math.min(n, MAX_LIMIT);
+}
+function createProxyHandler(config) {
+  const {
+    installToken,
+    extensionId,
+    brainEndpoint,
+    brainJwt,
+    appId,
+    scrub,
+    fetch: fetchImpl
+  } = config;
+  const doFetch = fetchImpl ?? ((...args) => globalThis.fetch(...args));
+  const base = brainEndpoint.replace(/\/+$/, "");
+  return async function proxy(req) {
+    const authFail = checkAuth(req, { installToken, extensionId });
+    if (authFail) return authFail;
+    const url = new URL(req.url);
+    const traceId = url.searchParams.get("traceId");
+    const limit = parseLimit(url.searchParams.get("limit"));
+    const qs = new URLSearchParams();
+    qs.set("app_id", `eq.${appId}`);
+    if (traceId) {
+      qs.set("trace_id", `eq.${traceId}`);
+    } else {
+      qs.set("order", "created_at.desc");
+      qs.set("limit", String(limit));
+    }
+    const brainUrl = `${base}/rest/v1/compile_outcomes?${qs.toString()}`;
+    let brainRes;
+    try {
+      brainRes = await doFetch(brainUrl, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${brainJwt}`,
+          apikey: brainJwt,
+          Accept: "application/json"
+        }
+      });
+    } catch {
+      return jsonError2(502, "brain_unavailable");
+    }
+    if (brainRes.status === 401 || brainRes.status === 403) {
+      return jsonError2(500, "brain_auth_misconfig");
+    }
+    if (brainRes.status >= 500) {
+      return jsonError2(502, "brain_unavailable");
+    }
+    if (!brainRes.ok) {
+      return jsonError2(400, "bad_request");
+    }
+    let rows;
+    try {
+      rows = await brainRes.json();
+    } catch {
+      return jsonError2(502, "brain_unavailable");
+    }
+    if (!Array.isArray(rows)) {
+      return jsonError2(502, "brain_unavailable");
+    }
+    const scrubbed = rows.map((row) => applyScrub(row, scrub));
+    return jsonResponse(200, scrubbed);
+  };
+}
+
+// src/glassbox-routes/stream.ts
+var SSE_HEADERS = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache, no-transform",
+  Connection: "keep-alive",
+  "X-Accel-Buffering": "no"
+};
+var JSON_HEADERS3 = { "Content-Type": "application/json" };
+function jsonError3(status, code) {
+  return new Response(JSON.stringify({ error: code }), {
+    status,
+    headers: JSON_HEADERS3
+  });
+}
+function applyScrub2(event, scrub) {
+  if (!scrub) return event;
+  try {
+    const out = scrub(event);
+    if (out && typeof out === "object" && typeof out.kind === "string" && typeof out.at === "number") {
+      return out;
+    }
+    return event;
+  } catch {
+    return event;
+  }
+}
+function sseFrame(eventName, data) {
+  const safeName = eventName.replace(/[\r\n]/g, "");
+  return `event: ${safeName}
+data: ${JSON.stringify(data)}
+
+`;
+}
+function createStreamHandler(config, subscribe2) {
+  const { installToken, extensionId, scrub } = config;
+  return async function stream(req) {
+    const authFail = checkAuth(req, { installToken, extensionId });
+    if (authFail) return authFail;
+    const url = new URL(req.url);
+    const traceId = url.searchParams.get("traceId");
+    if (!traceId) {
+      return jsonError3(400, "missing_trace_id");
+    }
+    const source = subscribe2(traceId);
+    const encoder = new TextEncoder();
+    let sourceReader;
+    let cancelled = false;
+    const body = new ReadableStream({
+      async start(controller) {
+        controller.enqueue(encoder.encode(sseFrame("ready", {})));
+        sourceReader = source.getReader();
+        const signal = req.signal;
+        if (signal) {
+          if (signal.aborted) {
+            cancelled = true;
+            await sourceReader.cancel();
+            try {
+              controller.close();
+            } catch {
+            }
+            return;
+          }
+          signal.addEventListener(
+            "abort",
+            () => {
+              cancelled = true;
+              sourceReader?.cancel().catch(() => {
+              });
+              try {
+                controller.close();
+              } catch {
+              }
+            },
+            { once: true }
+          );
+        }
+        try {
+          while (!cancelled) {
+            const { value, done } = await sourceReader.read();
+            if (done) break;
+            const scrubbed = applyScrub2(value, scrub);
+            controller.enqueue(
+              encoder.encode(sseFrame(scrubbed.kind, scrubbed))
+            );
+          }
+        } catch {
+        } finally {
+          try {
+            controller.close();
+          } catch {
+          }
+          try {
+            sourceReader?.releaseLock();
+          } catch {
+          }
+        }
+      },
+      cancel() {
+        cancelled = true;
+        sourceReader?.cancel().catch(() => {
+        });
+      }
+    });
+    return new Response(body, { status: 200, headers: SSE_HEADERS });
+  };
+}
+
+// src/glassbox-routes/index.ts
+function requireString(name, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`createGlassboxRoutes: ${name} is required`);
+  }
+  return value;
+}
+function createGlassboxRoutes(config) {
+  const installToken = requireString("installToken", config.installToken);
+  const extensionId = requireString("extensionId", config.extensionId);
+  const brainEndpoint = requireString("brainEndpoint", config.brainEndpoint);
+  const brainJwt = requireString("brainJwt", config.brainJwt);
+  const appId = requireString("appId", config.appId);
+  const proxy = createProxyHandler({
+    installToken,
+    extensionId,
+    brainEndpoint,
+    brainJwt,
+    appId,
+    scrub: config.scrub,
+    fetch: config.fetch
+  });
+  const stream = createStreamHandler(
+    {
+      installToken,
+      extensionId,
+      scrub: config.scrub
+    },
+    config.subscribe ?? subscribe
+  );
+  return { proxy, stream };
+}
+export {
+  createGlassboxRoutes
+};

package/dist/types-DWF6mPGg.d.mts

@@ -0,0 +1,122 @@
+import { j as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, g as CallAttempt } from './ir-C3P4gDt0.mjs';
+
+/**
+ * Glass-Box observability types (alpha.17).
+ *
+ * The substrate for kgauto's in-flight observability surface — a Chrome MV3
+ * side panel that renders compile + execute + advisor outputs in real-time.
+ * See design doc:
+ *   ~/.gstack/projects/stue-kgauto/stgreen-claude-serene-williamson-51a105-design-20260518-175356.md
+ *
+ * Wire shape is intentionally minimal:
+ *   { kind, at, data } — discriminated union by `kind`.
+ *
+ * Critical-path safety (L-086 derived): emit MUST NEVER fail the user's
+ * `call()` invocation. emit.ts wraps every adapter write in try/catch +
+ * silently drops on error. Consumers in Vercel Edge runtimes can lose one
+ * event without losing the response.
+ */
+
+/**
+ * Discriminator. Six event kinds cover the v1 substrate. New kinds added
+ * additively; the side-panel renderer treats unknown kinds as "ignore".
+ */
+type GlassboxEventKind = 'compile.start' | 'compile.done' | 'execute.attempt' | 'execute.success' | 'advisory.fired' | 'fallback.walked';
+/**
+ * Wire envelope. Every emit lands as one of these.
+ *
+ *   - kind:    discriminator
+ *   - at:      unix milliseconds (Date.now())
+ *   - data:    kind-specific payload
+ *
+ * `data` typed loosely as Record<string, unknown> for serialization-friendliness;
+ * the per-kind builders below populate it with the structured shape expected
+ * by the renderer. We deliberately do NOT typescript-narrow `data` by kind on
+ * the wire type — the side panel reads JSON from SSE and only the renderer
+ * needs the narrowed shape. Internal callers (emit.ts) get type assistance via
+ * the typed factory helpers in emit.ts.
+ */
+interface GlassboxEvent {
+    kind: GlassboxEventKind;
+    at: number;
+    data: Record<string, unknown>;
+}
+/**
+ * Per-kind data shapes. Surfaced as type aids; not enforced at the
+ * GlassboxEvent boundary (intentionally — see comment above).
+ */
+interface CompileStartData {
+    appId: string;
+    archetype: string;
+    models: string[];
+}
+interface CompileDoneData {
+    target: string;
+    provider: string;
+    fallbackChain: string[];
+    tokensIn: number;
+    estimatedCostUsd: number;
+    mutationsApplied: MutationApplied[];
+    advisories: BestPracticeAdvisory[];
+}
+interface ExecuteAttemptData {
+    model: string;
+    attemptIndex: number;
+}
+interface ExecuteSuccessData {
+    model: string;
+    tokensIn: number;
+    tokensOut: number;
+    latencyMs: number;
+}
+interface AdvisoryFiredData {
+    code: string;
+    message: string;
+}
+interface FallbackWalkedData {
+    from: string;
+    to: string;
+    reason: FallbackReason | 'unknown';
+    attempt: CallAttempt;
+}
+/**
+ * Pub/sub backend interface. Two adapters implement it: in-memory (dev /
+ * single-process) and Upstash Redis Streams (Vercel Edge multi-instance).
+ *
+ * The choice is made at module load (NOT per-call) based on env-var presence:
+ *   if (UPSTASH_REDIS_URL && UPSTASH_REDIS_TOKEN) → Upstash
+ *   else                                          → in-memory
+ *
+ * Stream TTL: 60s after last event. After that, subscriber stream closes
+ * cleanly. The adapter owns its own TTL clock; subscribe() is agnostic.
+ */
+interface GlassboxPubSub {
+    /**
+     * Publish a single event for a traceId. Returns a promise that resolves
+     * after the event is durably appended (or rejects on adapter failure —
+     * callers in emit.ts always swallow rejections).
+     */
+    publish(traceId: string, event: GlassboxEvent): Promise<void>;
+    /**
+     * Subscribe to events for a traceId. Returns a ReadableStream that emits
+     * GlassboxEvent objects as they're published. The stream closes cleanly
+     * after the per-trace TTL elapses since the LAST event (rolling 60s).
+     *
+     * If the traceId has no publisher within 60s of subscription, the stream
+     * closes empty.
+     */
+    subscribe(traceId: string): ReadableStream<GlassboxEvent>;
+    /**
+     * Test-only escape hatch. Clears any in-memory state. Upstash adapter
+     * no-ops (server-side state isn't accessible from here). Tests reach for
+     * this between cases to keep adapters hermetic.
+     */
+    _reset?(): void;
+}
+/**
+ * TTL applied to a stream after each event. The design doc names 60s; this
+ * constant centralizes it so both adapters + tests agree.
+ */
+declare const GLASSBOX_STREAM_TTL_MS = 60000;
+
+export { type AdvisoryFiredData as A, type CompileDoneData as C, type ExecuteAttemptData as E, type FallbackWalkedData as F, type GlassboxEvent as G, type CompileStartData as a, type ExecuteSuccessData as b, GLASSBOX_STREAM_TTL_MS as c, type GlassboxEventKind as d, type GlassboxPubSub as e };

package/dist/types-xeklorHU.d.ts

@@ -0,0 +1,122 @@
+import { j as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, g as CallAttempt } from './ir-CFHU3BUT.js';
+
+/**
+ * Glass-Box observability types (alpha.17).
+ *
+ * The substrate for kgauto's in-flight observability surface — a Chrome MV3
+ * side panel that renders compile + execute + advisor outputs in real-time.
+ * See design doc:
+ *   ~/.gstack/projects/stue-kgauto/stgreen-claude-serene-williamson-51a105-design-20260518-175356.md
+ *
+ * Wire shape is intentionally minimal:
+ *   { kind, at, data } — discriminated union by `kind`.
+ *
+ * Critical-path safety (L-086 derived): emit MUST NEVER fail the user's
+ * `call()` invocation. emit.ts wraps every adapter write in try/catch +
+ * silently drops on error. Consumers in Vercel Edge runtimes can lose one
+ * event without losing the response.
+ */
+
+/**
+ * Discriminator. Six event kinds cover the v1 substrate. New kinds added
+ * additively; the side-panel renderer treats unknown kinds as "ignore".
+ */
+type GlassboxEventKind = 'compile.start' | 'compile.done' | 'execute.attempt' | 'execute.success' | 'advisory.fired' | 'fallback.walked';
+/**
+ * Wire envelope. Every emit lands as one of these.
+ *
+ *   - kind:    discriminator
+ *   - at:      unix milliseconds (Date.now())
+ *   - data:    kind-specific payload
+ *
+ * `data` typed loosely as Record<string, unknown> for serialization-friendliness;
+ * the per-kind builders below populate it with the structured shape expected
+ * by the renderer. We deliberately do NOT typescript-narrow `data` by kind on
+ * the wire type — the side panel reads JSON from SSE and only the renderer
+ * needs the narrowed shape. Internal callers (emit.ts) get type assistance via
+ * the typed factory helpers in emit.ts.
+ */
+interface GlassboxEvent {
+    kind: GlassboxEventKind;
+    at: number;
+    data: Record<string, unknown>;
+}
+/**
+ * Per-kind data shapes. Surfaced as type aids; not enforced at the
+ * GlassboxEvent boundary (intentionally — see comment above).
+ */
+interface CompileStartData {
+    appId: string;
+    archetype: string;
+    models: string[];
+}
+interface CompileDoneData {
+    target: string;
+    provider: string;
+    fallbackChain: string[];
+    tokensIn: number;
+    estimatedCostUsd: number;
+    mutationsApplied: MutationApplied[];
+    advisories: BestPracticeAdvisory[];
+}
+interface ExecuteAttemptData {
+    model: string;
+    attemptIndex: number;
+}
+interface ExecuteSuccessData {
+    model: string;
+    tokensIn: number;
+    tokensOut: number;
+    latencyMs: number;
+}
+interface AdvisoryFiredData {
+    code: string;
+    message: string;
+}
+interface FallbackWalkedData {
+    from: string;
+    to: string;
+    reason: FallbackReason | 'unknown';
+    attempt: CallAttempt;
+}
+/**
+ * Pub/sub backend interface. Two adapters implement it: in-memory (dev /
+ * single-process) and Upstash Redis Streams (Vercel Edge multi-instance).
+ *
+ * The choice is made at module load (NOT per-call) based on env-var presence:
+ *   if (UPSTASH_REDIS_URL && UPSTASH_REDIS_TOKEN) → Upstash
+ *   else                                          → in-memory
+ *
+ * Stream TTL: 60s after last event. After that, subscriber stream closes
+ * cleanly. The adapter owns its own TTL clock; subscribe() is agnostic.
+ */
+interface GlassboxPubSub {
+    /**
+     * Publish a single event for a traceId. Returns a promise that resolves
+     * after the event is durably appended (or rejects on adapter failure —
+     * callers in emit.ts always swallow rejections).
+     */
+    publish(traceId: string, event: GlassboxEvent): Promise<void>;
+    /**
+     * Subscribe to events for a traceId. Returns a ReadableStream that emits
+     * GlassboxEvent objects as they're published. The stream closes cleanly
+     * after the per-trace TTL elapses since the LAST event (rolling 60s).
+     *
+     * If the traceId has no publisher within 60s of subscription, the stream
+     * closes empty.
+     */
+    subscribe(traceId: string): ReadableStream<GlassboxEvent>;
+    /**
+     * Test-only escape hatch. Clears any in-memory state. Upstash adapter
+     * no-ops (server-side state isn't accessible from here). Tests reach for
+     * this between cases to keep adapters hermetic.
+     */
+    _reset?(): void;
+}
+/**
+ * TTL applied to a stream after each event. The design doc names 60s; this
+ * constant centralizes it so both adapters + tests agree.
+ */
+declare const GLASSBOX_STREAM_TTL_MS = 60000;
+
+export { type AdvisoryFiredData as A, type CompileDoneData as C, type ExecuteAttemptData as E, type FallbackWalkedData as F, type GlassboxEvent as G, type CompileStartData as a, type ExecuteSuccessData as b, GLASSBOX_STREAM_TTL_MS as c, type GlassboxEventKind as d, type GlassboxPubSub as e };

package/package.json

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