kongbrain 0.1.0

package/src/orchestrator.ts

@@ -0,0 +1,348 @@
+/**
+ * ISMAR-GENT Orchestration Layer
+ *
+ * Pre/post processing pipeline between user input and agent.prompt().
+ * Classifies intent, adapts agent configuration, records metrics.
+ * Target: <25ms for non-trivial prompts, <1ms for simple ones.
+ *
+ * Ported from kongbrain — takes EmbeddingService + SurrealStore as params
+ * instead of module-level singletons. Per-session state via SessionState.
+ */
+
+import { classifyIntent, estimateComplexity } from "./intent.js";
+import type { IntentResult, ComplexityEstimate, ThinkingLevel, IntentCategory } from "./intent.js";
+import type { EmbeddingService } from "./embeddings.js";
+import type { SurrealStore } from "./surreal.js";
+import type { SessionState } from "./state.js";
+import { getRecentUtilizationAvg } from "./retrieval-quality.js";
+import { swallow } from "./errors.js";
+
+// Detects inputs that reference memory/history
+const MEMORY_REFERENCE_RE = /\b(we|our|yesterday|earlier|before|last time|prior|remember|recall|previous|discussed|decided|talked about|worked on|you said|you mentioned)\b/i;
+
+// --- Types ---
+
+export { type ThinkingLevel, type IntentCategory } from "./intent.js";
+
+export interface AdaptiveConfig {
+  thinkingLevel: ThinkingLevel;
+  toolLimit: number;
+  tokenBudget: number;
+  retrievalShare?: number;
+  skipRetrieval?: boolean;
+  intent?: string;
+  vectorSearchLimits: {
+    turn: number;
+    identity: number;
+    concept: number;
+    memory: number;
+    artifact: number;
+  };
+}
+
+export interface PreflightResult {
+  intent: IntentResult;
+  complexity: ComplexityEstimate;
+  config: AdaptiveConfig;
+  preflightMs: number;
+  fastPath: boolean;
+}
+
+interface SteeringCandidate {
+  type: "runaway" | "budget_warning" | "scope_drift";
+  toolCall: number;
+  detail: string;
+}
+
+// --- Default config ---
+
+export const DEFAULT_ADAPTIVE_CONFIG: AdaptiveConfig = {
+  thinkingLevel: "medium",
+  toolLimit: 15,
+  tokenBudget: 6000,
+  retrievalShare: 0.15,
+  vectorSearchLimits: { turn: 25, identity: 10, concept: 20, memory: 20, artifact: 10 },
+};
+
+// --- Intent → Config mapping ---
+
+const INTENT_CONFIG: Record<IntentCategory, AdaptiveConfig> = {
+  "simple-question": {
+    thinkingLevel: "low",
+    toolLimit: 3,
+    tokenBudget: 4000,
+    retrievalShare: 0.10,
+    vectorSearchLimits: { turn: 15, identity: 5, concept: 12, memory: 12, artifact: 3 },
+  },
+  "code-read": {
+    thinkingLevel: "medium",
+    toolLimit: 5,
+    tokenBudget: 6000,
+    retrievalShare: 0.15,
+    vectorSearchLimits: { turn: 25, identity: 8, concept: 20, memory: 20, artifact: 10 },
+  },
+  "code-write": {
+    thinkingLevel: "high",
+    toolLimit: 8,
+    tokenBudget: 8000,
+    retrievalShare: 0.20,
+    vectorSearchLimits: { turn: 30, identity: 10, concept: 20, memory: 20, artifact: 15 },
+  },
+  "code-debug": {
+    thinkingLevel: "high",
+    toolLimit: 10,
+    tokenBudget: 8000,
+    retrievalShare: 0.20,
+    vectorSearchLimits: { turn: 30, identity: 8, concept: 20, memory: 25, artifact: 15 },
+  },
+  "deep-explore": {
+    thinkingLevel: "medium",
+    toolLimit: 15,
+    tokenBudget: 6000,
+    retrievalShare: 0.15,
+    vectorSearchLimits: { turn: 25, identity: 8, concept: 15, memory: 15, artifact: 8 },
+  },
+  "reference-prior": {
+    thinkingLevel: "medium",
+    toolLimit: 5,
+    tokenBudget: 10000,
+    retrievalShare: 0.25,
+    vectorSearchLimits: { turn: 40, identity: 10, concept: 25, memory: 30, artifact: 10 },
+  },
+  "meta-session": {
+    thinkingLevel: "low",
+    toolLimit: 2,
+    tokenBudget: 3000,
+    retrievalShare: 0.07,
+    skipRetrieval: false,
+    vectorSearchLimits: { turn: 8, identity: 5, concept: 5, memory: 8, artifact: 0 },
+  },
+  "multi-step": {
+    thinkingLevel: "high",
+    toolLimit: 12,
+    tokenBudget: 8000,
+    retrievalShare: 0.20,
+    vectorSearchLimits: { turn: 30, identity: 10, concept: 20, memory: 20, artifact: 15 },
+  },
+  "continuation": {
+    thinkingLevel: "low",
+    toolLimit: 8,
+    tokenBudget: 4000,
+    skipRetrieval: true,
+    vectorSearchLimits: { turn: 0, identity: 0, concept: 0, memory: 0, artifact: 0 },
+  },
+  "unknown": { ...DEFAULT_ADAPTIVE_CONFIG },
+};
+
+// --- Per-session orchestrator state ---
+
+interface OrchestratorSessionState {
+  lastConfig: AdaptiveConfig;
+  turnIndex: number;
+  currentTurnTools: { name: string; args?: string }[];
+  steeringCandidates: SteeringCandidate[];
+}
+
+const sessionOrchState = new WeakMap<SessionState, OrchestratorSessionState>();
+
+function getOrchState(session: SessionState): OrchestratorSessionState {
+  let state = sessionOrchState.get(session);
+  if (!state) {
+    state = {
+      lastConfig: { ...DEFAULT_ADAPTIVE_CONFIG },
+      turnIndex: 0,
+      currentTurnTools: [],
+      steeringCandidates: [],
+    };
+    sessionOrchState.set(session, state);
+  }
+  return state;
+}
+
+// --- Public API ---
+
+export async function preflight(
+  input: string,
+  session: SessionState,
+  embeddings: EmbeddingService,
+  retrievalBudgetTokens = 42000,
+): Promise<PreflightResult> {
+  const start = performance.now();
+  const orch = getOrchState(session);
+  orch.turnIndex++;
+  orch.currentTurnTools = [];
+  orch.steeringCandidates = [];
+
+  // Fast path: trivial first-turn inputs
+  const isTrivial = orch.turnIndex <= 1 && input.length < 20 && !input.includes("?");
+  if (isTrivial) {
+    const config: AdaptiveConfig = {
+      thinkingLevel: "low", toolLimit: 15, tokenBudget: 300, skipRetrieval: true,
+      vectorSearchLimits: { turn: 0, identity: 0, concept: 0, memory: 0, artifact: 0 },
+    };
+    orch.lastConfig = config;
+    return {
+      intent: { category: "unknown", confidence: 0, scores: [] },
+      complexity: { level: "simple", estimatedToolCalls: 0, suggestedThinking: "low" },
+      config,
+      preflightMs: performance.now() - start,
+      fastPath: true,
+    };
+  }
+
+  // Non-first-turn short inputs → continuation
+  if (orch.turnIndex > 1 && input.length < 20 && !input.includes("?")) {
+    const inheritedLimit = Math.max(orch.lastConfig.toolLimit, 25);
+    const config: AdaptiveConfig = {
+      ...orch.lastConfig, toolLimit: inheritedLimit, skipRetrieval: true,
+      vectorSearchLimits: { turn: 0, identity: 0, concept: 0, memory: 0, artifact: 0 },
+    };
+    orch.lastConfig = config;
+    return {
+      intent: { category: "continuation", confidence: 0.9, scores: [] },
+      complexity: { level: "moderate", estimatedToolCalls: 15, suggestedThinking: "medium" },
+      config,
+      preflightMs: performance.now() - start,
+      fastPath: true,
+    };
+  }
+
+  // Full classification
+  const intent = await classifyIntent(input, embeddings);
+  const complexity = estimateComplexity(input, intent);
+
+  const LOW_CONFIDENCE_CONFIG: AdaptiveConfig = {
+    thinkingLevel: "low", toolLimit: 15, tokenBudget: 3000, retrievalShare: 0.08,
+    vectorSearchLimits: { turn: 12, identity: 5, concept: 8, memory: 12, artifact: 3 },
+  };
+
+  let config: AdaptiveConfig;
+  if (intent.category === "continuation") {
+    config = { ...orch.lastConfig };
+    config.toolLimit = Math.max(config.toolLimit, 15);
+  } else if (intent.confidence < 0.40) {
+    config = { ...LOW_CONFIDENCE_CONFIG };
+  } else {
+    config = { ...(INTENT_CONFIG[intent.category] ?? DEFAULT_ADAPTIVE_CONFIG) };
+  }
+  config.intent = intent.category;
+
+  // Gate retrieval for trivial intents (unless memory-referencing)
+  if (
+    (intent.category === "simple-question" || intent.category === "meta-session") &&
+    intent.confidence >= 0.70 &&
+    !MEMORY_REFERENCE_RE.test(input)
+  ) {
+    config.skipRetrieval = true;
+    config.vectorSearchLimits = { turn: 0, identity: 0, concept: 0, memory: 0, artifact: 0 };
+  }
+
+  // Derive tokenBudget from retrieval budget
+  if (config.retrievalShare != null && config.retrievalShare > 0) {
+    config.tokenBudget = Math.round(retrievalBudgetTokens * config.retrievalShare);
+  }
+
+  // Override thinking if complexity demands it
+  if (complexity.suggestedThinking === "high" && config.thinkingLevel !== "high") {
+    config.thinkingLevel = "high";
+  }
+
+  // Override tool limit from complexity estimate (capped at 1.5x, max 20)
+  if (complexity.estimatedToolCalls > config.toolLimit) {
+    config.toolLimit = Math.min(complexity.estimatedToolCalls, Math.ceil(config.toolLimit * 1.5), 20);
+  }
+
+  // Adaptive token budget from rolling retrieval quality
+  if (!config.skipRetrieval) {
+    const recentUtil = await getRecentUtilizationAvg(session.sessionId, 10).catch(() => null);
+    if (recentUtil !== null) {
+      const scale = Math.max(0.5, Math.min(1.3, 0.5 + recentUtil * 0.8));
+      config.tokenBudget = Math.round(config.tokenBudget * scale);
+    }
+  }
+
+  orch.lastConfig = config;
+  return {
+    intent,
+    complexity,
+    config,
+    preflightMs: performance.now() - start,
+    fastPath: false,
+  };
+}
+
+/** Record a tool call for steering analysis. */
+export function recordToolCall(session: SessionState, name: string, args?: string): void {
+  const orch = getOrchState(session);
+  orch.currentTurnTools.push({ name, args });
+
+  if (orch.currentTurnTools.length >= 5) {
+    const last5 = orch.currentTurnTools.slice(-5);
+    if (last5.every((t) => t.name === last5[0].name)) {
+      orch.steeringCandidates.push({
+        type: "runaway",
+        toolCall: orch.currentTurnTools.length,
+        detail: `${last5[0].name} called 5+ times consecutively`,
+      });
+    }
+  }
+
+  const budgetWarnAt = Math.floor(orch.lastConfig.toolLimit * 0.85);
+  if (orch.lastConfig.toolLimit !== Infinity && orch.currentTurnTools.length >= budgetWarnAt) {
+    orch.steeringCandidates.push({
+      type: "budget_warning",
+      toolCall: orch.currentTurnTools.length,
+      detail: `${orch.currentTurnTools.length}/${orch.lastConfig.toolLimit} tool calls used`,
+    });
+  }
+}
+
+/** Record metrics to SurrealDB (non-blocking). */
+export async function postflight(
+  input: string,
+  result: PreflightResult,
+  actualToolCalls: number,
+  actualTokensIn: number,
+  actualTokensOut: number,
+  turnDurationMs: number,
+  session: SessionState,
+  store: SurrealStore,
+): Promise<void> {
+  const orch = getOrchState(session);
+  try {
+    if (!store.isAvailable()) return;
+    await store.queryExec(`CREATE orchestrator_metrics CONTENT $data`, {
+      data: {
+        session_id: session.sessionId,
+        turn_index: orch.turnIndex,
+        input_length: input.length,
+        intent: result.intent.category,
+        intent_confidence: result.intent.confidence,
+        complexity: result.complexity.level,
+        thinking_level: result.config.thinkingLevel,
+        tool_limit: result.config.toolLimit === Infinity ? -1 : result.config.toolLimit,
+        token_budget: result.config.tokenBudget,
+        actual_tool_calls: actualToolCalls,
+        actual_tokens_in: actualTokensIn,
+        actual_tokens_out: actualTokensOut,
+        preflight_ms: result.preflightMs,
+        turn_duration_ms: turnDurationMs,
+        steering_candidates: orch.steeringCandidates.length,
+        steering_details: orch.steeringCandidates.length > 0
+          ? orch.steeringCandidates.map((c) => `${c.type}: ${c.detail}`).join("; ")
+          : undefined,
+        fast_path: result.fastPath,
+      },
+    });
+  } catch (e) {
+    swallow("orchestrator:postflight", e);
+  }
+}
+
+export function getLastPreflightConfig(session: SessionState): AdaptiveConfig {
+  return getOrchState(session).lastConfig;
+}
+
+export function getSteeringCandidates(session: SessionState): SteeringCandidate[] {
+  return getOrchState(session).steeringCandidates;
+}

package/src/prefetch.ts

@@ -0,0 +1,200 @@
+/**
+ * Predictive Context Prefetching — Phase 7d
+ *
+ * After preflight classifies intent, predict 2-4 follow-up queries and fire
+ * vector searches in the background. Results are cached in an LRU with 5-min TTL.
+ *
+ * Ported from kongbrain — takes SurrealStore/EmbeddingService as params.
+ */
+
+import type { EmbeddingService } from "./embeddings.js";
+import type { SurrealStore, VectorSearchResult } from "./surreal.js";
+import { findRelevantSkills, type Skill } from "./skills.js";
+import { retrieveReflections, type Reflection } from "./reflection.js";
+import type { IntentCategory } from "./intent.js";
+import { swallow } from "./errors.js";
+
+// --- Types ---
+
+interface CacheEntry {
+  queryVec: number[];
+  results: VectorSearchResult[];
+  skills: Skill[];
+  reflections: Reflection[];
+  timestamp: number;
+}
+
+// --- LRU Cache ---
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const MAX_CACHE_SIZE = 10;
+const CACHE_HIT_THRESHOLD = 0.85;
+
+const warmCache = new Map<string, CacheEntry>();
+
+// --- Hit rate telemetry ---
+let _prefetchHits = 0;
+let _prefetchMisses = 0;
+
+export function recordPrefetchHit(): void { _prefetchHits++; }
+export function recordPrefetchMiss(): void { _prefetchMisses++; }
+
+export function getPrefetchHitRate(): { hits: number; misses: number; attempts: number; hitRate: number } {
+  const attempts = _prefetchHits + _prefetchMisses;
+  return { hits: _prefetchHits, misses: _prefetchMisses, attempts, hitRate: attempts > 0 ? _prefetchHits / attempts : 0 };
+}
+
+function evictStale(): void {
+  const now = Date.now();
+  for (const [key, entry] of warmCache) {
+    if (now - entry.timestamp > CACHE_TTL_MS) warmCache.delete(key);
+  }
+  while (warmCache.size > MAX_CACHE_SIZE) {
+    const oldest = warmCache.keys().next().value;
+    if (oldest) warmCache.delete(oldest);
+  }
+}
+
+// --- Query Prediction ---
+
+export function predictQueries(input: string, intent: IntentCategory): string[] {
+  const queries: string[] = [];
+
+  const filePaths = input.match(/[\w./\\-]+\.\w{1,10}/g) ?? [];
+  for (const fp of filePaths.slice(0, 2)) queries.push(fp);
+
+  const quoted = input.match(/[`"']([^`"']{3,60})[`"']/g) ?? [];
+  for (const q of quoted.slice(0, 2)) queries.push(q.replace(/[`"']/g, ""));
+
+  switch (intent) {
+    case "code-debug":
+      queries.push(`error ${extractKeyTerms(input)}`);
+      queries.push(`fix ${extractKeyTerms(input)}`);
+      break;
+    case "code-write":
+      queries.push(`implementation pattern ${extractKeyTerms(input)}`);
+      queries.push(`test ${extractKeyTerms(input)}`);
+      break;
+    case "code-read":
+      queries.push(`architecture ${extractKeyTerms(input)}`);
+      break;
+    case "multi-step":
+      queries.push(`procedure ${extractKeyTerms(input)}`);
+      queries.push(`workflow ${extractKeyTerms(input)}`);
+      break;
+    case "reference-prior":
+      queries.push(extractKeyTerms(input));
+      break;
+    default:
+      break;
+  }
+
+  return [...new Set(queries.filter((q) => q.length > 3))].slice(0, 4);
+}
+
+function extractKeyTerms(input: string): string {
+  const STOP = new Set(["the", "and", "for", "with", "from", "this", "that", "have", "will", "can", "not", "are", "was", "but"]);
+  return input.split(/\s+/)
+    .filter((w) => w.length >= 3 && !STOP.has(w.toLowerCase()))
+    .slice(0, 6)
+    .join(" ");
+}
+
+// --- Prefetching ---
+
+export async function prefetchContext(
+  queries: string[],
+  sessionId: string,
+  embeddings: EmbeddingService,
+  store: SurrealStore,
+): Promise<void> {
+  if (!embeddings.isAvailable() || !store.isAvailable()) return;
+  if (queries.length === 0) return;
+
+  evictStale();
+
+  for (const query of queries) {
+    try {
+      const queryVec = await embeddings.embed(query);
+
+      const results = await store.vectorSearch(queryVec, sessionId, {
+        turn: 5, identity: 2, concept: 3, memory: 3, artifact: 2,
+      });
+
+      const topIds = results
+        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+        .slice(0, 5)
+        .map((r) => r.id);
+
+      let neighbors: VectorSearchResult[] = [];
+      if (topIds.length > 0) {
+        try {
+          const expanded = await store.graphExpand(topIds, queryVec);
+          const existingIds = new Set(results.map((r) => r.id));
+          neighbors = expanded.filter((n) => !existingIds.has(n.id));
+        } catch (e) { swallow("prefetch:graphExpand", e); }
+      }
+
+      const [skills, reflections] = await Promise.all([
+        findRelevantSkills(queryVec, 2, store).catch(() => [] as Skill[]),
+        retrieveReflections(queryVec, 2, store).catch(() => [] as Reflection[]),
+      ]);
+
+      warmCache.set(query, {
+        queryVec,
+        results: [...results, ...neighbors],
+        skills,
+        reflections,
+        timestamp: Date.now(),
+      });
+    } catch (e) {
+      swallow("prefetch:query", e);
+    }
+  }
+}
+
+// --- Cache Lookup ---
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom > 0 ? dot / denom : 0;
+}
+
+export interface CachedContext {
+  results: VectorSearchResult[];
+  skills: Skill[];
+  reflections: Reflection[];
+}
+
+export function getCachedContext(queryVec: number[]): CachedContext | null {
+  evictStale();
+
+  let bestMatch: CacheEntry | null = null;
+  let bestSim = 0;
+
+  for (const [, entry] of warmCache) {
+    const sim = cosineSimilarity(queryVec, entry.queryVec);
+    if (sim > bestSim) { bestSim = sim; bestMatch = entry; }
+  }
+
+  if (bestMatch && bestSim >= CACHE_HIT_THRESHOLD) {
+    return { results: bestMatch.results, skills: bestMatch.skills, reflections: bestMatch.reflections };
+  }
+  return null;
+}
+
+export function getPrefetchStats(): { entries: number; maxSize: number } {
+  evictStale();
+  return { entries: warmCache.size, maxSize: MAX_CACHE_SIZE };
+}
+
+export function clearPrefetchCache(): void {
+  warmCache.clear();
+}