@warmdrift/kgauto-compiler 2.0.0-alpha.3 → 2.0.0-alpha.31

package/dist/glassbox/index.d.mts

@@ -0,0 +1,59 @@
+import { G as GlassboxEvent } from '../types-BjrIFPGe.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-BjrIFPGe.mjs';
+import '../ir-De2AQtlr.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-D_JAhCv4.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-D_JAhCv4.js';
+import '../ir-BIAT9gJk.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 };

package/dist/glassbox/index.js

@@ -0,0 +1,312 @@
+"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/glassbox/index.ts
+var glassbox_exports = {};
+__export(glassbox_exports, {
+  GLASSBOX_STREAM_TTL_MS: () => GLASSBOX_STREAM_TTL_MS,
+  subscribe: () => subscribe,
+  subscribeApp: () => subscribeApp
+});
+module.exports = __toCommonJS(glassbox_exports);
+
+// src/glassbox/types.ts
+var GLASSBOX_STREAM_TTL_MS = 6e4;
+
+// src/glassbox/pubsub-memory.ts
+var MemoryPubSub = class {
+  subscribers = /* @__PURE__ */ new Map();
+  async publish(channelKey, event) {
+    const subs = this.subscribers.get(channelKey);
+    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(channelKey, sub);
+    }
+  }
+  subscribe(channelKey) {
+    const self = this;
+    let sub;
+    return new ReadableStream({
+      start(controller) {
+        sub = {
+          controller,
+          ttlTimer: setTimeout(() => {
+            self.closeSubscriber(channelKey, sub);
+          }, GLASSBOX_STREAM_TTL_MS),
+          closed: false
+        };
+        let set = self.subscribers.get(channelKey);
+        if (!set) {
+          set = /* @__PURE__ */ new Set();
+          self.subscribers.set(channelKey, set);
+        }
+        set.add(sub);
+      },
+      cancel() {
+        if (sub) self.removeSubscriber(channelKey, sub);
+      }
+    });
+  }
+  /**
+   * Refresh the rolling TTL for a subscriber after an event lands. Replaces
+   * the existing timer with a fresh 60s one.
+   */
+  refreshTtl(channelKey, sub) {
+    clearTimeout(sub.ttlTimer);
+    sub.ttlTimer = setTimeout(() => {
+      this.closeSubscriber(channelKey, 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(channelKey, sub) {
+    if (sub.closed) return;
+    sub.closed = true;
+    clearTimeout(sub.ttlTimer);
+    try {
+      sub.controller.close();
+    } catch {
+    }
+    this.removeSubscriber(channelKey, sub);
+  }
+  removeSubscriber(channelKey, sub) {
+    clearTimeout(sub.ttlTimer);
+    const set = this.subscribers.get(channelKey);
+    if (!set) return;
+    set.delete(sub);
+    if (set.size === 0) this.subscribers.delete(channelKey);
+  }
+  /**
+   * 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(channelKey, event) {
+    const key = channelKey;
+    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(channelKey) {
+    const key = channelKey;
+    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 traceChannel(traceId) {
+  return `glassbox:trace:${traceId}`;
+}
+function appChannel(appId) {
+  return `glassbox:app:${appId}`;
+}
+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;
+}
+
+// src/glassbox/subscribe.ts
+function emptyStream() {
+  return new ReadableStream({
+    start(controller) {
+      controller.close();
+    }
+  });
+}
+function subscribe(traceId) {
+  if (!traceId) return emptyStream();
+  return getPubSub().subscribe(traceChannel(traceId));
+}
+function subscribeApp({
+  appId
+}) {
+  if (!appId) return emptyStream();
+  return getPubSub().subscribe(appChannel(appId));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GLASSBOX_STREAM_TTL_MS,
+  subscribe,
+  subscribeApp
+});

package/dist/glassbox/index.mjs

@@ -0,0 +1,12 @@
+import {
+  subscribe,
+  subscribeApp
+} from "../chunk-RO22VFIF.mjs";
+import {
+  GLASSBOX_STREAM_TTL_MS
+} from "../chunk-NBO4R5PC.mjs";
+export {
+  GLASSBOX_STREAM_TTL_MS,
+  subscribe,
+  subscribeApp
+};

package/dist/glassbox-routes/index.d.mts

@@ -0,0 +1,242 @@
+import { G as GlassboxEvent } from '../types-BjrIFPGe.mjs';
+import { h as Adapter, u as SectionKind } from '../ir-De2AQtlr.mjs';
+import '../dialect.mjs';
+
+/**
+ * Internal config + hook types for createGlassboxRoutes().
+ *
+ * The public contract lives on `GlassboxRoutesConfig` in ./index.ts; these
+ * are the narrower per-handler shapes consumed by proxy.ts and stream.ts.
+ */
+
+/**
+ * Wire contract for the Glass-Box Chrome extension's brain-poll endpoint.
+ *
+ * The list mode of `proxy(req)` returns `{ traces: TraceSummary[] }`. The
+ * detail mode (`?traceId=<id>`) returns a single `TraceDetail`. These are
+ * the camelCase shapes the extension renderer expects — distinct from the
+ * snake_case `compile_outcomes` row shape that PostgREST returns. The
+ * factory's typed `rowToSummary` / `rowToDetail` transformer is the single
+ * canonical boundary between the DB shape and the wire shape (see
+ * `feedback_typed_boundary_transformers.md` in kgauto memory for the rule).
+ */
+interface TraceSummary {
+    traceId: string;
+    appId: string;
+    archetype: string;
+    target: string;
+    createdAt: string;
+    tokensIn: number;
+    tokensOut: number;
+    estimatedCostUsd: number;
+}
+
+interface AdvisoryRecord {
+    level: 'info' | 'warn' | 'critical';
+    /** Stable advisory identifier, e.g. "caching-off-on-claude". */
+    code: string;
+    /** Consumer-renderable message — no internal jargon ("L-040", "R3" etc.). */
+    message: string;
+    /** Optional secondary one-liner. Renders below `message` in italics. */
+    suggestion?: string;
+    /** Deep link to the relevant section of `interfaces/kgauto.md` or docs. */
+    docsUrl?: string;
+    /**
+     * alpha.28+ — closed-union adaptation hint surfaced by the advisor when
+     * the advisory can be auto-mitigated by a config knob. Renderer surfaces
+     * as `→ try toolOrchestration: 'sequential'` on the advisory row.
+     *
+     * MUST stay byte-identical to Builder C's
+     * `BestPracticeAdvisory.suggestedAdaptation` shape (verified at Phase 2
+     * integration; the Adapter type itself is the contract).
+     */
+    suggestedAdaptation?: Adapter;
+}
+/**
+ * Cost-equivalent alternative the chain could have served. Computed at
+ * detail-view time by `computeCounterfactuals()` against the served row's
+ * observed token counts + archetype + cache state. Up to 2 entries, sorted
+ * cheapest first.
+ */
+interface TraceCounterfactual {
+    modelId: string;
+    estimatedCostUsd: number;
+    /** servedCostUsd - estimatedCostUsd (always > 0; only ≥10% savings kept). */
+    savingsUsd: number;
+    /** 0-100. */
+    savingsPercent: number;
+    /** Plain-English rationale tying archetype + perf score. */
+    reason: string;
+}
+/**
+ * Derived axis-health tri-state for the three Glass-Box dots
+ * (input-ratio · cache · fallback). Renderer reads; transformer computes.
+ *
+ * Thresholds (locked in design contract Phase 0):
+ *   - inputRatio: green ≤ 0.65 · yellow 0.65–0.85 · red > 0.85
+ *   - cache (only when historyCacheableTokens > 1000):
+ *       green if inputCacheHitRatio ≥ 0.5
+ *       yellow if 0.1 ≤ inputCacheHitRatio < 0.5
+ *       red if inputCacheHitRatio < 0.1
+ *       na if historyCacheableTokens ≤ 1000
+ *   - fallback: red iff fellOverFrom !== undefined && fellOverFrom !== target
+ */
+interface TraceHealth {
+    inputRatioStatus: 'green' | 'yellow' | 'red';
+    cacheStatus: 'green' | 'yellow' | 'red' | 'na';
+    fallbackStatus: 'green' | 'red';
+}
+/**
+ * alpha.29+ — wire-boundary representation of a translator section-rewrite.
+ *
+ * Distinct from the package-internal `SectionRewrite` type in `ir.ts`: this
+ * shape drops `originalText` + `transformedText` because those may carry
+ * consumer PII. The renderer shows the `rule` + `summary` only. Full text
+ * stays on `compile_outcomes.section_rewrites_applied` (Supabase row), gated
+ * by RLS for brain-side cross-app learning.
+ */
+interface TraceSectionRewrite {
+    /** Stable id of the rewritten section. */
+    sectionId: string;
+    /** Section-kind discriminator that triggered the rewrite. */
+    kind: SectionKind;
+    /** Stable rule identifier (e.g. `'sequential-tool-cliff-below-floor'`). */
+    rule: string;
+    /**
+     * Plain-English one-liner describing what fired and why. Renderer surfaces
+     * this on the Coaching card; no internal jargon ("L-040", "below floor").
+     */
+    summary: string;
+}
+interface TraceDetail extends TraceSummary {
+    mutationsApplied: string[];
+    advisories: AdvisoryRecord[];
+    rawRequest?: string;
+    rawResponse?: string;
+    /** Set when consumer passed a forceModel / fallback fired. */
+    requestedModel?: string;
+    /** Provider finish reason — 'stop' / 'max_tokens' / 'tool_use' / etc. */
+    finishReason?: string;
+    /** Time to first token (ms); populated when provider surfaces it. */
+    ttftMs?: number;
+    /** End-to-end wall-clock (ms); from migration 018. */
+    totalMs?: number;
+    /** Tools kept after relevance pass. */
+    toolsCount?: number;
+    /** Number of history messages at compile time. */
+    historyDepth?: number;
+    /** Rendered system prompt size in characters. */
+    systemPromptChars?: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    historyCacheableTokens: number;
+    /** Derived: cacheReadInputTokens / max(tokensIn, 1). 0-1. */
+    inputCacheHitRatio: number;
+    fellOverFrom?: string;
+    fallbackReason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
+    /** Up to 2 alternatives. Empty array (not undefined) when none qualify. */
+    counterfactuals?: TraceCounterfactual[];
+    /** Undefined when 7d volume < 5/day (insufficient data). */
+    projectedDailyCostUsd?: number;
+    /**
+     * alpha.29+ — translator activity for this trace. Empty array (not
+     * undefined) when no rewrites fired or pre-019 row. Surfaced in the
+     * Glass-Box Coaching card as synthetic info-level rows. PII-safe by
+     * construction: only sectionId + kind + rule + summary cross the wire.
+     */
+    sectionRewritesApplied: TraceSectionRewrite[];
+    health: TraceHealth;
+}
+
+/**
+ * Public entry point for `@warmdrift/kgauto-compiler/glassbox-routes`.
+ *
+ * One factory call from a Vercel Edge consumer route handler gets you both
+ * the replay-query (`proxy`) and live-SSE (`stream`) endpoints that the
+ * Glass-Box Chrome panel reads. Wiring is ~6 lines per app:
+ *
+ *   // app/api/glassbox/proxy/route.ts
+ *   import { createGlassboxRoutes } from '@warmdrift/kgauto-compiler/glassbox-routes';
+ *   const { proxy } = createGlassboxRoutes({
+ *     installToken:  process.env.GLASSBOX_INSTALL_TOKEN!,
+ *     extensionId:   process.env.GLASSBOX_EXTENSION_ID!,
+ *     brainEndpoint: process.env.GLASSBOX_BRAIN_ENDPOINT!,
+ *     brainJwt:      process.env.GLASSBOX_BRAIN_JWT!,      // scoped JWT (RLS via app_id claim)
+ *     brainAnonKey:  process.env.GLASSBOX_BRAIN_ANON_KEY!, // project anon/publishable key (Supabase apikey header)
+ *     appId:         'playbacksam',
+ *   });
+ *   export { proxy as GET };
+ *
+ * Auth model (defense in depth):
+ *   - Bearer install token   → primary, constant-time compared
+ *   - chrome-extension Origin → secondary CSRF gate
+ *
+ * Scrub: optional sanitization runs at the proxy boundary before events or
+ * rows leave the consumer's infrastructure. Per pii-scrubber-call-site-not-
+ * package: kgauto stays naive to PII policy; consumers pass scrub hooks
+ * that encode their own data-handling rules.
+ *
+ * Brain reads use the scoped JWT minted via migration 013. RLS enforces
+ * `app_id = jwt.claim.app_id`; the proxy filter is belt-and-suspenders for
+ * payload size + log legibility.
+ */
+
+interface GlassboxRoutesConfig {
+    /** Bearer token validated on every request via constant-time compare. Required. */
+    installToken: string;
+    /** chrome-extension://<id> — exact match required on Origin header. Required. */
+    extensionId: string;
+    /** Brain endpoint base (e.g. https://kgauto-brain.supabase.co). Used by `proxy` for replay queries. */
+    brainEndpoint: string;
+    /** Scoped JWT for brain reads. Use the per-consumer JWT minted via migration 013 (claim: app_id). Drives RLS via the `app_id` claim; sent as `Authorization: Bearer <jwt>` only. */
+    brainJwt: string;
+    /**
+     * Anon/publishable key for the Supabase `apikey` header. Supabase requires
+     * `apikey` to be one of the project's known keys (anon or service_role) —
+     * the scoped JWT in `brainJwt` doesn't qualify there. Pass the project's
+     * legacy `anon` key (JWT format, role=anon) or the modern `sb_publishable_...`
+     * key. Safe to expose at the wire (that's what "publishable" means).
+     *
+     * Pre-alpha.24 this was missing and `brainJwt` was used as apikey too — first
+     * real call always 401'd against real Supabase. Catching this required a
+     * pre-publish smoke against the real brain; unit tests with mocked fetch
+     * couldn't surface it. See L-117 in command-center/learnings.md.
+     */
+    brainAnonKey: string;
+    /** App scope filter — must match the JWT's app_id claim. */
+    appId: string;
+    /**
+     * Optional sanitization hook. Called with each event/trace BEFORE it leaves the consumer.
+     * Default: identity (no scrub). PII policy lives at the call-site, not in the package.
+     */
+    scrub?: (event: GlassboxEvent | Record<string, unknown>) => GlassboxEvent | Record<string, unknown>;
+    /**
+     * Test-only seam: override the brain fetch implementation. Production
+     * code never sets this; tests use it to mock PostgREST responses.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Test-only seam: override the per-trace live-stream subscriber. Production
+     * code resolves to the alpha.17 `subscribe()` export; tests inject a fake
+     * source ReadableStream<GlassboxEvent>.
+     */
+    subscribe?: (traceId: string) => ReadableStream<GlassboxEvent>;
+    /**
+     * Test-only seam: override the per-app "tail-all" subscriber (alpha.26).
+     * Production code resolves to the `subscribeApp()` export; tests inject
+     * a fake source. Backs the extension's default Live tab mode when no
+     * traceId is supplied in the URL.
+     */
+    subscribeApp?: (args: {
+        appId: string;
+    }) => ReadableStream<GlassboxEvent>;
+}
+interface GlassboxRoutes {
+    /** GET /api/glassbox/proxy?traceId=<id>  OR  ?limit=20 (recent traces) */
+    proxy: (req: Request) => Promise<Response>;
+    /** GET /api/glassbox/stream?traceId=<id>  (SSE) */
+    stream: (req: Request) => Promise<Response>;
+}
+declare function createGlassboxRoutes(config: GlassboxRoutesConfig): GlassboxRoutes;
+
+export { type GlassboxRoutes, type GlassboxRoutesConfig, type TraceDetail, type TraceSummary, createGlassboxRoutes };