kongbrain 0.4.1 → 0.4.2

package/src/hooks/after-tool-call.ts

@@ -68,7 +68,8 @@ export function createAfterToolCallHandler(state: GlobalPluginState) {
 
     // Auto-track file artifacts from write/edit tools
     if (!isError) {
-      await trackArtifact(event.toolName, event.params, session.taskId, session.projectId, state)
+      // Fire-and-forget: artifact tracking is best-effort enrichment, not critical path
+      trackArtifact(event.toolName, event.params, session.taskId, session.projectId, state)
         .catch(e => swallow.warn("hook:afterToolCall:artifact", e));
     }
 

package/src/hooks/before-tool-call.ts

@@ -10,7 +10,7 @@ import type { GlobalPluginState } from "../state.js";
 import { recordToolCall } from "../orchestrator.js";
 import { cosineSimilarity } from "../graph-context.js";
 
-const DEFAULT_TOOL_LIMIT = 10;
+const DEFAULT_TOOL_LIMIT = 9;
 const CLASSIFICATION_LIMITS: Record<string, number> = { LOOKUP: 3, EDIT: 4, REFACTOR: 8 };
 const API_CYCLE_CAP = 16;
 const RECALL_SIMILARITY_THRESHOLD = 0.80;
@@ -59,7 +59,7 @@ export function createBeforeToolCallHandler(state: GlobalPluginState) {
     }
 
     // Tool limit
-    if (session.toolCallCount > session.toolLimit) {
+    if (session.toolCallCount >= session.toolLimit) {
       return {
         block: true,
         blockReason: `Tool call limit reached (${session.toolLimit}). Stop calling tools. Continue exactly where you left off — deliver your answer from what you've gathered. Do NOT repeat anything you already said. State what's done and what remains.`,
@@ -100,22 +100,26 @@ export function createBeforeToolCallHandler(state: GlobalPluginState) {
     // Planning gate: model must output text before first tool call
     if (textLengthSoFar === 0 && toolIndex === 0) {
       const retrievalNote = session.lastRetrievalSummary
-        ? `\nContext already injected: ${session.lastRetrievalSummary}. Read <graph_context> before calling tools.`
+        ? ` Context: ${session.lastRetrievalSummary}.`
         : "";
       return {
         block: true,
         blockReason:
-          "PLANNING GATE — You must announce your plan before making tool calls.\n" +
-          "1. Classify: LOOKUP (3 calls max), EDIT (4 max), REFACTOR (8 max)\n" +
-          "2. STATE WHAT YOU ALREADY KNOW from injected memory/context — if you have prior knowledge about these files, say so" +
-          retrievalNote + "\n" +
-          "3. List each planned call and what SPECIFIC GAP it fills that memory doesn't cover\n" +
-          "4. Every step still happens, but COMBINED. Edit + test in one bash call, not two.\n" +
-          "If injected context already answers the question, you may need ZERO tool calls.\n" +
-          "Speak your plan, then proceed.",
+          "Plan before tools. Classify (LOOKUP/EDIT/REFACTOR), state what you know from <graph_context>," +
+          " list each call + what gap it fills. Combine steps. 0 calls if context answers it." +
+          retrievalNote,
       };
     }
 
+    // Inline classification: if text was emitted with a classification keyword,
+    // parse and apply the tool limit (even on first tool call after text)
+    if (toolIndex === 0 && textLengthSoFar > 0 && session.toolLimit === DEFAULT_TOOL_LIMIT) {
+      const parsed = parseClassificationFromText(session.lastAssistantText ?? "");
+      if (parsed !== null) {
+        session.toolLimit = parsed;
+      }
+    }
+
     return undefined;
   };
 }

package/src/hooks/llm-output.ts

@@ -61,16 +61,24 @@ export function createLlmOutputHandler(state: GlobalPluginState) {
       ? Math.round(deltaTokens * (reportedOutput / reportedTotal))
       : (deltaTokens > 0 ? deltaTokens : Math.ceil(textLen / 4));
 
-    // Always update session stats — turn_count must increment even without usage data
+    // Batch session stats writes — accumulate in-memory, flush every 5th response
     if (session.surrealSessionId) {
-      try {
-        await state.store.updateSessionStats(
-          session.surrealSessionId,
-          inputTokens,
-          outputTokens,
-        );
-      } catch (e) {
-        swallow("hook:llmOutput:sessionStats", e);
+      session._pendingInputTokens = (session._pendingInputTokens ?? 0) + inputTokens;
+      session._pendingOutputTokens = (session._pendingOutputTokens ?? 0) + outputTokens;
+      session._statsFlushCounter = (session._statsFlushCounter ?? 0) + 1;
+      if (session._statsFlushCounter >= 5) {
+        try {
+          await state.store.updateSessionStats(
+            session.surrealSessionId,
+            session._pendingInputTokens,
+            session._pendingOutputTokens,
+          );
+        } catch (e) {
+          swallow("hook:llmOutput:sessionStats", e);
+        }
+        session._pendingInputTokens = 0;
+        session._pendingOutputTokens = 0;
+        session._statsFlushCounter = 0;
       }
     }
 
@@ -95,7 +103,7 @@ export function createLlmOutputHandler(state: GlobalPluginState) {
     }
 
     // Capture thinking blocks for monologue extraction
-    const lastAssistant = event.lastAssistant as any;
+    const lastAssistant = event.lastAssistant as { content?: { type: string; thinking?: string; text?: string }[] } | undefined;
     if (lastAssistant?.content && Array.isArray(lastAssistant.content)) {
       for (const block of lastAssistant.content) {
         if (block.type === "thinking") {

package/src/index.ts

@@ -33,6 +33,7 @@ import { hasMigratableFiles, migrateWorkspace } from "./workspace-migrate.js";
 import { writeHandoffFileSync } from "./handoff-file.js";
 import { runDeferredCleanup } from "./deferred-cleanup.js";
 import { swallow } from "./errors.js";
+import { log } from "./log.js";
 
 // Use process-global symbols so state survives Jiti re-importing the module.
 // Jiti may load this file multiple times (fresh module scope each time),
@@ -40,17 +41,20 @@ import { swallow } from "./errors.js";
 const GLOBAL_KEY = Symbol.for("kongbrain.globalState");
 const REGISTERED_KEY = Symbol.for("kongbrain.registered");
 
+// Typed accessor for process-global symbol keys on globalThis
+const _g = globalThis as Record<symbol, unknown>;
+
 function getGlobalState(): GlobalPluginState | null {
-  return (globalThis as any)[GLOBAL_KEY] ?? null;
+  return (_g[GLOBAL_KEY] as GlobalPluginState) ?? null;
 }
 function setGlobalState(state: GlobalPluginState): void {
-  (globalThis as any)[GLOBAL_KEY] = state;
+  _g[GLOBAL_KEY] = state;
 }
 function isRegistered(): boolean {
-  return (globalThis as any)[REGISTERED_KEY] === true;
+  return _g[REGISTERED_KEY] === true;
 }
 function markRegistered(): void {
-  (globalThis as any)[REGISTERED_KEY] = true;
+  _g[REGISTERED_KEY] = true;
 }
 
 let shutdownPromise: Promise<void> | null = null;
@@ -107,7 +111,7 @@ async function runSessionCleanup(
           const turnData = recentTurns.map(t => ({
             role: t.role as "user" | "assistant",
             text: t.text,
-            turnId: (t as any).id,
+            turnId: (t as { id?: string }).id,
           }));
           session.daemon!.sendTurnBatch(turnData, [...session.pendingThinking], []);
         } catch (e) { swallow.warn("cleanup:finalDaemonFlush", e); }
@@ -278,7 +282,7 @@ async function detectGraduationEvent(
   }
 
   // Flag the session for context engine injection
-  (session as any)._graduationCelebration = {
+  session._graduationCelebration = {
     qualityScore: event.quality_score,
     volumeScore: event.volume_score,
     soulSummary,
@@ -367,12 +371,13 @@ export default definePluginEntry({
         // Pass apiKey directly in options so the provider can use it
         const response = await piAi!.completeSimple(model, context, {
           apiKey: auth.apiKey,
+          ...(params.outputFormat && { outputFormat: params.outputFormat }),
         });
         let text = "";
         let thinking: string | undefined;
         for (const block of response.content) {
           if (block.type === "text") text += block.text;
-          else if ((block as any).type === "thinking") thinking = (thinking ?? "") + (block as any).thinking;
+          else if ((block as { type: string; thinking?: string }).type === "thinking") thinking = (thinking ?? "") + (block as { type: string; thinking?: string }).thinking;
         }
         return { text, thinking, usage: { input: response.usage.input, output: response.usage.output } };
       };
@@ -478,7 +483,7 @@ export default definePluginEntry({
         hasMigratableFiles(globalState!.workspaceDir)
           .then(hasMigratable => {
             if (hasMigratable) {
-              (session as any)._hasMigratableFiles = true;
+              session._hasMigratableFiles = true;
             }
           })
           .catch(e => swallow.warn("index:migrationCheck", e));
@@ -492,7 +497,7 @@ export default definePluginEntry({
         .catch(e => swallow("index:graduationDetect", e));
 
       // Synthesize wakeup briefing — store the promise so assemble() can await it
-      (session as any)._wakeupPromise = synthesizeWakeup(
+      session._wakeupPromise = synthesizeWakeup(
         globalState!.store, globalState!.complete, session.sessionId, globalState!.workspaceDir,
       ).catch(e => { swallow.warn("index:wakeup", e); return null; });
 
@@ -541,7 +546,7 @@ export default definePluginEntry({
     const syncExitHandler = () => {
       const gs = getGlobalState();
       if (!gs?.workspaceDir) return;
-      const sessions = [...(gs as any).sessions.values()] as import("./state.js").SessionState[];
+      const sessions = gs.allSessions();
       for (const session of sessions) {
         if (session.cleanedUp) continue;
         writeHandoffFileSync({
@@ -559,14 +564,14 @@ export default definePluginEntry({
     const asyncExitHandler = () => {
       const gs = getGlobalState();
       if (!gs) return;
-      const sessions = [...(gs as any).sessions.values()] as import("./state.js").SessionState[];
+      const sessions = gs.allSessions();
       if (sessions.length === 0 && !shutdownPromise) return;
 
       const cleanups = sessions.map(s => runSessionCleanup(s, gs));
       if (shutdownPromise) cleanups.push(shutdownPromise);
 
       const done = Promise.allSettled(cleanups).then(() => {
-        gs.shutdown().catch(() => {});
+        gs.shutdown().catch(e => log.error("shutdown error:", e));
       });
 
       done.then(() => process.exit(0)).catch(() => process.exit(1));

package/src/intent.ts

@@ -92,20 +92,21 @@ async function ensurePrototypes(embeddings: EmbeddingService): Promise<{ categor
   let promise = centroidInitPromise.get(embeddings);
   if (!promise) {
     promise = (async () => {
+      const vecs = await embeddings.embedBatch(PROTOTYPES.map(p => p.text));
       const byCategory = new Map<IntentCategory, number[][]>();
-      for (const proto of PROTOTYPES) {
-        const vec = await embeddings.embed(proto.text);
-        if (!byCategory.has(proto.category)) byCategory.set(proto.category, []);
-        byCategory.get(proto.category)!.push(vec);
+      for (let i = 0; i < PROTOTYPES.length; i++) {
+        const cat = PROTOTYPES[i].category;
+        if (!byCategory.has(cat)) byCategory.set(cat, []);
+        byCategory.get(cat)!.push(vecs[i]);
       }
       const centroids: { category: IntentCategory; vec: number[] }[] = [];
-      for (const [category, vecs] of byCategory) {
-        const dim = vecs[0].length;
+      for (const [category, catVecs] of byCategory) {
+        const dim = catVecs[0].length;
         const centroid = new Array(dim).fill(0);
-        for (const v of vecs) {
+        for (const v of catVecs) {
           for (let d = 0; d < dim; d++) centroid[d] += v[d];
         }
-        for (let d = 0; d < dim; d++) centroid[d] /= vecs.length;
+        for (let d = 0; d < dim; d++) centroid[d] /= catVecs.length;
         centroids.push({ category, vec: centroid });
       }
       centroidCache.set(embeddings, centroids);

package/src/log.ts

@@ -0,0 +1,11 @@
+const LEVELS = { error: 0, warn: 1, info: 2, debug: 3 } as const;
+type Level = keyof typeof LEVELS;
+
+const currentLevel: Level = (process.env.KONGBRAIN_LOG_LEVEL as Level) ?? "warn";
+
+export const log = {
+  error: (...args: unknown[]) => { if (LEVELS[currentLevel] >= LEVELS.error) console.error("[kongbrain]", ...args); },
+  warn: (...args: unknown[]) => { if (LEVELS[currentLevel] >= LEVELS.warn) console.warn("[kongbrain]", ...args); },
+  info: (...args: unknown[]) => { if (LEVELS[currentLevel] >= LEVELS.info) console.info("[kongbrain]", ...args); },
+  debug: (...args: unknown[]) => { if (LEVELS[currentLevel] >= LEVELS.debug) console.debug("[kongbrain]", ...args); },
+};

package/src/orchestrator.ts

@@ -141,6 +141,8 @@ interface OrchestratorSessionState {
   turnIndex: number;
   currentTurnTools: { name: string; args?: string }[];
   steeringCandidates: SteeringCandidate[];
+  cachedUtilAvg: number | null;
+  utilAvgTurn: number;
 }
 
 const sessionOrchState = new WeakMap<SessionState, OrchestratorSessionState>();
@@ -153,6 +155,8 @@ function getOrchState(session: SessionState): OrchestratorSessionState {
       turnIndex: 0,
       currentTurnTools: [],
       steeringCandidates: [],
+      cachedUtilAvg: null,
+      utilAvgTurn: 0,
     };
     sessionOrchState.set(session, state);
   }
@@ -252,11 +256,14 @@ export async function preflight(
     config.toolLimit = Math.min(complexity.estimatedToolCalls, Math.ceil(config.toolLimit * 1.5), 20);
   }
 
-  // Adaptive token budget from rolling retrieval quality
+  // Adaptive token budget from rolling retrieval quality (cached, refreshed every 10 turns)
   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));
+    if (orch.cachedUtilAvg === null || orch.turnIndex - orch.utilAvgTurn >= 10) {
+      orch.cachedUtilAvg = await getRecentUtilizationAvg(session.sessionId, 10).catch(() => null);
+      orch.utilAvgTurn = orch.turnIndex;
+    }
+    if (orch.cachedUtilAvg !== null) {
+      const scale = Math.max(0.5, Math.min(1.3, 0.5 + orch.cachedUtilAvg * 0.8));
       config.tokenBudget = Math.round(config.tokenBudget * scale);
     }
   }

package/src/prefetch.ts

@@ -115,7 +115,7 @@ export async function prefetchContext(
 
   evictStale();
 
-  for (const query of queries) {
+  await Promise.all(queries.map(async (query) => {
     try {
       const queryVec = await embeddings.embed(query);
 
@@ -152,7 +152,7 @@ export async function prefetchContext(
     } catch (e) {
       swallow("prefetch:query", e);
     }
-  }
+  }));
 }
 
 // --- Cache Lookup ---

package/src/reflection.ts

@@ -143,8 +143,15 @@ export async function generateReflection(
 ): Promise<void> {
   if (!store.isAvailable()) return;
 
+  // Gate: only reflect if session metrics warrant it
+  const metrics = await gatherSessionMetrics(sessionId, store);
+  if (metrics) {
+    const { reflect } = shouldReflect(metrics);
+    if (!reflect) return;
+  }
+
   // Get session turns directly — no dependency on orchestrator_metrics
-  const turns = await store.getSessionTurns(sessionId, 30).catch(() => []);
+  const turns = await store.getSessionTurns(sessionId, 15).catch(() => []);
   if (turns.length < 3) return; // Too short for meaningful reflection
 
   const transcript = turns
@@ -183,7 +190,7 @@ export async function generateReflection(
         { vec: reflEmb },
       );
       const top = existing[0];
-      if (top && (top.score ?? 0) > 0.85) {
+      if (top && typeof top.score === "number" && top.score > 0.85) {
         const newImportance = Math.min(10, (top.importance ?? 7) + 0.5);
         await store.queryFirst<any>(
           `UPDATE $id SET importance = $imp, updated_at = time::now()`,

package/src/schema.surql

@@ -42,6 +42,7 @@ DEFINE FIELD IF NOT EXISTS embedding ON artifact TYPE option<array<float>>;
 DEFINE FIELD IF NOT EXISTS tags ON artifact TYPE option<array>;
 DEFINE FIELD IF NOT EXISTS created_at ON artifact TYPE datetime DEFAULT time::now();
 DEFINE INDEX IF NOT EXISTS artifact_vec_idx ON artifact FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS artifact_type_idx ON artifact FIELDS type;
 
 -- ============================================================
 -- PILLAR 5: Concept (semantic knowledge nodes)
@@ -78,6 +79,7 @@ DEFINE FIELD IF NOT EXISTS model ON turn TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS usage ON turn TYPE option<object>;
 DEFINE INDEX IF NOT EXISTS turn_vec_idx ON turn FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
 DEFINE INDEX IF NOT EXISTS turn_session_idx ON turn FIELDS session_id;
+DEFINE INDEX IF NOT EXISTS turn_tool_name_idx ON turn FIELDS tool_name;
 
 -- Identity chunks (agent persona / identity)
 DEFINE TABLE IF NOT EXISTS identity_chunk SCHEMALESS;
@@ -115,6 +117,7 @@ DEFINE FIELD IF NOT EXISTS status ON memory TYPE option<string> DEFAULT "active"
 DEFINE FIELD IF NOT EXISTS resolved_at ON memory TYPE option<datetime>;
 DEFINE FIELD IF NOT EXISTS resolved_by ON memory TYPE option<string>;
 DEFINE INDEX IF NOT EXISTS memory_vec_idx ON memory FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS memory_category_idx ON memory FIELDS category;
 
 -- ============================================================
 -- GRAPH EDGES: Turn-level
@@ -260,6 +263,7 @@ DEFINE FIELD IF NOT EXISTS avg_duration_ms ON skill TYPE float DEFAULT 0.0;
 DEFINE FIELD IF NOT EXISTS last_used ON skill TYPE option<datetime>;
 DEFINE FIELD IF NOT EXISTS created_at ON skill TYPE datetime DEFAULT time::now();
 DEFINE INDEX IF NOT EXISTS skill_vec_idx ON skill FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS skill_active_idx ON skill FIELDS active;
 
 DEFINE TABLE IF NOT EXISTS skill_from_task TYPE RELATION IN skill OUT task;
 DEFINE TABLE IF NOT EXISTS skill_uses_concept TYPE RELATION IN skill OUT concept;

package/src/skills.ts

@@ -16,6 +16,20 @@ import { swallow } from "./errors.js";
 import { linkToRelevantConcepts } from "./concept-extract.js";
 import { assertRecordId } from "./surreal.js";
 
+// --- Shared schema for structured output ---
+
+const skillSchema = {
+  type: "object" as const,
+  properties: {
+    name: { type: "string" },
+    description: { type: "string" },
+    preconditions: { type: "string" },
+    steps: { type: "array", items: { type: "object", properties: { tool: { type: "string" }, description: { type: "string" } } } },
+    postconditions: { type: "string" },
+  },
+  required: ["name", "description", "steps"],
+};
+
 // --- Types ---
 
 export interface SkillStep {
@@ -71,21 +85,27 @@ export async function extractSkill(
 
   try {
     const response = await complete({
-      system: `Return JSON or null. Fields: {name, description, preconditions, steps: [{tool, description}] (max 8), postconditions}. Generic patterns only (no specific paths). null if no clear multi-step workflow.`,
+      system: `Extract a reusable skill procedure. Generic patterns only (no specific paths). Return null if no clear multi-step workflow.`,
       messages: [{
         role: "user",
         content: `${turns.length} turns:\n${transcript.slice(0, 20000)}`,
       }],
+      outputFormat: { type: "json_schema", schema: skillSchema },
     });
 
     const text = response.text;
 
     if (text.trim() === "null" || text.trim() === "None") return null;
 
-    const jsonMatch = text.match(/\{[\s\S]*?\}/);
-    if (!jsonMatch) return null;
-
-    const parsed = JSON.parse(jsonMatch[0]) as ExtractedSkill;
+    // Try direct JSON.parse first (structured output), fall back to regex extraction
+    let parsed: ExtractedSkill;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      const jsonMatch = text.match(/\{[\s\S]*\}/); // greedy — handles nested objects
+      if (!jsonMatch) return null;
+      parsed = JSON.parse(jsonMatch[0]) as ExtractedSkill;
+    }
     if (!parsed.name || !parsed.description || !Array.isArray(parsed.steps) || parsed.steps.length === 0) {
       return null;
     }
@@ -290,19 +310,21 @@ export async function graduateCausalToSkills(
       if (existing.length > 0) continue;
 
       const resp = await complete({
-        system: `Return JSON: {name, description, preconditions, steps: [{tool, description}] (max 6), postconditions}. Synthesize a reusable procedure from these recurring patterns. Generic — no specific file paths or variable names.`,
+        system: `Synthesize a reusable procedure from recurring patterns. Generic — no specific file paths or variable names.`,
         messages: [{
           role: "user",
           content: `${group.cnt} successful "${group.chain_type}" patterns:\n${group.descriptions.slice(0, 8).join("\n")}`,
         }],
+        outputFormat: { type: "json_schema", schema: skillSchema },
       });
 
       const text = resp.text;
-      const jsonMatch = text.match(/\{[\s\S]*?\}/);
-      if (!jsonMatch) continue;
-
       let parsed: ExtractedSkill;
-      try { parsed = JSON.parse(jsonMatch[0]); } catch { continue; }
+      try { parsed = JSON.parse(text); } catch {
+        const jsonMatch = text.match(/\{[\s\S]*?\}/);
+        if (!jsonMatch) continue;
+        try { parsed = JSON.parse(jsonMatch[0]); } catch { continue; }
+      }
       if (!parsed.name || !Array.isArray(parsed.steps) || parsed.steps.length === 0) continue;
 
       let skillEmb: number[] | null = null;

package/src/soul.ts

@@ -551,16 +551,32 @@ Output ONLY valid JSON:
 Be honest, not aspirational. Only claim what the data supports.`;
 
   try {
+    const soulSchema = {
+      type: "object" as const,
+      properties: {
+        working_style: { type: "array", items: { type: "string" } },
+        emotional_dimensions: { type: "array", items: { type: "object" } },
+        self_observations: { type: "array", items: { type: "string" } },
+        earned_values: { type: "array", items: { type: "object" } },
+      },
+      required: ["working_style", "emotional_dimensions", "self_observations", "earned_values"],
+    };
+
     const response = await complete({
       system: "You are introspecting on your own experience to write a self-assessment. Be genuine and grounded.",
       messages: [{
         role: "user",
         content: prompt,
       }],
+      outputFormat: { type: "json_schema", schema: soulSchema },
     });
 
     const text = response.text.trim();
-    const jsonMatch = text.match(/\{[\s\S]*?\}/);
+    // With structured output, response should be valid JSON directly
+    let jsonMatch: RegExpMatchArray | null;
+    try { JSON.parse(text); jsonMatch = [text]; } catch {
+      jsonMatch = text.match(/\{[\s\S]*?\}/);
+    }
     if (!jsonMatch) return null;
 
     const parsed = JSON.parse(jsonMatch[0]);

package/src/state.ts

@@ -4,6 +4,12 @@ import type { EmbeddingService } from "./embeddings.js";
 import type { AdaptiveConfig } from "./orchestrator.js";
 import type { MemoryDaemon } from "./daemon-manager.js";
 
+/** JSON schema for structured output (forces API to return valid JSON matching schema). */
+export type OutputFormat = {
+  type: "json_schema";
+  schema: Record<string, unknown>;
+};
+
 /** Parameters for an LLM completion call. */
 export type CompleteParams = {
   system?: string;
@@ -13,6 +19,8 @@ export type CompleteParams = {
   temperature?: number;
   maxTokens?: number;
   reasoning?: "none" | "low" | "medium" | "high";
+  /** When set, API returns structured JSON matching the schema (no markdown, no preamble). */
+  outputFormat?: OutputFormat;
 };
 
 /** Result of an LLM completion call. */
@@ -32,6 +40,7 @@ export type CompleteFn = (params: CompleteParams) => Promise<CompleteResult>;
 
 const DEFAULT_TOOL_LIMIT = 10;
 
+/** Per-session mutable state: turn counters, daemon refs, 5-pillar IDs, and adaptive config. */
 export class SessionState {
   readonly sessionId: string;
   readonly sessionKey: string;
@@ -41,6 +50,8 @@ export class SessionState {
   lastAssistantTurnId = "";
   lastUserText = "";
   lastAssistantText = "";
+  /** Embedding of last user message from ingest — reused in buildContextualQueryVec to avoid re-embedding. */
+  lastUserEmbedding: number[] | null = null;
   toolCallCount = 0;
   toolLimit = DEFAULT_TOOL_LIMIT;
   turnTextLength = 0;
@@ -92,6 +103,20 @@ export class SessionState {
   taskId = "";
   surrealSessionId = "";
 
+  // Cross-concern state (set by index.ts hooks, consumed by context-engine.ts assemble)
+  /** Structured summary stashed after compaction for next assemble() injection. */
+  _compactionSummary?: string;
+  /** Promise resolving to wakeup briefing text (synthesized at session start). */
+  _wakeupPromise?: Promise<string | null>;
+  /** Graduation celebration payload for context injection. */
+  _graduationCelebration?: {
+    qualityScore: number;
+    volumeScore: number;
+    soulSummary: string;
+  };
+  /** Whether workspace has files from the default context engine that can be migrated. */
+  _hasMigratableFiles?: boolean;
+
   constructor(sessionId: string, sessionKey: string) {
     this.sessionId = sessionId;
     this.sessionKey = sessionKey;
@@ -118,6 +143,7 @@ export class SessionState {
 /** Function to enqueue a system event visible to the user. */
 export type EnqueueSystemEventFn = (text: string, options: { sessionKey: string }) => boolean;
 
+/** Singleton shared state: config, SurrealDB store, embedding service, and session map. */
 export class GlobalPluginState {
   readonly config: KongBrainConfig;
   readonly store: SurrealStore;
@@ -162,6 +188,11 @@ export class GlobalPluginState {
     this.sessions.delete(sessionKey);
   }
 
+  /** Return all active sessions (for exit handlers). */
+  allSessions(): SessionState[] {
+    return [...this.sessions.values()];
+  }
+
   /** Shut down all shared resources. */
   async shutdown(): Promise<void> {
     this.sessions.clear();