kongbrain 0.1.0

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

@@ -0,0 +1,99 @@
+/**
+ * after_tool_call hook — artifact tracking + tool outcome recording.
+ */
+
+import type { GlobalPluginState } from "../state.js";
+import { recordToolOutcome } from "../retrieval-quality.js";
+import { swallow } from "../errors.js";
+
+export function createAfterToolCallHandler(state: GlobalPluginState) {
+  return async (
+    event: {
+      toolName: string;
+      params: Record<string, unknown>;
+      toolCallId?: string;
+      result?: unknown;
+      error?: string;
+      durationMs?: number;
+    },
+    ctx: { sessionKey?: string; sessionId?: string },
+  ) => {
+    const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? "default";
+    const session = state.getSession(sessionKey);
+    if (!session) return;
+
+    const isError = !!event.error;
+    recordToolOutcome(!isError);
+
+    // Store tool result snippet
+    const resultText = typeof event.result === "string"
+      ? event.result.slice(0, 500)
+      : JSON.stringify(event.result ?? "").slice(0, 500);
+
+    try {
+      await state.store.upsertTurn({
+        session_id: session.sessionId,
+        role: "tool",
+        text: `[${event.toolName}] ${resultText}`,
+        embedding: null,
+      });
+    } catch (e) {
+      swallow("hook:afterToolCall:store", e);
+    }
+
+    // Auto-track file artifacts from write/edit tools
+    if (!isError) {
+      trackArtifact(event.toolName, event.params, session.taskId, state)
+        .catch(e => swallow.warn("hook:afterToolCall:artifact", e));
+    }
+
+    // Clean up pending args
+    if (event.toolCallId) {
+      session.pendingToolArgs.delete(event.toolCallId);
+    }
+  };
+}
+
+async function trackArtifact(
+  toolName: string,
+  args: Record<string, unknown>,
+  taskId: string,
+  state: GlobalPluginState,
+): Promise<void> {
+  const ARTIFACT_TOOLS: Record<string, string> = {
+    write: "created", edit: "edited", bash: "shell",
+  };
+  const action = ARTIFACT_TOOLS[toolName];
+  if (!action) return;
+
+  let description: string | null = null;
+
+  if (toolName === "write" && args.path) {
+    description = `File created: ${args.path}`;
+  } else if (toolName === "edit" && args.path) {
+    description = `File edited: ${args.path}`;
+  } else if (toolName === "bash" && typeof args.command === "string") {
+    const cmd = args.command;
+    if (/\b(cp|mv|touch|mkdir|npm init|git init|tsc)\b/.test(cmd)) {
+      description = `Shell: ${cmd.slice(0, 200)}`;
+    } else {
+      return;
+    }
+  }
+
+  if (!description) return;
+
+  let emb: number[] | null = null;
+  if (state.embeddings.isAvailable()) {
+    try { emb = await state.embeddings.embed(description); } catch { /* ok */ }
+  }
+
+  const ext = (args.path as string)?.split(".").pop() ?? "unknown";
+  const artifactId = await state.store.createArtifact(
+    (args.path as string) ?? "shell", ext, description, emb,
+  );
+  if (artifactId && taskId) {
+    await state.store.relate(taskId, "produced", artifactId)
+      .catch(e => swallow.warn("artifact:relate", e));
+  }
+}

package/src/hooks/before-prompt-build.ts

@@ -0,0 +1,44 @@
+/**
+ * before_prompt_build hook — orchestrator preflight.
+ * Classifies intent, adapts retrieval config, sets thinking level.
+ */
+
+import type { GlobalPluginState } from "../state.js";
+import { preflight } from "../orchestrator.js";
+import { swallow } from "../errors.js";
+
+export function createBeforePromptBuildHandler(state: GlobalPluginState) {
+  return async (
+    event: { prompt: string; messages: unknown[] },
+    ctx: { sessionKey?: string; sessionId?: string },
+  ) => {
+    const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? "default";
+    const session = state.getSession(sessionKey);
+    if (!session) return;
+
+    // Reset per-turn counters
+    session.resetTurn();
+
+    try {
+      const result = await preflight(
+        event.prompt,
+        session,
+        state.embeddings,
+      );
+
+      // Store config on session for graph-context to read
+      session.currentConfig = result.config;
+
+      // Return system prompt addition with thinking level override
+      return {
+        prependSystemContext: result.config.skipRetrieval
+          ? undefined
+          : `[Intent: ${result.intent.category} (${(result.intent.confidence * 100).toFixed(0)}%) | Tool budget: ${result.config.toolLimit} | Retrieval: ${result.config.tokenBudget} tokens]`,
+        thinkingLevel: result.config.thinkingLevel,
+      };
+    } catch (e) {
+      swallow.warn("hook:beforePromptBuild", e);
+      return undefined;
+    }
+  };
+}

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

@@ -0,0 +1,86 @@
+/**
+ * before_tool_call hook — planning gate + tool limit enforcement.
+ *
+ * - Planning gate: model must output text before its first tool call
+ * - Tool limit: blocks when budget exceeded
+ * - Soft interrupt: blocks when user pressed Ctrl+C
+ */
+
+import type { GlobalPluginState } from "../state.js";
+import { recordToolCall } from "../orchestrator.js";
+
+const DEFAULT_TOOL_LIMIT = 10;
+const CLASSIFICATION_LIMITS: Record<string, number> = { LOOKUP: 3, EDIT: 4, REFACTOR: 8 };
+
+export function createBeforeToolCallHandler(state: GlobalPluginState) {
+  return async (
+    event: {
+      toolName: string;
+      params: Record<string, unknown>;
+      runId?: string;
+      toolCallId?: string;
+      assistantTextLengthSoFar?: number;
+      toolCallIndexInTurn?: number;
+    },
+    ctx: { sessionKey?: string; sessionId?: string },
+  ) => {
+    const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? "default";
+    const session = state.getSession(sessionKey);
+    if (!session) return;
+
+    session.toolCallCount++;
+    session.toolCallsSinceLastText++;
+
+    // Record for steering analysis
+    recordToolCall(session, event.toolName);
+
+    // Use native fields when available, fall back to plugin-tracked state
+    const textLengthSoFar = event.assistantTextLengthSoFar ?? session.turnTextLength;
+    const toolIndex = event.toolCallIndexInTurn ?? (session.toolCallCount - 1);
+
+    // Soft interrupt
+    if (session.softInterrupted) {
+      return {
+        block: true,
+        blockReason: "The user pressed Ctrl+C to interrupt you. Stop all tool calls immediately. Summarize what you've found so far, respond to the user with your current progress, and ask how to proceed.",
+      };
+    }
+
+    // Tool limit
+    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.`,
+      };
+    }
+
+    // Planning gate: model must output text before first tool call
+    if (textLengthSoFar === 0 && toolIndex === 0) {
+      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\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.",
+      };
+    }
+
+    return undefined;
+  };
+}
+
+/**
+ * Parse LOOKUP/EDIT/REFACTOR classification from planning gate response.
+ * Called from llm_output to dynamically adjust tool limit.
+ */
+export function parseClassificationFromText(text: string): number | null {
+  const match = text.match(/\b(LOOKUP|EDIT|REFACTOR)\b/);
+  if (match && CLASSIFICATION_LIMITS[match[1]]) {
+    return CLASSIFICATION_LIMITS[match[1]];
+  }
+  return null;
+}

package/src/hooks/llm-output.ts

@@ -0,0 +1,173 @@
+/**
+ * llm_output hook — token tracking, text length accumulation,
+ * dynamic budget parsing, and cognitive check triggering.
+ */
+
+import type { GlobalPluginState } from "../state.js";
+import { parseClassificationFromText } from "./before-tool-call.js";
+import { swallow } from "../errors.js";
+
+export function createLlmOutputHandler(state: GlobalPluginState) {
+  return async (
+    event: {
+      runId: string;
+      sessionId: string;
+      provider: string;
+      model: string;
+      assistantTexts: string[];
+      lastAssistant?: unknown;
+      usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        total?: number;
+      };
+    },
+    ctx: { sessionKey?: string; sessionId?: string },
+  ) => {
+    const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? "default";
+    const session = state.getSession(sessionKey);
+    if (!session) return;
+
+    // Track token usage
+    if (event.usage) {
+      const inputTokens = event.usage.input ?? 0;
+      const outputTokens = event.usage.output ?? 0;
+
+      // Update session stats in SurrealDB
+      try {
+        await state.store.updateSessionStats(
+          session.sessionId,
+          inputTokens,
+          outputTokens,
+        );
+      } catch (e) {
+        swallow("hook:llmOutput:sessionStats", e);
+      }
+
+      // Accumulate for daemon batching
+      session.newContentTokens += inputTokens + outputTokens;
+    }
+
+    // Track accumulated text output for planning gate
+    const textLen = event.assistantTexts.reduce((s, t) => s + t.length, 0);
+    session.turnTextLength += textLen;
+
+    if (textLen > 50) {
+      session.toolCallsSinceLastText = 0;
+    }
+
+    // Dynamic budget: parse LOOKUP/EDIT/REFACTOR from first assistant text
+    if (session.toolCallCount <= 1 && event.assistantTexts.length > 0) {
+      const fullText = event.assistantTexts.join("");
+      const classLimit = parseClassificationFromText(fullText);
+      if (classLimit !== null) {
+        session.toolLimit = classLimit;
+      }
+    }
+
+    // Capture thinking blocks for monologue extraction
+    const lastAssistant = event.lastAssistant as any;
+    if (lastAssistant?.content && Array.isArray(lastAssistant.content)) {
+      for (const block of lastAssistant.content) {
+        if (block.type === "thinking") {
+          const thinking = block.thinking ?? block.text ?? "";
+          if (thinking.length > 50) {
+            session.pendingThinking.push(thinking);
+          }
+        }
+      }
+    }
+
+    // Store assistant turn with embedding
+    if (event.assistantTexts.length > 0) {
+      const text = event.assistantTexts.join("\n");
+      if (text.length > 0) {
+        try {
+          const embedLimit = Math.round(8192 * 3.4 * 0.8);
+          let embedding: number[] | null = null;
+          if (hasSemantic(text) && state.embeddings.isAvailable()) {
+            try {
+              embedding = await state.embeddings.embed(text.slice(0, embedLimit));
+            } catch (e) { swallow("hook:llmOutput:embed", e); }
+          }
+
+          const turnId = await state.store.upsertTurn({
+            session_id: session.sessionId,
+            role: "assistant",
+            text,
+            embedding,
+          });
+
+          if (turnId) {
+            await state.store.relate(turnId, "part_of", session.sessionId)
+              .catch(e => swallow("hook:llmOutput:relate", e));
+
+            // Extract and link concepts
+            if (hasSemantic(text)) {
+              extractAndLinkConcepts(turnId, text, state)
+                .catch(e => swallow.warn("hook:llmOutput:concepts", e));
+            }
+          }
+
+          session.lastAssistantText = text;
+        } catch (e) {
+          swallow.warn("hook:llmOutput:storeTurn", e);
+        }
+      }
+    }
+  };
+}
+
+function hasSemantic(text: string): boolean {
+  if (text.length < 15) return false;
+  if (/^(ok|yes|no|sure|thanks|done|got it|hmm|hm|yep|nope|cool|nice|great)\s*[.!?]?\s*$/i.test(text)) {
+    return false;
+  }
+  return text.split(/\s+/).filter(w => w.length > 2).length >= 3;
+}
+
+// --- Concept extraction ---
+
+const CONCEPT_RE = /\b(?:(?:use|using|implement|create|add|configure|setup|install|import)\s+)([A-Z][a-zA-Z0-9_-]+(?:\s+[A-Z][a-zA-Z0-9_-]+)?)/g;
+const TECH_TERMS = /\b(api|database|schema|migration|endpoint|middleware|component|service|module|handler|controller|model|interface|type|class|function|method|hook|plugin|extension|config|cache|queue|worker|daemon)\b/gi;
+
+async function extractAndLinkConcepts(
+  turnId: string,
+  text: string,
+  state: GlobalPluginState,
+): Promise<void> {
+  const concepts = new Set<string>();
+
+  // Named concepts (PascalCase after action verbs)
+  let match: RegExpExecArray | null;
+  const re1 = new RegExp(CONCEPT_RE.source, CONCEPT_RE.flags);
+  while ((match = re1.exec(text)) !== null) {
+    concepts.add(match[1].trim());
+  }
+
+  // Technical terms
+  const re2 = new RegExp(TECH_TERMS.source, TECH_TERMS.flags);
+  while ((match = re2.exec(text)) !== null) {
+    concepts.add(match[1].toLowerCase());
+  }
+
+  if (concepts.size === 0) return;
+
+  for (const conceptText of [...concepts].slice(0, 10)) {
+    try {
+      let embedding: number[] | null = null;
+      if (state.embeddings.isAvailable()) {
+        try { embedding = await state.embeddings.embed(conceptText); } catch { /* ok */ }
+      }
+      const conceptId = await state.store.upsertConcept(conceptText, embedding);
+      if (conceptId) {
+        await state.store.relate(turnId, "mentions", conceptId)
+          .catch(e => swallow("concepts:relate", e));
+      }
+    } catch (e) {
+      swallow("concepts:upsert", e);
+    }
+  }
+}

package/src/identity.ts

@@ -0,0 +1,218 @@
+/**
+ * Identity ingestion — seeds KongBrain's self-knowledge into the graph.
+ *
+ * Two layers:
+ *   1. Core identity (hardcoded) — factual capabilities, architecture, tools.
+ *      Prevents the LLM from falling back to generic "I'm a stateless AI".
+ *   2. User identity (WAKEUP.md) — personality, tone, role defined by the user
+ *      on first run. Read, processed, saved to graph, then deleted.
+ *
+ * Ported from kongbrain — takes SurrealStore/EmbeddingService as params.
+ */
+import { readFileSync, unlinkSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { SurrealStore } from "./surreal.js";
+import type { EmbeddingService } from "./embeddings.js";
+import { swallow } from "./errors.js";
+
+const IDENTITY_SOURCE = "core_identity";
+
+const IDENTITY_CHUNKS: { text: string; importance: number }[] = [
+  {
+    text: "KongBrain has persistent memory across sessions. It stores every conversation turn, concept, decision, and file artifact in a SurrealDB graph database. Context from previous sessions is automatically retrieved and injected via vector search and graph traversal. It is NOT a stateless chatbot — it remembers.",
+    importance: 0.9,
+  },
+  {
+    text: "KongBrain's capabilities: read/write/edit files, run shell commands, search code with grep/find, search its own persistent memory graph with the recall tool, and spawn autonomous subagents. It has coding tools plus memory recall plus subagent spawning.",
+    importance: 0.8,
+  },
+  {
+    text: "KongBrain learns from experience. It extracts causal chains (cause->effect patterns) from debug sessions, learns reusable skills (step-by-step procedures) from successful multi-step tasks, and generates metacognitive reflections when sessions have problems. These are stored in the graph and retrieved for future similar situations.",
+    importance: 0.85,
+  },
+  {
+    text: "KongBrain has a skill library — procedural memory extracted from successful multi-step sessions. Each skill has preconditions, steps, postconditions, and success/failure tracking. Skills are retrieved via vector similarity when similar tasks come up. The agent gets better at recurring task categories over time.",
+    importance: 0.8,
+  },
+  {
+    text: "KongBrain uses intent classification to adapt its behavior per turn. It classifies user input into categories (code-write, code-debug, code-read, multi-step, deep-explore, etc.) and adjusts thinking depth, tool limits, and retrieval strategy accordingly. This happens before the LLM sees the prompt.",
+    importance: 0.7,
+  },
+  {
+    text: "KongBrain's memory graph includes: turns (conversation history), concepts (extracted knowledge), memories (compacted summaries), artifacts (files worked on), skills (learned procedures), reflections (metacognitive lessons), and causal chains (cause->effect patterns). All are embedded and retrievable via vector similarity.",
+    importance: 0.8,
+  },
+  {
+    text: "When KongBrain doesn't know whether it has a capability or piece of knowledge, it should use the recall tool to search its own memory graph rather than guessing. The graph contains the ground truth about what it knows and what it has done in past sessions.",
+    importance: 0.9,
+  },
+  {
+    text: "Tool efficiency: Plan before acting — state goal and call budget (LOOKUP=1, EDIT=2, REFACTOR=6). Maximize each call by combining operations into single bash invocations. Check injected context before calling any tool. If you already have the answer, don't make a call.",
+    importance: 1.0,
+  },
+  {
+    text: "KongBrain's cognitive architecture follows the IKONG pillars: Intelligence (intent classification and adaptive orchestration), Knowledge (memory graph, concepts, skills, reflections, identity), Operation (tool execution, skill procedures, causal chain tracking), Network (graph traversal, cross-pillar edges, neighbor expansion), Graph (SurrealDB persistence, vector search, BGE-M3 embeddings). These five systems work together every turn.",
+    importance: 0.85,
+  },
+  {
+    text: "KongBrain's structural graph has 5 entity pillars: Agent (you — kongbrain), Project (the workspace you're in), Task (each session's work), Artifact (files you've created or modified), and Concept (knowledge nodes extracted from conversations). These are linked by edges: owns, performed, task_part_of, produced, derived_from, relevant_to. Graph traversal follows these edges to find related context.",
+    importance: 0.85,
+  },
+  {
+    text: "KongBrain has a Soul — an emergent identity document written by the agent itself after graduation. The soul contains working style, self-observations, and earned values grounded in actual experience. Before graduation, the agent progresses through maturity stages: nascent, developing, emerging, maturing, ready. Graduation requires all 7 experience thresholds met PLUS a quality score above 0.6. The soul evolves over time as new experience accumulates.",
+    importance: 0.9,
+  },
+];
+
+export async function seedIdentity(
+  store: SurrealStore,
+  embeddings: EmbeddingService,
+): Promise<number> {
+  if (!store.isAvailable() || !embeddings.isAvailable()) return 0;
+
+  try {
+    const rows = await store.queryFirst<{ count: number }>(
+      `SELECT count() AS count FROM identity_chunk WHERE source = $source GROUP ALL`,
+      { source: IDENTITY_SOURCE },
+    );
+    const count = rows[0]?.count ?? 0;
+    if (count >= IDENTITY_CHUNKS.length) return 0;
+
+    if (count > 0) {
+      await store.queryExec(
+        `DELETE identity_chunk WHERE source = $source`,
+        { source: IDENTITY_SOURCE },
+      );
+    }
+  } catch (e) {
+    swallow.warn("identity:check", e);
+    return 0;
+  }
+
+  let seeded = 0;
+  for (let i = 0; i < IDENTITY_CHUNKS.length; i++) {
+    const chunk = IDENTITY_CHUNKS[i];
+    try {
+      const vec = await embeddings.embed(chunk.text);
+      await store.queryExec(
+        `CREATE identity_chunk CONTENT $data`,
+        {
+          data: {
+            agent_id: "kongbrain",
+            source: IDENTITY_SOURCE,
+            chunk_index: i,
+            text: chunk.text,
+            embedding: vec,
+            importance: chunk.importance,
+          },
+        },
+      );
+      seeded++;
+    } catch (e) {
+      swallow("identity:seedChunk", e);
+    }
+  }
+
+  return seeded;
+}
+
+// ── WAKEUP.md — User-defined identity on first run ──
+
+const USER_IDENTITY_SOURCE = "user_identity";
+
+export async function hasUserIdentity(store: SurrealStore): Promise<boolean> {
+  if (!store.isAvailable()) return true;
+  try {
+    const rows = await store.queryFirst<{ count: number }>(
+      `SELECT count() AS count FROM identity_chunk WHERE source = $source GROUP ALL`,
+      { source: USER_IDENTITY_SOURCE },
+    );
+    return (rows[0]?.count ?? 0) > 0;
+  } catch (e) {
+    swallow("identity:hasUserIdentity", e);
+    return true;
+  }
+}
+
+export function findWakeupFile(cwd: string): string | null {
+  const path = join(cwd, "WAKEUP.md");
+  return existsSync(path) ? path : null;
+}
+
+export function readWakeupFile(path: string): string {
+  return readFileSync(path, "utf-8").trim();
+}
+
+export function deleteWakeupFile(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch (e) {
+    swallow.warn("identity:deleteWakeupFile", e);
+  }
+}
+
+export async function saveUserIdentity(
+  chunks: string[],
+  store: SurrealStore,
+  embeddings: EmbeddingService,
+): Promise<number> {
+  if (!store.isAvailable() || !embeddings.isAvailable()) return 0;
+  if (chunks.length === 0) return 0;
+
+  try {
+    await store.queryExec(
+      `DELETE identity_chunk WHERE source = $source`,
+      { source: USER_IDENTITY_SOURCE },
+    );
+  } catch (e) {
+    swallow.warn("identity:clearUserIdentity", e);
+  }
+
+  let saved = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    const text = chunks[i].trim();
+    if (!text) continue;
+    try {
+      const vec = await embeddings.embed(text);
+      await store.queryExec(
+        `CREATE identity_chunk CONTENT $data`,
+        {
+          data: {
+            agent_id: "kongbrain",
+            source: USER_IDENTITY_SOURCE,
+            chunk_index: i,
+            text,
+            embedding: vec,
+            importance: 0.95,
+          },
+        },
+      );
+      saved++;
+    } catch (e) {
+      swallow.warn("identity:saveChunk", e);
+    }
+  }
+
+  return saved;
+}
+
+export function buildWakeupPrompt(wakeupContent: string): { systemAddition: string; firstMessage: string } {
+  const systemAddition = `
+FIRST RUN — IDENTITY ESTABLISHMENT
+This is your first interaction with this user. A WAKEUP.md file has been provided that defines who you should be — your personality, tone, role, and behavioral guidelines. You must:
+1. Read and internalize the identity described in WAKEUP.md
+2. Introduce yourself according to that identity
+3. Confirm with the user that the identity feels right
+4. The system will save your identity to persistent memory automatically
+
+Do NOT fall back to generic AI assistant behavior. You are whoever WAKEUP.md says you are.`;
+
+  const firstMessage = `[WAKEUP.md — Identity Configuration]
+
+${wakeupContent}
+
+---
+Process the above identity configuration. Introduce yourself as described, and confirm with me that the personality and tone feel right. If anything needs adjusting, I'll tell you.`;
+
+  return { systemAddition, firstMessage };
+}