kongbrain 0.4.0 → 0.4.2

package/src/handoff-file.ts

@@ -6,7 +6,7 @@
  * so the next session's wakeup has context even before deferred
  * extraction runs.
  */
-import { readFileSync, writeFileSync, unlinkSync, existsSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, unlinkSync, existsSync, renameSync } from "node:fs";
 import { join } from "node:path";
 
 const HANDOFF_FILENAME = ".kongbrain-handoff.json";
@@ -42,14 +42,21 @@ export function readAndDeleteHandoffFile(
   workspaceDir: string,
 ): HandoffFileData | null {
   const path = join(workspaceDir, HANDOFF_FILENAME);
+  const processingPath = path + ".processing";
+  // Also clean up stale .processing files from prior crashes
+  if (existsSync(processingPath) && !existsSync(path)) {
+    try { unlinkSync(processingPath); } catch { /* ignore */ }
+  }
   if (!existsSync(path)) return null;
   try {
-    const raw = readFileSync(path, "utf-8");
-    unlinkSync(path);
+    // Atomic rename first so a crash between read and delete can't re-process
+    renameSync(path, processingPath);
+    const raw = readFileSync(processingPath, "utf-8");
+    unlinkSync(processingPath);
     const parsed = JSON.parse(raw);
     // Runtime validation — reject prototype pollution and malformed data
     if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-    if ("__proto__" in parsed || "constructor" in parsed) return null;
+    if (Object.hasOwn(parsed, "__proto__") || Object.hasOwn(parsed, "constructor")) return null;
     const data: HandoffFileData = {
       sessionId: typeof parsed.sessionId === "string" ? parsed.sessionId.slice(0, 200) : "",
       timestamp: typeof parsed.timestamp === "string" ? parsed.timestamp.slice(0, 50) : "",
@@ -61,7 +68,7 @@ export function readAndDeleteHandoffFile(
     return data;
   } catch {
     // Corrupted or deleted between check and read
-    try { unlinkSync(path); } catch { /* ignore */ }
+    try { unlinkSync(processingPath); } catch { /* ignore */ }
     return null;
   }
 }

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

@@ -54,7 +54,7 @@ export function createAfterToolCallHandler(state: GlobalPluginState) {
             });
             if (assistantTurnId) session.lastAssistantTurnId = assistantTurnId;
           } catch (e) {
-            swallow("hook:afterToolCall:eagerAssistantTurn", e);
+            swallow.warn("hook:afterToolCall:eagerAssistantTurn", e);
           }
         }
         if (session.lastAssistantTurnId) {
@@ -63,11 +63,12 @@ export function createAfterToolCallHandler(state: GlobalPluginState) {
         }
       }
     } catch (e) {
-      swallow("hook:afterToolCall:store", e);
+      swallow.warn("hook:afterToolCall:store", e);
     }
 
     // Auto-track file artifacts from write/edit tools
     if (!isError) {
+      // 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); }
@@ -147,11 +151,18 @@ async function runSessionCleanup(
     new Promise(resolve => setTimeout(resolve, 150_000)),
   ]);
 
+  // Await the graduation promise once and reuse the result below
+  let gradResult: Awaited<typeof graduationPromise> = null;
+  try {
+    gradResult = await graduationPromise;
+  } catch (e) {
+    swallow.warn("cleanup:graduationAwait", e);
+  }
+
   // If soul graduation just happened, persist a graduation event so the next
   // session can celebrate with the user. We also fire a system event for
   // immediate visibility if the session is still active.
   try {
-    const gradResult = await graduationPromise;
     if (gradResult?.graduated && gradResult.soul) {
       // Check if this is a NEW graduation (not a pre-existing soul)
       const isNewGraduation = gradResult.report.stage === "ready";
@@ -189,7 +200,6 @@ async function runSessionCleanup(
   // Soul evolution — if soul already exists, check if it should be revised
   // based on new experience (runs every 10 sessions after last revision)
   try {
-    const gradResult = await graduationPromise;
     if (gradResult?.graduated && gradResult.report.stage !== "ready") {
       // Pre-existing soul — check for evolution
       await evolveSoul(s, complete);
@@ -272,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,
@@ -361,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 } };
       };
@@ -472,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));
@@ -486,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; });
 
@@ -535,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({
@@ -553,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);
   }
@@ -192,7 +196,7 @@ export async function preflight(
 
   // Non-first-turn short inputs → continuation
   if (orch.turnIndex > 1 && input.length < 20 && !input.includes("?")) {
-    const inheritedLimit = Math.max(orch.lastConfig.toolLimit, 25);
+    const inheritedLimit = Math.min(orch.lastConfig.toolLimit, 25);
     const config: AdaptiveConfig = {
       ...orch.lastConfig, toolLimit: inheritedLimit, skipRetrieval: true,
       vectorSearchLimits: { turn: 0, identity: 0, concept: 0, memory: 0, artifact: 0 },
@@ -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()`,
@@ -207,6 +214,7 @@ export async function generateReflection(
       { record },
     );
     const reflectionId = String(rows[0]?.id ?? "");
+    store.clearReflectionCache();
 
     if (reflectionId && surrealSessionId) {
       await store.relate(reflectionId, "reflects_on", surrealSessionId).catch(e => swallow.warn("reflection:relate", e));

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

@@ -191,7 +191,7 @@ export async function getQualitySignals(store: SurrealStore): Promise<QualitySig
     const totalSuccess = Number(skillRow?.totalSuccess ?? 0);
     const totalFailure = Number(skillRow?.totalFailure ?? 0);
     const skillTotal = totalSuccess + totalFailure;
-    const skillSuccessRate = skillTotal > 0 ? totalSuccess / skillTotal : 0;
+    const skillSuccessRate = skillTotal > 0 && Number.isFinite(skillTotal) ? totalSuccess / skillTotal : 0;
 
     const critCount = Number(critRow?.count ?? 0);
     const reflCount = Number(totalRow?.count ?? 0);
@@ -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]);