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

package/dist/profiles.d.ts

@@ -1,2 +1,137 @@
-export { g as ALIASES, h as CacheStrategy, k as CliffRule, L as LoweringSpec, M as ModelProfile, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, _ as _setProfileBrainHook, t as allProfiles, x as allProfilesRaw, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-CVB2_5C8.js';
-import './dialect.js';
+import { f as Provider } from './ir-CFHU3BUT.js';
+import { IntentArchetypeName } from './dialect.js';
+
+/**
+ * Model profiles — executable knowledge about each provider/model.
+ *
+ * Unlike v1 which carried `known_failures` as prose strings, v2 makes them
+ * executable: cliffs trigger guards, lowering describes the wire format,
+ * recovery handlers describe what to do after specific failures.
+ *
+ * Each profile is the answer to "if I want to call THIS model with THIS
+ * shape of work, what does it need from me, and what should I do when it
+ * fails?"
+ */
+
+type StructuredOutputCapability = 'native' | 'grammar' | 'none';
+type SystemPromptMode = 'inline' | 'separate' | 'as_developer' | 'unsupported';
+type CacheStrategy = 'cache_control' | 'cachedContent' | 'unsupported';
+interface CliffRule {
+    /** What metric triggers this cliff. */
+    metric: 'input_tokens' | 'tool_count' | 'history_turns' | 'thinking_with_short_output';
+    /** Threshold — meaning depends on metric. */
+    threshold: number;
+    /** What action to take when triggered. */
+    action: 'downgrade_quality_warning' | 'drop_to_top_relevant' | 'force_thinking_budget_zero' | 'force_terse_output' | 'escalate_target' | 'strip_tools';
+    /**
+     * Optional: only fire this cliff when the IR's intent.archetype matches.
+     * Used for archetype-specific failure modes (e.g. Gemini Flash returns
+     * empty when summarize is offered tools).
+     */
+    whenIntent?: IntentArchetypeName;
+    /** Human-readable reason for digest reporting. */
+    reason: string;
+}
+interface RecoveryRule {
+    /** What signal triggers recovery. */
+    signal: 'empty_response_after_tool' | 'empty_response' | 'malformed_function_call' | 'rate_limit' | 'model_not_found' | 'context_overflow';
+    /** Action: retry with adjusted params, or escalate to next fallback. */
+    action: 'retry_with_params' | 'escalate' | 'log_only';
+    /** When action=retry_with_params, the param adjustments to apply. */
+    retryParams?: Record<string, unknown>;
+    /** Max retries with this rule. */
+    maxRetries?: number;
+    /** Human-readable reason for digest reporting. */
+    reason: string;
+}
+interface LoweringSpec {
+    /** Where the system prompt goes. */
+    system: {
+        mode: SystemPromptMode;
+        field?: string;
+    };
+    /** Cache strategy + parameters. */
+    cache: {
+        strategy: CacheStrategy;
+        /** Min tokens before caching is worth it (provider rules). */
+        minTokens?: number;
+        /** Discount factor on cached input (0.1 = 10% of normal price). */
+        discount?: number;
+        /** TTL hint in seconds. */
+        ttlSeconds?: number;
+    };
+    /** Tool format identifier — see lower.ts for supported formats. */
+    tools?: {
+        format: 'anthropic' | 'google' | 'openai' | 'deepseek';
+    };
+    /** Thinking config — present iff this model has a thinking knob. */
+    thinking?: {
+        /** Field path on the request. */
+        field: string;
+        /** Default value when caller hasn't specified. */
+        default?: number | 'auto' | 'off';
+    };
+}
+interface ModelProfile {
+    id: string;
+    provider: Provider;
+    status: 'current' | 'preview' | 'legacy';
+    maxContextTokens: number;
+    maxOutputTokens: number;
+    maxTools: number;
+    parallelToolCalls: boolean;
+    structuredOutput: StructuredOutputCapability;
+    systemPromptMode: SystemPromptMode;
+    streaming: boolean;
+    cliffs: CliffRule[];
+    costInputPer1m: number;
+    costOutputPer1m: number;
+    lowering: LoweringSpec;
+    recovery: RecoveryRule[];
+    strengths: string[];
+    weaknesses: string[];
+    notes?: string;
+    verifiedAgainstDocs?: string;
+    /**
+     * Hand-curated per-archetype performance score on a 0-10 scale.
+     *
+     *   10 = frontier on this archetype (e.g. Opus 4.7 on critique)
+     *    8 = strong second tier (Sonnet on plan, Pro on extract)
+     *    7 = competent (Haiku on classify, Flash on hunt)
+     *    5 = acceptable for tolerant archetypes (Flash-Lite on classify)
+     *    3 = degraded (Flash on critique, DeepSeek on hunt)
+     *
+     * Missing archetypes default to `5` (no data, neutral). Each non-default
+     * value should carry a one-line rationale in the profile's note or inline
+     * comment citing brain evidence, family prior, or "starter hypothesis —
+     * verify with telemetry."
+     *
+     * Source today: hand-curated from master plan §3.3 + §6.2 starter tables.
+     * Source tomorrow (alpha.10+): brain `archetype_model_evidence` view.
+     *
+     * Anti-hallucination guardrail (master plan §2.5): when the watcher's
+     * `--audit-fields` flag flags a profile stale (>90 days since
+     * verifiedAgainstDocs), the archetypePerf values get re-audited
+     * alongside capability fields. AI-trained intuition is NOT a valid
+     * source — only docs or brain evidence.
+     *
+     * alpha.9.
+     */
+    archetypePerf?: Partial<Record<IntentArchetypeName, number>>;
+}
+declare const ALIASES: Record<string, string>;
+interface ProfileBrainHook {
+    getProfile?: (canonicalId: string) => ModelProfile | undefined;
+    resolveAlias?: (id: string) => string | undefined;
+}
+/** @internal — called by models-brain.ts at module load. */
+declare function _setProfileBrainHook(hook: ProfileBrainHook): void;
+declare function getProfile(id: string): ModelProfile;
+declare function tryGetProfile(id: string): ModelProfile | undefined;
+declare function allProfiles(): readonly ModelProfile[];
+/** @internal — bundled-only access for adapters that need a non-brain
+ *  fallback baseline (avoids a brain → profiles → brain re-entry). */
+declare function allProfilesRaw(): readonly ModelProfile[];
+declare function profilesByProvider(provider: Provider): readonly ModelProfile[];
+
+export { ALIASES, type CacheStrategy, type CliffRule, type LoweringSpec, type ModelProfile, type RecoveryRule, type StructuredOutputCapability, type SystemPromptMode, _setProfileBrainHook, allProfiles, allProfilesRaw, getProfile, profilesByProvider, tryGetProfile };

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.16",
+  "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",
@@ -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",