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

package/dist/profiles.mjs

@@ -1,13 +1,17 @@
 import {
   ALIASES,
+  _setProfileBrainHook,
   allProfiles,
+  allProfilesRaw,
   getProfile,
   profilesByProvider,
   tryGetProfile
-} from "./chunk-MBEI5UOM.mjs";
+} from "./chunk-JQGRWJZO.mjs";
 export {
   ALIASES,
+  _setProfileBrainHook,
   allProfiles,
+  allProfilesRaw,
   getProfile,
   profilesByProvider,
   tryGetProfile

package/dist/types-BjrIFPGe.d.mts

@@ -0,0 +1,131 @@
+import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-De2AQtlr.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 to a channel key. The channel is an opaque
+     * namespaced string — callers build it via `traceChannel(traceId)` or
+     * `appChannel(appId)` (see pubsub-upstash.ts). Returns a promise that
+     * resolves after the event is durably appended (or rejects on adapter
+     * failure — callers in emit.ts always swallow rejections).
+     *
+     * Pre-alpha.26 the parameter was named `traceId` because there was only
+     * one channel namespace; alpha.26 added per-app channels for the
+     * "tail-all" Live tab subscription. Behavior identical to the adapters —
+     * they treat the value as an opaque key — but the rename surfaces the
+     * generalization at the type level.
+     */
+    publish(channelKey: string, event: GlassboxEvent): Promise<void>;
+    /**
+     * Subscribe to events on a channel key. Returns a ReadableStream that
+     * emits GlassboxEvent objects as they're published. The stream closes
+     * cleanly after the channel-level TTL elapses since the LAST event
+     * (rolling 60s).
+     *
+     * If no publisher writes to the channel within 60s of subscription, the
+     * stream closes empty.
+     */
+    subscribe(channelKey: 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-D_JAhCv4.d.ts

@@ -0,0 +1,131 @@
+import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-BIAT9gJk.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 to a channel key. The channel is an opaque
+     * namespaced string — callers build it via `traceChannel(traceId)` or
+     * `appChannel(appId)` (see pubsub-upstash.ts). Returns a promise that
+     * resolves after the event is durably appended (or rejects on adapter
+     * failure — callers in emit.ts always swallow rejections).
+     *
+     * Pre-alpha.26 the parameter was named `traceId` because there was only
+     * one channel namespace; alpha.26 added per-app channels for the
+     * "tail-all" Live tab subscription. Behavior identical to the adapters —
+     * they treat the value as an opaque key — but the rename surfaces the
+     * generalization at the type level.
+     */
+    publish(channelKey: string, event: GlassboxEvent): Promise<void>;
+    /**
+     * Subscribe to events on a channel key. Returns a ReadableStream that
+     * emits GlassboxEvent objects as they're published. The stream closes
+     * cleanly after the channel-level TTL elapses since the LAST event
+     * (rolling 60s).
+     *
+     * If no publisher writes to the channel within 60s of subscription, the
+     * stream closes empty.
+     */
+    subscribe(channelKey: 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.3",
+  "version": "2.0.0-alpha.31",
   "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -20,11 +20,21 @@
       "types": "./dist/profiles.d.ts",
       "import": "./dist/profiles.mjs",
       "require": "./dist/profiles.js"
+    },
+    "./glassbox": {
+      "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 --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",