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

package/dist/chunk-NUTC7NUC.mjs

@@ -0,0 +1,298 @@
+// src/glassbox/types.ts
+var GLASSBOX_STREAM_TTL_MS = 6e4;
+
+// src/glassbox/pubsub-memory.ts
+var MemoryPubSub = class {
+  subscribers = /* @__PURE__ */ new Map();
+  async publish(traceId, event) {
+    const subs = this.subscribers.get(traceId);
+    if (!subs || subs.size === 0) return;
+    for (const sub of subs) {
+      if (sub.closed) continue;
+      try {
+        sub.controller.enqueue(event);
+      } catch {
+        sub.closed = true;
+        continue;
+      }
+      this.refreshTtl(traceId, sub);
+    }
+  }
+  subscribe(traceId) {
+    const self = this;
+    let sub;
+    return new ReadableStream({
+      start(controller) {
+        sub = {
+          controller,
+          ttlTimer: setTimeout(() => {
+            self.closeSubscriber(traceId, sub);
+          }, GLASSBOX_STREAM_TTL_MS),
+          closed: false
+        };
+        let set = self.subscribers.get(traceId);
+        if (!set) {
+          set = /* @__PURE__ */ new Set();
+          self.subscribers.set(traceId, set);
+        }
+        set.add(sub);
+      },
+      cancel() {
+        if (sub) self.removeSubscriber(traceId, sub);
+      }
+    });
+  }
+  /**
+   * Refresh the rolling TTL for a subscriber after an event lands. Replaces
+   * the existing timer with a fresh 60s one.
+   */
+  refreshTtl(traceId, sub) {
+    clearTimeout(sub.ttlTimer);
+    sub.ttlTimer = setTimeout(() => {
+      this.closeSubscriber(traceId, sub);
+    }, GLASSBOX_STREAM_TTL_MS);
+  }
+  /**
+   * Close the subscriber's stream cleanly and remove from the fan-out set.
+   * Idempotent — safe to call multiple times.
+   */
+  closeSubscriber(traceId, sub) {
+    if (sub.closed) return;
+    sub.closed = true;
+    clearTimeout(sub.ttlTimer);
+    try {
+      sub.controller.close();
+    } catch {
+    }
+    this.removeSubscriber(traceId, sub);
+  }
+  removeSubscriber(traceId, sub) {
+    clearTimeout(sub.ttlTimer);
+    const set = this.subscribers.get(traceId);
+    if (!set) return;
+    set.delete(sub);
+    if (set.size === 0) this.subscribers.delete(traceId);
+  }
+  /**
+   * Test-only reset. Tears down all subscribers, clears all state. Calling
+   * outside of tests is harmless but cancels every active stream.
+   */
+  _reset() {
+    for (const [, set] of this.subscribers) {
+      for (const sub of set) {
+        this.closeSubscriber("", sub);
+      }
+    }
+    this.subscribers.clear();
+  }
+};
+
+// src/glassbox/pubsub-upstash.ts
+var UpstashPubSub = class {
+  url;
+  token;
+  fetchImpl;
+  blockMs;
+  maxLen;
+  constructor(cfg) {
+    this.url = cfg.url.replace(/\/$/, "");
+    this.token = cfg.token;
+    this.fetchImpl = cfg.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.blockMs = cfg.blockMs ?? 100;
+    this.maxLen = cfg.maxLen ?? 100;
+  }
+  async publish(traceId, event) {
+    const key = streamKey(traceId);
+    const payload = JSON.stringify(event);
+    await this.cmd([
+      "XADD",
+      key,
+      "MAXLEN",
+      "~",
+      String(this.maxLen),
+      "*",
+      "event",
+      payload
+    ]);
+    await this.cmd(["EXPIRE", key, String(Math.ceil(GLASSBOX_STREAM_TTL_MS / 1e3))]);
+  }
+  subscribe(traceId) {
+    const key = streamKey(traceId);
+    const self = this;
+    let cursor = "$";
+    let cancelled = false;
+    let ttlDeadline = Date.now() + GLASSBOX_STREAM_TTL_MS;
+    return new ReadableStream({
+      async start(controller) {
+        try {
+          while (!cancelled && Date.now() < ttlDeadline) {
+            const resp = await self.cmd([
+              "XREAD",
+              "BLOCK",
+              String(self.blockMs),
+              "STREAMS",
+              key,
+              cursor
+            ]);
+            if (cancelled) break;
+            const parsed = parseXReadResult(resp.result);
+            if (parsed.entries.length === 0) {
+              continue;
+            }
+            for (const entry of parsed.entries) {
+              const evt = decodeEvent(entry.fields);
+              if (evt) {
+                try {
+                  controller.enqueue(evt);
+                } catch {
+                  cancelled = true;
+                  break;
+                }
+              }
+              cursor = entry.id;
+            }
+            ttlDeadline = Date.now() + GLASSBOX_STREAM_TTL_MS;
+          }
+        } catch (err) {
+          if (!cancelled) {
+            try {
+              controller.error(err);
+            } catch {
+            }
+            return;
+          }
+        }
+        try {
+          controller.close();
+        } catch {
+        }
+      },
+      cancel() {
+        cancelled = true;
+      }
+    });
+  }
+  async cmd(args) {
+    const res = await this.fetchImpl(this.url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(args)
+    });
+    if (!res.ok) {
+      throw new Error(`Upstash ${args[0]} failed: HTTP ${res.status}`);
+    }
+    const json = await res.json();
+    if (json.error) {
+      throw new Error(`Upstash ${args[0]} failed: ${json.error}`);
+    }
+    return json;
+  }
+};
+function streamKey(traceId) {
+  return `glassbox:trace:${traceId}`;
+}
+function decodeEvent(fields) {
+  const raw = fields["event"];
+  if (!raw) return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.kind === "string" && typeof parsed.at === "number") {
+      return parsed;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parseXReadResult(raw) {
+  if (!Array.isArray(raw)) return { entries: [] };
+  const entries = [];
+  for (const stream of raw) {
+    if (!Array.isArray(stream) || stream.length < 2) continue;
+    const streamEntries = stream[1];
+    if (!Array.isArray(streamEntries)) continue;
+    for (const entry of streamEntries) {
+      if (!Array.isArray(entry) || entry.length < 2) continue;
+      const id = String(entry[0]);
+      const flat = entry[1];
+      if (!Array.isArray(flat)) continue;
+      const fields = {};
+      for (let i = 0; i < flat.length; i += 2) {
+        const k = flat[i];
+        const v = flat[i + 1];
+        if (typeof k === "string") fields[k] = String(v ?? "");
+      }
+      entries.push({ id, fields });
+    }
+  }
+  return { entries };
+}
+
+// src/glassbox/emit.ts
+var activePubSub;
+function getPubSub() {
+  if (activePubSub) return activePubSub;
+  const url = readEnv("UPSTASH_REDIS_URL");
+  const token = readEnv("UPSTASH_REDIS_TOKEN");
+  if (url && token) {
+    activePubSub = new UpstashPubSub({ url, token });
+  } else {
+    activePubSub = new MemoryPubSub();
+  }
+  return activePubSub;
+}
+function readEnv(key) {
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      const v = process.env[key];
+      return v && v.trim() !== "" ? v : void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function emitGlassboxEvent(traceId, kind, data) {
+  if (!traceId) return;
+  const event = { kind, at: Date.now(), data };
+  const ps = getPubSub();
+  try {
+    const p = ps.publish(traceId, event);
+    if (p && typeof p.then === "function") {
+      p.catch(() => {
+      });
+    }
+  } catch {
+  }
+}
+function emitCompileStart(traceId, data) {
+  emitGlassboxEvent(traceId, "compile.start", data);
+}
+function emitCompileDone(traceId, data) {
+  emitGlassboxEvent(traceId, "compile.done", data);
+}
+function emitExecuteAttempt(traceId, data) {
+  emitGlassboxEvent(traceId, "execute.attempt", data);
+}
+function emitExecuteSuccess(traceId, data) {
+  emitGlassboxEvent(traceId, "execute.success", data);
+}
+function emitAdvisoryFired(traceId, data) {
+  emitGlassboxEvent(traceId, "advisory.fired", data);
+}
+function emitFallbackWalked(traceId, data) {
+  emitGlassboxEvent(traceId, "fallback.walked", data);
+}
+
+export {
+  GLASSBOX_STREAM_TTL_MS,
+  getPubSub,
+  emitCompileStart,
+  emitCompileDone,
+  emitExecuteAttempt,
+  emitExecuteSuccess,
+  emitAdvisoryFired,
+  emitFallbackWalked
+};

package/dist/glassbox/index.d.mts

@@ -0,0 +1,159 @@
+import { j as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, g as CallAttempt } from '../ir-C3P4gDt0.mjs';
+import '../dialect.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;
+
+/**
+ * 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>;
+
+export { type AdvisoryFiredData, type CompileDoneData, type CompileStartData, type ExecuteAttemptData, type ExecuteSuccessData, type FallbackWalkedData, GLASSBOX_STREAM_TTL_MS, type GlassboxEvent, type GlassboxEventKind, type GlassboxPubSub, subscribe };

package/dist/glassbox/index.d.ts

@@ -0,0 +1,159 @@
+import { j as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, g as CallAttempt } from '../ir-CFHU3BUT.js';
+import '../dialect.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;
+
+/**
+ * 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>;
+
+export { type AdvisoryFiredData, type CompileDoneData, type CompileStartData, type ExecuteAttemptData, type ExecuteSuccessData, type FallbackWalkedData, GLASSBOX_STREAM_TTL_MS, type GlassboxEvent, type GlassboxEventKind, type GlassboxPubSub, subscribe };