@kb-labs/core-platform 1.0.0

package/dist/index.js

@@ -0,0 +1,1381 @@
+import { createHash } from 'crypto';
+import path from 'path';
+
+// src/adapters/llm-types.ts
+var TIER_ORDER = [
+  "small",
+  "medium",
+  "large"
+];
+function isTierHigher(a, b) {
+  return TIER_ORDER.indexOf(a) > TIER_ORDER.indexOf(b);
+}
+function isTierLower(a, b) {
+  return TIER_ORDER.indexOf(a) < TIER_ORDER.indexOf(b);
+}
+
+// src/wrappers/analytics-llm.ts
+var AnalyticsLLM = class {
+  constructor(realLLM, analytics) {
+    this.realLLM = realLLM;
+    this.analytics = analytics;
+  }
+  async getProtocolCapabilities() {
+    if (!this.realLLM.getProtocolCapabilities) {
+      return {
+        cache: { supported: false },
+        stream: { supported: true }
+      };
+    }
+    return this.realLLM.getProtocolCapabilities();
+  }
+  /**
+   * Generate a completion with analytics tracking.
+   */
+  async complete(prompt, options) {
+    const startTime = Date.now();
+    const requestId = generateRequestId();
+    const metadata = options?.metadata;
+    await this.analytics.track("llm.completion.started", {
+      requestId,
+      tier: metadata?.tier,
+      provider: metadata?.provider,
+      model: options?.model,
+      cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+      cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+      streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+      streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+      streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+      promptLength: prompt.length,
+      maxTokens: options?.maxTokens,
+      temperature: options?.temperature
+    });
+    try {
+      const response = await this.realLLM.complete(prompt, options);
+      await this.trackCacheOutcome(requestId, metadata, response);
+      const durationMs = Date.now() - startTime;
+      const usageMetrics = buildUsageAnalytics(response);
+      await this.analytics.track("llm.completion.completed", {
+        requestId,
+        tier: metadata?.tier,
+        provider: metadata?.provider,
+        model: response.model,
+        cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+        cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+        streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+        streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+        streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+        ...usageMetrics,
+        durationMs
+      });
+      return response;
+    } catch (error) {
+      await this.analytics.track("llm.completion.error", {
+        requestId,
+        tier: metadata?.tier,
+        provider: metadata?.provider,
+        cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+        cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+        streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+        streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+        streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  /**
+   * Stream a completion.
+   * Note: Streaming is harder to track token-by-token, so we track start/end only.
+   */
+  async *stream(prompt, options) {
+    const startTime = Date.now();
+    const requestId = generateRequestId();
+    const metadata = options?.metadata;
+    await this.analytics.track("llm.stream.started", {
+      requestId,
+      tier: metadata?.tier,
+      provider: metadata?.provider,
+      model: options?.model,
+      cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+      cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+      streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+      streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+      streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+      promptLength: prompt.length
+    });
+    try {
+      let totalChunks = 0;
+      let totalLength = 0;
+      for await (const chunk of this.realLLM.stream(prompt, options)) {
+        totalChunks++;
+        totalLength += chunk.length;
+        yield chunk;
+      }
+      await this.analytics.track("llm.stream.completed", {
+        requestId,
+        tier: metadata?.tier,
+        provider: metadata?.provider,
+        model: options?.model,
+        cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+        cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+        streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+        streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+        streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+        durationMs: Date.now() - startTime,
+        totalChunks,
+        totalLength
+      });
+    } catch (error) {
+      await this.analytics.track("llm.stream.error", {
+        requestId,
+        tier: metadata?.tier,
+        provider: metadata?.provider,
+        cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+        cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+        streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+        streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+        streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  /**
+   * Chat with native tool calling support (optional).
+   * Proxies to underlying LLM if it supports chatWithTools.
+   */
+  async chatWithTools(messages, options) {
+    if (!this.realLLM.chatWithTools) {
+      throw new Error("Underlying LLM does not support chatWithTools");
+    }
+    const startTime = Date.now();
+    const requestId = generateRequestId();
+    const metadata = options?.metadata;
+    await this.analytics.track("llm.chatWithTools.started", {
+      requestId,
+      tier: metadata?.tier,
+      provider: metadata?.provider,
+      model: options?.model,
+      cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+      cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+      streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+      streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+      streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+      messageCount: messages.length,
+      toolCount: options.tools.length,
+      toolChoice: options.toolChoice,
+      maxTokens: options?.maxTokens,
+      temperature: options?.temperature
+    });
+    try {
+      const response = await this.realLLM.chatWithTools(messages, options);
+      await this.trackCacheOutcome(requestId, metadata, response);
+      const durationMs = Date.now() - startTime;
+      const usageMetrics = buildUsageAnalytics(response);
+      await this.analytics.track("llm.chatWithTools.completed", {
+        requestId,
+        tier: metadata?.tier,
+        provider: metadata?.provider,
+        model: response.model,
+        cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+        cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+        streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+        streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+        streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+        ...usageMetrics,
+        toolCallCount: response.toolCalls?.length ?? 0,
+        toolNames: response.toolCalls?.map((tc) => tc.name) ?? [],
+        durationMs
+      });
+      return response;
+    } catch (error) {
+      await this.analytics.track("llm.chatWithTools.error", {
+        requestId,
+        tier: metadata?.tier,
+        provider: metadata?.provider,
+        cacheRequestedMode: metadata?.cacheDecisionTrace?.cacheRequestedMode,
+        cacheAppliedMode: metadata?.cacheDecisionTrace?.cacheAppliedMode,
+        streamRequestedMode: metadata?.cacheDecisionTrace?.streamRequestedMode,
+        streamAppliedMode: metadata?.cacheDecisionTrace?.streamAppliedMode,
+        streamFallback: metadata?.cacheDecisionTrace?.streamFallback,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async trackCacheOutcome(requestId, metadata, response) {
+    const trace = metadata?.cacheDecisionTrace;
+    if (!trace) {
+      return;
+    }
+    const cacheReadTokens = response.usage.cacheReadTokens ?? 0;
+    const cacheWriteTokens = response.usage.cacheWriteTokens ?? 0;
+    const basePayload = {
+      requestId,
+      tier: metadata?.tier,
+      provider: metadata?.provider,
+      cacheRequestedMode: trace.cacheRequestedMode,
+      cacheAppliedMode: trace.cacheAppliedMode,
+      cacheSupported: trace.cacheSupported,
+      cacheReadTokens,
+      cacheWriteTokens,
+      promptTokens: response.usage.promptTokens,
+      completionTokens: response.usage.completionTokens,
+      model: response.model
+    };
+    if (trace.cacheAppliedMode === "bypass" || trace.cacheRequestedMode === "bypass") {
+      await this.analytics.track("llm.cache.bypass", {
+        ...basePayload,
+        reason: trace.reason ?? "CACHE_BYPASSED"
+      });
+      return;
+    }
+    if (cacheReadTokens > 0) {
+      await this.analytics.track("llm.cache.hit", basePayload);
+      return;
+    }
+    await this.analytics.track("llm.cache.miss", {
+      ...basePayload,
+      reason: trace.reason ?? "NO_CACHE_READ_TOKENS"
+    });
+  }
+};
+function generateRequestId() {
+  return `llm-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+}
+function buildUsageAnalytics(response) {
+  const model = response.model.toLowerCase();
+  const promptTokens = response.usage.promptTokens;
+  const completionTokens = response.usage.completionTokens;
+  const cacheReadTokens = response.usage.cacheReadTokens ?? 0;
+  const cacheWriteTokens = response.usage.cacheWriteTokens ?? 0;
+  const billablePromptTokens = response.usage.billablePromptTokens ?? Math.max(promptTokens - cacheReadTokens, 0);
+  const totalTokens = promptTokens + completionTokens;
+  const billableTotalTokens = billablePromptTokens + completionTokens;
+  const pricing = getPricing(model);
+  const normalInputTokens = Math.max(promptTokens - cacheReadTokens, 0);
+  const cachedInputTokens = cacheReadTokens;
+  const cachedInputRate = pricing.cachedInput ?? pricing.input;
+  const inputCost = normalInputTokens / 1e6 * pricing.input + cachedInputTokens / 1e6 * cachedInputRate;
+  const outputCost = completionTokens / 1e6 * pricing.output;
+  const estimatedCost = inputCost + outputCost;
+  const uncachedInputCost = promptTokens / 1e6 * pricing.input;
+  const uncachedOutputCost = outputCost;
+  const estimatedUncachedCost = uncachedInputCost + uncachedOutputCost;
+  const estimatedCacheSavingsUsd = Math.max(estimatedUncachedCost - estimatedCost, 0);
+  const estimatedSavedPromptTokens = Math.max(promptTokens - billablePromptTokens, 0);
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    billablePromptTokens,
+    billableTotalTokens,
+    estimatedSavedPromptTokens,
+    estimatedCost,
+    estimatedUncachedCost,
+    estimatedCacheSavingsUsd
+  };
+}
+function getPricing(model) {
+  const pricing = {
+    // OpenAI models (2025-01 pricing)
+    "gpt-4o-mini": { input: 0.15, output: 0.6, cachedInput: 0.075 },
+    "gpt-4o": { input: 2.5, output: 10, cachedInput: 1.25 },
+    "gpt-4-turbo": { input: 10, output: 30 },
+    "gpt-4": { input: 30, output: 60 },
+    "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+    // Claude models (2025-01 pricing)
+    // Cached input discounts vary by policy (5m/1h), conservative defaults:
+    // if unknown, keep cachedInput equal to input.
+    "claude-3-opus": { input: 15, output: 75 },
+    "claude-3-sonnet": { input: 3, output: 15 },
+    "claude-3-haiku": { input: 0.25, output: 1.25 }
+  };
+  const sortedKeys = Object.keys(pricing).sort((a, b) => b.length - a.length);
+  let modelPricing = pricing["gpt-4o-mini"];
+  for (const key of sortedKeys) {
+    if (model.includes(key)) {
+      modelPricing = pricing[key];
+      break;
+    }
+  }
+  return modelPricing;
+}
+
+// src/wrappers/analytics-embeddings.ts
+function generateRequestId2() {
+  return `emb_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+function estimateCost(textLength, provider = "openai") {
+  const pricing = {
+    openai: 2e-5,
+    // per 1K tokens
+    cohere: 1e-4
+    // per 1K tokens
+  };
+  const pricePerK = pricing[provider] || pricing.openai;
+  const estimatedTokens = Math.ceil(textLength / 750);
+  return estimatedTokens / 1e3 * pricePerK;
+}
+var AnalyticsEmbeddings = class {
+  constructor(realEmbeddings, analytics) {
+    this.realEmbeddings = realEmbeddings;
+    this.analytics = analytics;
+  }
+  get dimensions() {
+    return this.realEmbeddings.dimensions;
+  }
+  async getDimensions() {
+    return this.realEmbeddings.getDimensions();
+  }
+  async embed(text) {
+    const startTime = Date.now();
+    const requestId = generateRequestId2();
+    await this.analytics.track("embeddings.embed.started", {
+      requestId,
+      textLength: text.length,
+      batchSize: 1
+    });
+    try {
+      const result = await this.realEmbeddings.embed(text);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("embeddings.embed.completed", {
+        requestId,
+        textLength: text.length,
+        dimensions: result.length,
+        durationMs,
+        estimatedCost: estimateCost(text.length),
+        batchSize: 1
+      });
+      return result;
+    } catch (error) {
+      await this.analytics.track("embeddings.embed.error", {
+        requestId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async embedBatch(texts) {
+    const startTime = Date.now();
+    const requestId = generateRequestId2();
+    const totalTextLength = texts.reduce((sum, text) => sum + text.length, 0);
+    await this.analytics.track("embeddings.embedBatch.started", {
+      requestId,
+      totalTextLength,
+      batchSize: texts.length
+    });
+    try {
+      const results = await this.realEmbeddings.embedBatch(texts);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("embeddings.embedBatch.completed", {
+        requestId,
+        totalTextLength,
+        batchSize: texts.length,
+        dimensions: results[0]?.length ?? 0,
+        durationMs,
+        estimatedCost: estimateCost(totalTextLength),
+        avgTextLength: Math.round(totalTextLength / texts.length)
+      });
+      return results;
+    } catch (error) {
+      await this.analytics.track("embeddings.embedBatch.error", {
+        requestId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime,
+        batchSize: texts.length
+      });
+      throw error;
+    }
+  }
+};
+
+// src/wrappers/analytics-vector-store.ts
+function generateRequestId3() {
+  return `vec_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+var AnalyticsVectorStore = class {
+  constructor(realVectorStore, analytics) {
+    this.realVectorStore = realVectorStore;
+    this.analytics = analytics;
+  }
+  async search(query, limit, filter) {
+    const startTime = Date.now();
+    const requestId = generateRequestId3();
+    await this.analytics.track("vectorstore.search.started", {
+      requestId,
+      dimensions: query.length,
+      limit,
+      hasFilter: !!filter
+    });
+    try {
+      const results = await this.realVectorStore.search(query, limit, filter);
+      const durationMs = Date.now() - startTime;
+      const avgScore = results.length > 0 ? results.reduce((sum, r) => sum + r.score, 0) / results.length : 0;
+      await this.analytics.track("vectorstore.search.completed", {
+        requestId,
+        dimensions: query.length,
+        limit,
+        resultsCount: results.length,
+        avgScore,
+        durationMs,
+        hasFilter: !!filter
+      });
+      return results;
+    } catch (error) {
+      await this.analytics.track("vectorstore.search.error", {
+        requestId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async upsert(vectors) {
+    const startTime = Date.now();
+    const requestId = generateRequestId3();
+    await this.analytics.track("vectorstore.upsert.started", {
+      requestId,
+      vectorCount: vectors.length
+    });
+    try {
+      await this.realVectorStore.upsert(vectors);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("vectorstore.upsert.completed", {
+        requestId,
+        vectorCount: vectors.length,
+        durationMs
+      });
+    } catch (error) {
+      await this.analytics.track("vectorstore.upsert.error", {
+        requestId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime,
+        vectorCount: vectors.length
+      });
+      throw error;
+    }
+  }
+  async delete(ids) {
+    const startTime = Date.now();
+    const requestId = generateRequestId3();
+    await this.analytics.track("vectorstore.delete.started", {
+      requestId,
+      idsCount: ids.length
+    });
+    try {
+      await this.realVectorStore.delete(ids);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("vectorstore.delete.completed", {
+        requestId,
+        idsCount: ids.length,
+        durationMs
+      });
+    } catch (error) {
+      await this.analytics.track("vectorstore.delete.error", {
+        requestId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async count() {
+    const startTime = Date.now();
+    const requestId = generateRequestId3();
+    try {
+      const count = await this.realVectorStore.count();
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("vectorstore.count.completed", {
+        requestId,
+        count,
+        durationMs
+      });
+      return count;
+    } catch (error) {
+      await this.analytics.track("vectorstore.count.error", {
+        requestId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async get(ids) {
+    if (!this.realVectorStore.get) {
+      throw new Error("get() not implemented by underlying vector store");
+    }
+    const startTime = Date.now();
+    const requestId = generateRequestId3();
+    try {
+      const results = await this.realVectorStore.get(ids);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("vectorstore.get.completed", {
+        requestId,
+        idsCount: ids.length,
+        resultsCount: results.length,
+        durationMs
+      });
+      return results;
+    } catch (error) {
+      await this.analytics.track("vectorstore.get.error", {
+        requestId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async query(filter) {
+    if (!this.realVectorStore.query) {
+      throw new Error("query() not implemented by underlying vector store");
+    }
+    const startTime = Date.now();
+    const requestId = generateRequestId3();
+    try {
+      const results = await this.realVectorStore.query(filter);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("vectorstore.query.completed", {
+        requestId,
+        resultsCount: results.length,
+        durationMs
+      });
+      return results;
+    } catch (error) {
+      await this.analytics.track("vectorstore.query.error", {
+        requestId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+};
+
+// src/wrappers/analytics-cache.ts
+function generateRequestId4() {
+  return `cache_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+var cacheCounter = 0;
+function shouldSampleCacheEvent(eventType) {
+  cacheCounter = (cacheCounter + 1) % 100;
+  if (eventType === "cache.get.hit" || eventType === "cache.set.completed") {
+    return cacheCounter === 0;
+  }
+  if (eventType === "cache.get.miss") {
+    return cacheCounter % 10 === 0;
+  }
+  return true;
+}
+var AnalyticsCache = class {
+  constructor(realCache, analytics) {
+    this.realCache = realCache;
+    this.analytics = analytics;
+  }
+  async get(key) {
+    const startTime = Date.now();
+    const requestId = generateRequestId4();
+    try {
+      const result = await this.realCache.get(key);
+      const durationMs = Date.now() - startTime;
+      const hit = result !== null;
+      const eventType = hit ? "cache.get.hit" : "cache.get.miss";
+      if (shouldSampleCacheEvent(eventType)) {
+        await this.analytics.track(eventType, {
+          requestId,
+          key,
+          durationMs
+        });
+      }
+      return result;
+    } catch (error) {
+      await this.analytics.track("cache.get.error", {
+        requestId,
+        key,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async set(key, value, ttl) {
+    const startTime = Date.now();
+    const requestId = generateRequestId4();
+    try {
+      await this.realCache.set(key, value, ttl);
+      const durationMs = Date.now() - startTime;
+      if (shouldSampleCacheEvent("cache.set.completed")) {
+        await this.analytics.track("cache.set.completed", {
+          requestId,
+          key,
+          ttl: ttl ?? null,
+          durationMs
+        });
+      }
+    } catch (error) {
+      await this.analytics.track("cache.set.error", {
+        requestId,
+        key,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async delete(key) {
+    const startTime = Date.now();
+    const requestId = generateRequestId4();
+    try {
+      await this.realCache.delete(key);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("cache.delete.completed", {
+        requestId,
+        key,
+        durationMs
+      });
+    } catch (error) {
+      await this.analytics.track("cache.delete.error", {
+        requestId,
+        key,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async clear(pattern) {
+    const startTime = Date.now();
+    const requestId = generateRequestId4();
+    try {
+      await this.realCache.clear(pattern);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("cache.clear.completed", {
+        requestId,
+        pattern: pattern ?? null,
+        durationMs
+      });
+    } catch (error) {
+      await this.analytics.track("cache.clear.error", {
+        requestId,
+        pattern: pattern ?? null,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async zadd(key, score, member) {
+    const startTime = Date.now();
+    const requestId = generateRequestId4();
+    try {
+      await this.realCache.zadd(key, score, member);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("cache.zadd.completed", {
+        requestId,
+        key,
+        durationMs
+      });
+    } catch (error) {
+      await this.analytics.track("cache.zadd.error", {
+        requestId,
+        key,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async zrangebyscore(key, min, max) {
+    const startTime = Date.now();
+    const requestId = generateRequestId4();
+    try {
+      const results = await this.realCache.zrangebyscore(key, min, max);
+      const durationMs = Date.now() - startTime;
+      return results;
+    } catch (error) {
+      await this.analytics.track("cache.zrangebyscore.error", {
+        requestId,
+        key,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async zrem(key, member) {
+    const startTime = Date.now();
+    const requestId = generateRequestId4();
+    try {
+      await this.realCache.zrem(key, member);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("cache.zrem.completed", {
+        requestId,
+        key,
+        durationMs
+      });
+    } catch (error) {
+      await this.analytics.track("cache.zrem.error", {
+        requestId,
+        key,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async setIfNotExists(key, value, ttl) {
+    const startTime = Date.now();
+    const requestId = generateRequestId4();
+    try {
+      const result = await this.realCache.setIfNotExists(key, value, ttl);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("cache.setIfNotExists.completed", {
+        requestId,
+        key,
+        success: result,
+        ttl: ttl ?? null,
+        durationMs
+      });
+      return result;
+    } catch (error) {
+      await this.analytics.track("cache.setIfNotExists.error", {
+        requestId,
+        key,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+};
+
+// src/wrappers/analytics-storage.ts
+function generateRequestId5() {
+  return `storage_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+var AnalyticsStorage = class {
+  constructor(realStorage, analytics) {
+    this.realStorage = realStorage;
+    this.analytics = analytics;
+  }
+  async read(path3) {
+    const startTime = Date.now();
+    const requestId = generateRequestId5();
+    try {
+      const result = await this.realStorage.read(path3);
+      const durationMs = Date.now() - startTime;
+      const bytesRead = result?.length ?? 0;
+      await this.analytics.track("storage.read.completed", {
+        requestId,
+        path: path3,
+        bytesRead,
+        durationMs,
+        found: result !== null
+      });
+      return result;
+    } catch (error) {
+      await this.analytics.track("storage.read.error", {
+        requestId,
+        path: path3,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async write(path3, data) {
+    const startTime = Date.now();
+    const requestId = generateRequestId5();
+    try {
+      await this.realStorage.write(path3, data);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("storage.write.completed", {
+        requestId,
+        path: path3,
+        bytesWritten: data.length,
+        durationMs
+      });
+    } catch (error) {
+      await this.analytics.track("storage.write.error", {
+        requestId,
+        path: path3,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async delete(path3) {
+    const startTime = Date.now();
+    const requestId = generateRequestId5();
+    try {
+      await this.realStorage.delete(path3);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("storage.delete.completed", {
+        requestId,
+        path: path3,
+        durationMs
+      });
+    } catch (error) {
+      await this.analytics.track("storage.delete.error", {
+        requestId,
+        path: path3,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async list(prefix) {
+    const startTime = Date.now();
+    const requestId = generateRequestId5();
+    try {
+      const results = await this.realStorage.list(prefix);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("storage.list.completed", {
+        requestId,
+        prefix,
+        filesCount: results.length,
+        durationMs
+      });
+      return results;
+    } catch (error) {
+      await this.analytics.track("storage.list.error", {
+        requestId,
+        prefix,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  async exists(path3) {
+    const startTime = Date.now();
+    const requestId = generateRequestId5();
+    try {
+      const result = await this.realStorage.exists(path3);
+      const durationMs = Date.now() - startTime;
+      await this.analytics.track("storage.exists.completed", {
+        requestId,
+        path: path3,
+        exists: result,
+        durationMs
+      });
+      return result;
+    } catch (error) {
+      await this.analytics.track("storage.exists.error", {
+        requestId,
+        path: path3,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+};
+
+// src/wrappers/scoped-analytics.ts
+var ScopedAnalytics = class {
+  constructor(realAnalytics, scopedSource) {
+    this.realAnalytics = realAnalytics;
+    this.scopedSource = scopedSource;
+    if (realAnalytics.setSource) {
+      realAnalytics.setSource(scopedSource);
+    }
+  }
+  async track(event, properties) {
+    await this.realAnalytics.track(event, properties);
+  }
+  async identify(userId, traits) {
+    await this.realAnalytics.identify(userId, traits);
+  }
+  async flush() {
+    await this.realAnalytics.flush();
+  }
+  // Optional methods - delegate if available
+  async getEvents(query) {
+    if (!this.realAnalytics.getEvents) {
+      throw new Error("getEvents not supported by underlying analytics adapter");
+    }
+    return this.realAnalytics.getEvents(query);
+  }
+  async getStats() {
+    if (!this.realAnalytics.getStats) {
+      throw new Error("getStats not supported by underlying analytics adapter");
+    }
+    return this.realAnalytics.getStats();
+  }
+  async getBufferStatus() {
+    if (!this.realAnalytics.getBufferStatus) {
+      return null;
+    }
+    return this.realAnalytics.getBufferStatus();
+  }
+  async getDlqStatus() {
+    if (!this.realAnalytics.getDlqStatus) {
+      return null;
+    }
+    return this.realAnalytics.getDlqStatus();
+  }
+  /**
+   * Get current source from underlying adapter
+   */
+  getSource() {
+    if (this.realAnalytics.getSource) {
+      return this.realAnalytics.getSource();
+    }
+    return this.scopedSource;
+  }
+  /**
+   * Delegate setSource to underlying adapter
+   */
+  setSource(source) {
+    if (this.realAnalytics.setSource) {
+      this.realAnalytics.setSource(source);
+    }
+    this.scopedSource = source;
+  }
+  /**
+   * Get the scoped source (for testing/debugging)
+   */
+  getScopedSource() {
+    return this.scopedSource;
+  }
+  /**
+   * Get the underlying analytics adapter (for introspection)
+   */
+  getUnderlyingAdapter() {
+    return this.realAnalytics;
+  }
+};
+function createScopedAnalytics(analytics, scopedSource) {
+  return new ScopedAnalytics(analytics, scopedSource);
+}
+function isScopedAnalytics(analytics) {
+  return analytics instanceof ScopedAnalytics;
+}
+function unwrapScopedAnalytics(analytics) {
+  if (isScopedAnalytics(analytics)) {
+    return analytics.getUnderlyingAdapter();
+  }
+  return analytics;
+}
+
+// src/logging/prefixed-logger.ts
+var SYSTEM_LOG_FIELDS = /* @__PURE__ */ new Set([
+  // Core observability
+  "reqId",
+  "requestId",
+  "traceId",
+  "spanId",
+  "parentSpanId",
+  "invocationId",
+  "executionId",
+  "tenantId",
+  "layer",
+  // REST context
+  "method",
+  "url",
+  // Workflow context
+  "workflowId",
+  "runId",
+  "stepId",
+  "jobId",
+  "attempt",
+  // Webhook context
+  "event",
+  "source",
+  // Cron context
+  "cronId",
+  "schedule",
+  "scheduledAt",
+  "lastRunAt"
+]);
+function createPrefixedLogger(baseLogger, options = {}) {
+  const {
+    prefix = "plugin_",
+    warnOnRename = true,
+    protectedFields = SYSTEM_LOG_FIELDS
+  } = options;
+  return {
+    // Proxy all log methods (defensive check for bind)
+    trace: baseLogger.trace?.bind ? baseLogger.trace.bind(baseLogger) : baseLogger.trace,
+    debug: baseLogger.debug?.bind ? baseLogger.debug.bind(baseLogger) : baseLogger.debug,
+    info: baseLogger.info?.bind ? baseLogger.info.bind(baseLogger) : baseLogger.info,
+    warn: baseLogger.warn?.bind ? baseLogger.warn.bind(baseLogger) : baseLogger.warn,
+    error: baseLogger.error?.bind ? baseLogger.error.bind(baseLogger) : baseLogger.error,
+    fatal: baseLogger.fatal?.bind ? baseLogger.fatal.bind(baseLogger) : baseLogger.fatal,
+    // Proxy optional log buffer
+    getLogBuffer: baseLogger.getLogBuffer?.bind ? baseLogger.getLogBuffer.bind(baseLogger) : baseLogger.getLogBuffer,
+    // Wrap child() to add prefixing
+    child(fields) {
+      const prefixed = {};
+      for (const [key, value] of Object.entries(fields)) {
+        if (protectedFields.has(key)) {
+          const newKey = `${prefix}${key}`;
+          prefixed[newKey] = value;
+          if (warnOnRename && process.env.NODE_ENV !== "production") {
+            console.warn(
+              `[Logger] Field "${key}" is reserved for system observability. Renamed to "${newKey}".`
+            );
+          }
+        } else {
+          prefixed[key] = value;
+        }
+      }
+      return createPrefixedLogger(baseLogger.child(prefixed), options);
+    }
+  };
+}
+var MemoryHistoryStore = class {
+  entries = [];
+  maxEntries;
+  constructor(maxEntries = 1e4) {
+    this.maxEntries = maxEntries;
+  }
+  async save(record) {
+    this.entries.push(record);
+    if (this.entries.length > this.maxEntries) {
+      this.entries.shift();
+    }
+  }
+  async find(options) {
+    const { scopeId, queryHash, queryVector, limit = 10 } = options;
+    let results = this.entries.filter((entry) => entry.scopeId === scopeId);
+    if (queryHash) {
+      results = results.filter((entry) => entry.queryHash === queryHash);
+    }
+    if (queryVector && queryVector.length > 0) {
+      results = results.map((entry) => {
+        const similarity = entry.queryVector ? this.cosineSimilarity(queryVector, entry.queryVector) : 0;
+        return { entry, similarity };
+      }).filter((item) => item.similarity > 0.7).sort((a, b) => b.similarity - a.similarity).slice(0, limit).map((item) => item.entry);
+    } else {
+      results = results.slice(0, limit);
+    }
+    return results;
+  }
+  async popular(scopeId, limit = 20) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const entry of this.entries) {
+      if (entry.scopeId !== scopeId) {
+        continue;
+      }
+      const count = counts.get(entry.query) ?? 0;
+      counts.set(entry.query, count + 1);
+    }
+    return Array.from(counts.entries()).map(([query, count]) => ({ query, count })).sort((a, b) => b.count - a.count).slice(0, limit);
+  }
+  async saveReasoningPlan(record) {
+    const targetHash = record.queryHash ?? createHash("sha256").update(record.query.toLowerCase().trim()).digest("hex");
+    const matches = this.entries.filter((entry) => entry.scopeId === record.scopeId && entry.queryHash === targetHash);
+    if (matches.length === 0) {
+      await this.save({ ...record, queryHash: targetHash });
+      return;
+    }
+    for (const entry of matches) {
+      entry.reasoningPlan = record.reasoningPlan;
+    }
+  }
+  cosineSimilarity(vec1, vec2) {
+    if (vec1.length !== vec2.length) {
+      return 0;
+    }
+    let dot = 0;
+    let norm1 = 0;
+    let norm2 = 0;
+    for (let i = 0; i < vec1.length; i++) {
+      dot += vec1[i] * vec2[i];
+      norm1 += vec1[i] * vec1[i];
+      norm2 += vec2[i] * vec2[i];
+    }
+    const denom = Math.sqrt(norm1) * Math.sqrt(norm2);
+    return denom === 0 ? 0 : dot / denom;
+  }
+};
+
+// src/learning/memory-feedback-store.ts
+var MemoryFeedbackStore = class {
+  entries = [];
+  maxEntries;
+  constructor(maxEntries = 1e4) {
+    this.maxEntries = maxEntries;
+  }
+  async save(record) {
+    this.entries.push(record);
+    if (this.entries.length > this.maxEntries) {
+      this.entries.shift();
+    }
+  }
+  async list(scopeId, limit = 100) {
+    const scoped = this.entries.filter((entry) => entry.scopeId === scopeId);
+    return scoped.slice(-limit);
+  }
+};
+var FileHistoryStore = class {
+  constructor(storage, options = {}) {
+    this.storage = storage;
+    this.basePath = options.basePath ? this.ensureTrailingSlash(options.basePath) : ".kb/mind/learning/history/";
+    this.filePrefix = options.filePrefix ?? "history-";
+    this.maxRecordsPerFile = options.maxRecordsPerFile ?? 1e3;
+    this.maxFiles = options.maxFiles ?? 30;
+  }
+  basePath;
+  filePrefix;
+  maxRecordsPerFile;
+  maxFiles;
+  async save(record) {
+    const target = await this.getWritableFile();
+    const line = JSON.stringify({ v: 1, record }) + "\n";
+    try {
+      const existing = await this.storage.read(target);
+      const buffer = existing ? Buffer.concat([existing, Buffer.from(line, "utf8")]) : Buffer.from(line, "utf8");
+      await this.storage.write(target, buffer);
+      await this.enforceRotation();
+    } catch (error) {
+      console.error("[FileHistoryStore] Failed to write history", {
+        target,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  async find(options) {
+    const files = await this.getFilesSorted();
+    const results = [];
+    for (const file of files) {
+      if (options.limit && results.length >= options.limit) {
+        break;
+      }
+      const buf = await this.storage.read(file);
+      if (!buf) {
+        continue;
+      }
+      const lines = buf.toString("utf8").split("\n").filter(Boolean);
+      for (const line of lines) {
+        if (options.limit && results.length >= options.limit) {
+          break;
+        }
+        try {
+          const parsed = JSON.parse(line);
+          const rec = parsed.record;
+          if (rec.scopeId !== options.scopeId) {
+            continue;
+          }
+          if (options.queryHash && rec.queryHash !== options.queryHash) {
+            continue;
+          }
+          if (options.queryVector && options.queryVector.length > 0 && rec.queryVector) {
+            const similarity = this.cosineSimilarity(options.queryVector, rec.queryVector);
+            if (similarity <= 0.7) {
+              continue;
+            }
+          }
+          results.push(rec);
+        } catch {
+          continue;
+        }
+      }
+    }
+    return options.limit ? results.slice(0, options.limit) : results;
+  }
+  async popular(scopeId, limit = 20) {
+    const files = await this.getFilesSorted();
+    const counts = /* @__PURE__ */ new Map();
+    for (const file of files) {
+      const buf = await this.storage.read(file);
+      if (!buf) {
+        continue;
+      }
+      const lines = buf.toString("utf8").split("\n").filter(Boolean);
+      for (const line of lines) {
+        try {
+          const parsed = JSON.parse(line);
+          const rec = parsed.record;
+          if (rec.scopeId !== scopeId) {
+            continue;
+          }
+          counts.set(rec.query, (counts.get(rec.query) ?? 0) + 1);
+        } catch {
+          continue;
+        }
+      }
+    }
+    return Array.from(counts.entries()).map(([query, count]) => ({ query, count })).sort((a, b) => b.count - a.count).slice(0, limit);
+  }
+  async saveReasoningPlan(record) {
+    const hash = record.queryHash ?? createHash("sha256").update(record.query.toLowerCase().trim()).digest("hex");
+    await this.save({ ...record, queryHash: hash });
+  }
+  async getWritableFile() {
+    const files = await this.getFilesSorted();
+    if (files.length === 0) {
+      return this.segmentPath(Date.now());
+    }
+    const latest = files[files.length - 1];
+    const buf = await this.storage.read(latest);
+    if (!buf) {
+      return latest;
+    }
+    const count = buf.toString("utf8").split("\n").filter(Boolean).length;
+    if (count >= this.maxRecordsPerFile) {
+      return this.segmentPath(Date.now());
+    }
+    return latest;
+  }
+  async getFilesSorted() {
+    const files = await this.storage.list(this.basePath);
+    return files.filter((f) => f.startsWith(this.basePath + this.filePrefix) && f.endsWith(".jsonl")).sort();
+  }
+  segmentPath(ts) {
+    const date = new Date(ts);
+    const day = String(date.getDate()).padStart(2, "0");
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const year = date.getFullYear();
+    const filename = `${this.filePrefix}${year}${month}${day}-${ts}.jsonl`;
+    return path.posix.join(this.basePath, filename);
+  }
+  async enforceRotation() {
+    const files = await this.getFilesSorted();
+    if (files.length <= this.maxFiles) {
+      return;
+    }
+    const excess = files.length - this.maxFiles;
+    const toDelete = files.slice(0, excess);
+    await Promise.all(toDelete.map((f) => this.storage.delete(f)));
+  }
+  ensureTrailingSlash(p) {
+    return p.endsWith("/") ? p : `${p}/`;
+  }
+  cosineSimilarity(vec1, vec2) {
+    if (vec1.length !== vec2.length) {
+      return 0;
+    }
+    let dot = 0;
+    let norm1 = 0;
+    let norm2 = 0;
+    for (let i = 0; i < vec1.length; i++) {
+      dot += vec1[i] * vec2[i];
+      norm1 += vec1[i] * vec1[i];
+      norm2 += vec2[i] * vec2[i];
+    }
+    const denom = Math.sqrt(norm1) * Math.sqrt(norm2);
+    return denom === 0 ? 0 : dot / denom;
+  }
+};
+var FileFeedbackStore = class {
+  constructor(storage, options = {}) {
+    this.storage = storage;
+    this.basePath = options.basePath ? this.ensureTrailingSlash(options.basePath) : ".kb/mind/learning/feedback/";
+    this.filePrefix = options.filePrefix ?? "feedback-";
+    this.maxRecordsPerFile = options.maxRecordsPerFile ?? 1e3;
+    this.maxFiles = options.maxFiles ?? 30;
+  }
+  basePath;
+  filePrefix;
+  maxRecordsPerFile;
+  maxFiles;
+  async save(record) {
+    const target = await this.getWritableFile();
+    const line = JSON.stringify({ v: 1, record }) + "\n";
+    try {
+      const existing = await this.storage.read(target);
+      const buffer = existing ? Buffer.concat([existing, Buffer.from(line, "utf8")]) : Buffer.from(line, "utf8");
+      await this.storage.write(target, buffer);
+      await this.enforceRotation();
+    } catch (error) {
+      console.error("[FileFeedbackStore] Failed to write feedback", {
+        target,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  async list(scopeId, limit = 100) {
+    const files = await this.getFilesSorted();
+    const results = [];
+    for (const file of files) {
+      if (results.length >= limit) {
+        break;
+      }
+      const buf = await this.storage.read(file);
+      if (!buf) {
+        continue;
+      }
+      const lines = buf.toString("utf8").split("\n").filter(Boolean);
+      for (const line of lines) {
+        if (results.length >= limit) {
+          break;
+        }
+        try {
+          const parsed = JSON.parse(line);
+          const rec = parsed.record;
+          if (rec.scopeId !== scopeId) {
+            continue;
+          }
+          results.push(rec);
+        } catch {
+          continue;
+        }
+      }
+    }
+    return results.slice(-limit);
+  }
+  async getWritableFile() {
+    const files = await this.getFilesSorted();
+    if (files.length === 0) {
+      return this.segmentPath(Date.now());
+    }
+    const latest = files[files.length - 1];
+    const buf = await this.storage.read(latest);
+    if (!buf) {
+      return latest;
+    }
+    const count = buf.toString("utf8").split("\n").filter(Boolean).length;
+    if (count >= this.maxRecordsPerFile) {
+      return this.segmentPath(Date.now());
+    }
+    return latest;
+  }
+  async getFilesSorted() {
+    const files = await this.storage.list(this.basePath);
+    return files.filter((f) => f.startsWith(this.basePath + this.filePrefix) && f.endsWith(".jsonl")).sort();
+  }
+  segmentPath(ts) {
+    const date = new Date(ts);
+    const day = String(date.getDate()).padStart(2, "0");
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const year = date.getFullYear();
+    const filename = `${this.filePrefix}${year}${month}${day}-${ts}.jsonl`;
+    return path.posix.join(this.basePath, filename);
+  }
+  async enforceRotation() {
+    const files = await this.getFilesSorted();
+    if (files.length <= this.maxFiles) {
+      return;
+    }
+    const excess = files.length - this.maxFiles;
+    const toDelete = files.slice(0, excess);
+    await Promise.all(toDelete.map((f) => this.storage.delete(f)));
+  }
+  ensureTrailingSlash(p) {
+    return p.endsWith("/") ? p : `${p}/`;
+  }
+};
+
+// src/runs/run-types.ts
+var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "failed_by_review",
+  "cancelled"
+]);
+
+export { AnalyticsCache, AnalyticsEmbeddings, AnalyticsLLM, AnalyticsStorage, AnalyticsVectorStore, FileFeedbackStore, FileHistoryStore, MemoryFeedbackStore, MemoryHistoryStore, SYSTEM_LOG_FIELDS, ScopedAnalytics, TERMINAL_RUN_STATUSES, TIER_ORDER, createPrefixedLogger, createScopedAnalytics, isScopedAnalytics, isTierHigher, isTierLower, unwrapScopedAnalytics };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map