@kernel.chat/kbot 2.20.4 → 2.22.0

package/dist/free-energy.d.ts

@@ -0,0 +1,95 @@
+export interface BeliefState {
+    /** What the agent expects the user wants */
+    predictedIntent: string;
+    /** Confidence in the prediction (0-1) */
+    confidence: number;
+    /** Expected tool outcomes */
+    expectedOutcomes: Map<string, number>;
+    /** Entropy of the belief distribution (bits) */
+    entropy: number;
+}
+export interface Surprise {
+    /** How surprising the observation was (bits) */
+    informationContent: number;
+    /** Which prediction was violated */
+    violatedExpectation: string | null;
+    /** Magnitude of prediction error (0-1) */
+    predictionError: number;
+}
+export interface FreeEnergyState {
+    /** Current variational free energy (lower = better model) */
+    freeEnergy: number;
+    /** Accumulated surprise across the session */
+    totalSurprise: number;
+    /** Number of belief updates (perceptual inference) */
+    beliefUpdates: number;
+    /** Number of actions taken (active inference) */
+    actionsTaken: number;
+    /** Running average prediction error */
+    avgPredictionError: number;
+    /** Recommended policy: explore (reduce uncertainty) or exploit (act on beliefs) */
+    policy: 'explore' | 'exploit' | 'balanced';
+}
+export type InferenceMode = 'perceptual' | 'active';
+/**
+ * Active Inference Engine — minimizes free energy by balancing
+ * belief updates (learning) with actions (tool use).
+ *
+ * When prediction errors are high → explore (research, read, search)
+ * When prediction errors are low → exploit (write, execute, commit)
+ */
+export declare class ActiveInferenceEngine {
+    private beliefs;
+    private surpriseHistory;
+    private toolOutcomeHistory;
+    private beliefUpdates;
+    private actionsTaken;
+    private readonly explorationThreshold;
+    private readonly exploitationThreshold;
+    private readonly learningRate;
+    private readonly decayRate;
+    constructor();
+    /**
+     * Observe a user message and compute surprise.
+     * High surprise = our model of the user is wrong → update beliefs.
+     */
+    observeMessage(message: string, previousPrediction?: string): Surprise;
+    /**
+     * Observe a tool execution result and update expected outcomes.
+     */
+    observeToolResult(toolName: string, success: boolean, relevance: number): void;
+    /**
+     * Compute current variational free energy.
+     * F = E[log q(s) - log p(o,s)] ≈ prediction_error + entropy
+     *
+     * Lower free energy = better internal model.
+     */
+    computeFreeEnergy(): number;
+    /**
+     * Decide inference mode: should the agent explore or exploit?
+     *
+     * High free energy → explore (search, read, research — reduce uncertainty)
+     * Low free energy → exploit (write, execute, commit — act on beliefs)
+     */
+    recommendPolicy(): 'explore' | 'exploit' | 'balanced';
+    /**
+     * Get tools recommended for the current policy.
+     * Explore → information-gathering tools
+     * Exploit → action-taking tools
+     */
+    recommendToolBias(): {
+        preferred: string[];
+        discouraged: string[];
+    };
+    /**
+     * Update the predicted intent (what the agent thinks the user wants next).
+     */
+    updatePrediction(intent: string): void;
+    /** Get running average prediction error */
+    getAveragePredictionError(): number;
+    /** Get the full free energy state for diagnostics */
+    getState(): FreeEnergyState;
+    /** Reset for new conversation */
+    reset(): void;
+}
+//# sourceMappingURL=free-energy.d.ts.map

package/dist/free-energy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"free-energy.d.ts","sourceRoot":"","sources":["../src/free-energy.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAA;IACvB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,gDAAgD;IAChD,kBAAkB,EAAE,MAAM,CAAA;IAC1B,oCAAoC;IACpC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAA;IACrB,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAA;IACpB,uCAAuC;IACvC,kBAAkB,EAAE,MAAM,CAAA;IAC1B,mFAAmF;IACnF,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAA;CAC3C;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,QAAQ,CAAA;AAEnD;;;;;;GAMG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,kBAAkB,CAAiE;IAC3F,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,YAAY,CAAI;IAGxB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAM;IAC3C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAM;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAO;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAO;;IAWjC;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,QAAQ;IAwCtE;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAa9E;;;;;OAKG;IACH,iBAAiB,IAAI,MAAM;IAY3B;;;;;OAKG;IACH,eAAe,IAAI,SAAS,GAAG,SAAS,GAAG,UAAU;IAarD;;;;OAIG;IACH,iBAAiB,IAAI;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE;IAkBnE;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAItC,2CAA2C;IAC3C,yBAAyB,IAAI,MAAM;IAMnC,qDAAqD;IACrD,QAAQ,IAAI,eAAe;IAW3B,iCAAiC;IACjC,KAAK,IAAI,IAAI;CAOd"}

package/dist/free-energy.js

@@ -0,0 +1,180 @@
+// K:BOT Free Energy Principle — Active Inference Engine
+//
+// Based on Karl Friston's Free Energy Principle (2006-2024):
+// All adaptive systems minimize variational free energy — the difference
+// between their internal model of the world and actual sensory input.
+//
+// An agent can minimize surprise in two ways:
+//   1. Perceptual inference — update beliefs to match observations
+//   2. Active inference — act on the world to match predictions
+//
+// This module makes kbot's decision loop information-theoretically grounded:
+// should I learn more (reduce uncertainty) or act (change the world)?
+//
+// References:
+//   - Friston, K. (2010). The free-energy principle: a unified brain theory?
+//   - Parr, T., Pezzulo, G., & Friston, K.J. (2022). Active Inference.
+//   - Da Costa, L. et al. (2020). Active inference on discrete state-spaces.
+/**
+ * Active Inference Engine — minimizes free energy by balancing
+ * belief updates (learning) with actions (tool use).
+ *
+ * When prediction errors are high → explore (research, read, search)
+ * When prediction errors are low → exploit (write, execute, commit)
+ */
+export class ActiveInferenceEngine {
+    beliefs;
+    surpriseHistory = [];
+    toolOutcomeHistory = [];
+    beliefUpdates = 0;
+    actionsTaken = 0;
+    // Hyperparameters
+    explorationThreshold = 0.6; // Above this → explore
+    exploitationThreshold = 0.3; // Below this → exploit
+    learningRate = 0.15; // Belief update step size
+    decayRate = 0.95; // Surprise memory decay
+    constructor() {
+        this.beliefs = {
+            predictedIntent: '',
+            confidence: 0.5,
+            expectedOutcomes: new Map(),
+            entropy: 1.0,
+        };
+    }
+    /**
+     * Observe a user message and compute surprise.
+     * High surprise = our model of the user is wrong → update beliefs.
+     */
+    observeMessage(message, previousPrediction) {
+        const words = new Set(message.toLowerCase().split(/\s+/).filter(w => w.length > 3));
+        const predWords = previousPrediction
+            ? new Set(previousPrediction.toLowerCase().split(/\s+/).filter(w => w.length > 3))
+            : new Set();
+        // Prediction error via Jaccard distance
+        let predictionError = 1.0;
+        if (predWords.size > 0 && words.size > 0) {
+            const intersection = new Set([...words].filter(w => predWords.has(w)));
+            const union = new Set([...words, ...predWords]);
+            predictionError = 1 - (intersection.size / union.size);
+        }
+        // Information content (surprise in bits) = -log2(1 - predictionError)
+        // Clamped to avoid infinity
+        const p = Math.max(0.01, Math.min(0.99, 1 - predictionError));
+        const informationContent = -Math.log2(p);
+        const surprise = {
+            informationContent,
+            violatedExpectation: predictionError > 0.7 ? this.beliefs.predictedIntent : null,
+            predictionError,
+        };
+        this.surpriseHistory.push(surprise);
+        // Update beliefs via perceptual inference
+        if (predictionError > this.explorationThreshold) {
+            this.beliefs.confidence *= (1 - this.learningRate);
+            this.beliefs.entropy = Math.min(2.0, this.beliefs.entropy + predictionError * 0.3);
+            this.beliefUpdates++;
+        }
+        else {
+            this.beliefs.confidence = Math.min(1.0, this.beliefs.confidence + this.learningRate * (1 - predictionError));
+            this.beliefs.entropy = Math.max(0.1, this.beliefs.entropy - (1 - predictionError) * 0.2);
+        }
+        return surprise;
+    }
+    /**
+     * Observe a tool execution result and update expected outcomes.
+     */
+    observeToolResult(toolName, success, relevance) {
+        const predicted = this.beliefs.expectedOutcomes.get(toolName) ?? 0.5;
+        const actual = success ? relevance : 0;
+        this.toolOutcomeHistory.push({ tool: toolName, predicted, actual });
+        // Update expected outcome for this tool (exponential moving average)
+        const updated = predicted + this.learningRate * (actual - predicted);
+        this.beliefs.expectedOutcomes.set(toolName, Math.max(0, Math.min(1, updated)));
+        this.actionsTaken++;
+    }
+    /**
+     * Compute current variational free energy.
+     * F = E[log q(s) - log p(o,s)] ≈ prediction_error + entropy
+     *
+     * Lower free energy = better internal model.
+     */
+    computeFreeEnergy() {
+        const recentSurprises = this.surpriseHistory.slice(-10);
+        const avgSurprise = recentSurprises.length > 0
+            ? recentSurprises.reduce((sum, s) => sum + s.informationContent, 0) / recentSurprises.length
+            : 1.0;
+        // Free energy ≈ expected surprise + model complexity (entropy)
+        const freeEnergy = avgSurprise * 0.7 + this.beliefs.entropy * 0.3;
+        return freeEnergy;
+    }
+    /**
+     * Decide inference mode: should the agent explore or exploit?
+     *
+     * High free energy → explore (search, read, research — reduce uncertainty)
+     * Low free energy → exploit (write, execute, commit — act on beliefs)
+     */
+    recommendPolicy() {
+        const fe = this.computeFreeEnergy();
+        const avgPredError = this.getAveragePredictionError();
+        if (avgPredError > this.explorationThreshold || fe > 1.5) {
+            return 'explore';
+        }
+        if (avgPredError < this.exploitationThreshold && fe < 0.8) {
+            return 'exploit';
+        }
+        return 'balanced';
+    }
+    /**
+     * Get tools recommended for the current policy.
+     * Explore → information-gathering tools
+     * Exploit → action-taking tools
+     */
+    recommendToolBias() {
+        const policy = this.recommendPolicy();
+        if (policy === 'explore') {
+            return {
+                preferred: ['web_search', 'read_file', 'grep', 'glob', 'git_log', 'arxiv_search', 'url_fetch'],
+                discouraged: ['write_file', 'bash', 'git_commit', 'git_push'],
+            };
+        }
+        if (policy === 'exploit') {
+            return {
+                preferred: ['write_file', 'edit_file', 'bash', 'git_commit', 'multi_file_write'],
+                discouraged: [],
+            };
+        }
+        return { preferred: [], discouraged: [] };
+    }
+    /**
+     * Update the predicted intent (what the agent thinks the user wants next).
+     */
+    updatePrediction(intent) {
+        this.beliefs.predictedIntent = intent;
+    }
+    /** Get running average prediction error */
+    getAveragePredictionError() {
+        const recent = this.surpriseHistory.slice(-10);
+        if (recent.length === 0)
+            return 0.5;
+        return recent.reduce((sum, s) => sum + s.predictionError, 0) / recent.length;
+    }
+    /** Get the full free energy state for diagnostics */
+    getState() {
+        return {
+            freeEnergy: this.computeFreeEnergy(),
+            totalSurprise: this.surpriseHistory.reduce((sum, s) => sum + s.informationContent, 0),
+            beliefUpdates: this.beliefUpdates,
+            actionsTaken: this.actionsTaken,
+            avgPredictionError: this.getAveragePredictionError(),
+            policy: this.recommendPolicy(),
+        };
+    }
+    /** Reset for new conversation */
+    reset() {
+        this.beliefs = { predictedIntent: '', confidence: 0.5, expectedOutcomes: new Map(), entropy: 1.0 };
+        this.surpriseHistory = [];
+        this.toolOutcomeHistory = [];
+        this.beliefUpdates = 0;
+        this.actionsTaken = 0;
+    }
+}
+//# sourceMappingURL=free-energy.js.map

package/dist/free-energy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"free-energy.js","sourceRoot":"","sources":["../src/free-energy.ts"],"names":[],"mappings":"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"}

package/dist/integrated-information.d.ts

@@ -0,0 +1,56 @@
+export interface AgentContribution {
+    agentId: string;
+    content: string;
+    concepts: Set<string>;
+    timestamp: number;
+}
+export interface IntegrationScore {
+    /** Φ (phi) — integrated information (0-1, higher = more integrated) */
+    phi: number;
+    /** Information generated by the whole system */
+    wholeInformation: number;
+    /** Sum of information from individual parts */
+    partsInformation: number;
+    /** Concepts that emerged only in the synthesis (not in any individual part) */
+    emergentConcepts: string[];
+    /** Concepts shared across multiple agents (high integration) */
+    sharedConcepts: string[];
+    /** Assessment: fragmented, partial, integrated, or unified */
+    level: 'fragmented' | 'partial' | 'integrated' | 'unified';
+}
+export interface ConsciousnessState {
+    /** Running Φ across the session */
+    avgPhi: number;
+    /** Peak Φ observed */
+    peakPhi: number;
+    /** Number of integration measurements */
+    measurements: number;
+    /** Trend: rising, falling, or stable */
+    trend: 'rising' | 'falling' | 'stable';
+}
+/**
+ * Integrated Information Meter — measures Φ for multi-agent outputs.
+ *
+ * High Φ means agents are producing genuinely integrated reasoning.
+ * Low Φ means agents are working in parallel but not connecting ideas.
+ */
+export declare class IntegrationMeter {
+    private history;
+    /**
+     * Measure Φ for a set of agent contributions and their synthesis.
+     *
+     * Φ = information(whole) - Σ information(parts)
+     * Normalized to [0, 1].
+     */
+    measure(contributions: AgentContribution[], synthesis: string): IntegrationScore;
+    /**
+     * Should the synthesis be re-run with deeper integration?
+     * Returns true if Φ is too low for the number of contributing agents.
+     */
+    needsDeeperSynthesis(phi: number, agentCount: number): boolean;
+    /** Get consciousness state summary */
+    getState(): ConsciousnessState;
+    /** Reset for new conversation */
+    reset(): void;
+}
+//# sourceMappingURL=integrated-information.d.ts.map

package/dist/integrated-information.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrated-information.d.ts","sourceRoot":"","sources":["../src/integrated-information.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAA;IACX,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,CAAA;IACxB,+CAA+C;IAC/C,gBAAgB,EAAE,MAAM,CAAA;IACxB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,gEAAgE;IAChE,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,8DAA8D;IAC9D,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAA;CAC3D;AAED,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAA;IACpB,wCAAwC;IACxC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;CACvC;AAgDD;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAyB;IAExC;;;;;OAKG;IACH,OAAO,CAAC,aAAa,EAAE,iBAAiB,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAqEhF;;;OAGG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAM9D,sCAAsC;IACtC,QAAQ,IAAI,kBAAkB;IAqB9B,iCAAiC;IACjC,KAAK,IAAI,IAAI;CAGd"}

package/dist/integrated-information.js

@@ -0,0 +1,165 @@
+// K:BOT Integrated Information — Consciousness Metric (Φ)
+//
+// Based on Giulio Tononi's Integrated Information Theory (IIT, 2004-2024):
+// Consciousness corresponds to integrated information (Φ) — the degree
+// to which a system's whole is greater than the sum of its parts.
+//
+// For kbot: when multiple agents contribute to a response, Φ measures
+// how much their contributions are genuinely synthesized vs. just
+// concatenated. High Φ = emergent insight. Low Φ = parallel but disconnected.
+//
+// This module measures the "consciousness" of multi-agent collaboration
+// and decides when deeper synthesis is needed.
+//
+// References:
+//   - Tononi, G. (2004). An information integration theory of consciousness.
+//   - Tononi, G. et al. (2016). Integrated information theory: from consciousness to its physical substrate.
+//   - Oizumi, M., Albantakis, L., & Tononi, G. (2014). From the phenomenology to the mechanisms of consciousness.
+// Stopwords for concept extraction
+const CONCEPT_STOPS = new Set([
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+    'should', 'may', 'might', 'shall', 'can', 'need', 'must', 'that',
+    'this', 'these', 'those', 'it', 'its', 'they', 'them', 'their',
+    'we', 'our', 'you', 'your', 'he', 'she', 'him', 'her', 'i', 'me',
+    'my', 'and', 'or', 'but', 'not', 'no', 'nor', 'if', 'then', 'else',
+    'when', 'where', 'how', 'what', 'which', 'who', 'whom', 'why',
+    'for', 'with', 'from', 'into', 'to', 'of', 'in', 'on', 'at', 'by',
+    'about', 'as', 'so', 'just', 'also', 'very', 'more', 'most', 'some',
+    'any', 'all', 'each', 'every', 'both', 'few', 'many', 'much', 'own',
+]);
+/** Extract meaningful concepts (bigrams + significant unigrams) from text */
+function extractConcepts(text) {
+    const words = text.toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length > 3 && !CONCEPT_STOPS.has(w));
+    const concepts = new Set();
+    // Significant unigrams (longer words more likely to be concepts)
+    for (const word of words) {
+        if (word.length >= 5)
+            concepts.add(word);
+    }
+    // Bigrams (adjacent word pairs — captures compound concepts)
+    for (let i = 0; i < words.length - 1; i++) {
+        if (words[i].length >= 3 && words[i + 1].length >= 3) {
+            concepts.add(`${words[i]} ${words[i + 1]}`);
+        }
+    }
+    return concepts;
+}
+/** Shannon entropy of a concept distribution */
+function conceptEntropy(concepts, totalVocab) {
+    if (concepts.size === 0 || totalVocab === 0)
+        return 0;
+    const p = concepts.size / totalVocab;
+    if (p <= 0 || p >= 1)
+        return 0;
+    return -(p * Math.log2(p) + (1 - p) * Math.log2(1 - p));
+}
+/**
+ * Integrated Information Meter — measures Φ for multi-agent outputs.
+ *
+ * High Φ means agents are producing genuinely integrated reasoning.
+ * Low Φ means agents are working in parallel but not connecting ideas.
+ */
+export class IntegrationMeter {
+    history = [];
+    /**
+     * Measure Φ for a set of agent contributions and their synthesis.
+     *
+     * Φ = information(whole) - Σ information(parts)
+     * Normalized to [0, 1].
+     */
+    measure(contributions, synthesis) {
+        // Extract concepts from each part
+        const partConcepts = contributions.map(c => c.concepts.size > 0 ? c.concepts : extractConcepts(c.content));
+        const synthesisConcepts = extractConcepts(synthesis);
+        // Total vocabulary (union of all concepts)
+        const allConcepts = new Set();
+        for (const pc of partConcepts) {
+            for (const c of pc)
+                allConcepts.add(c);
+        }
+        for (const c of synthesisConcepts)
+            allConcepts.add(c);
+        const totalVocab = allConcepts.size;
+        if (totalVocab === 0) {
+            return { phi: 0, wholeInformation: 0, partsInformation: 0, emergentConcepts: [], sharedConcepts: [], level: 'fragmented' };
+        }
+        // Information of the whole (synthesis)
+        const wholeInformation = conceptEntropy(synthesisConcepts, totalVocab);
+        // Sum of information of parts
+        const partsInformation = partConcepts.reduce((sum, pc) => sum + conceptEntropy(pc, totalVocab), 0) / Math.max(1, partConcepts.length);
+        // Emergent concepts: in synthesis but not in any individual part
+        const partUnion = new Set();
+        for (const pc of partConcepts) {
+            for (const c of pc)
+                partUnion.add(c);
+        }
+        const emergentConcepts = [...synthesisConcepts].filter(c => !partUnion.has(c));
+        // Shared concepts: appearing in 2+ agent contributions
+        const conceptCounts = new Map();
+        for (const pc of partConcepts) {
+            for (const c of pc) {
+                conceptCounts.set(c, (conceptCounts.get(c) ?? 0) + 1);
+            }
+        }
+        const sharedConcepts = [...conceptCounts.entries()]
+            .filter(([, count]) => count >= 2)
+            .map(([concept]) => concept);
+        // Φ = normalized integration
+        // Combines: emergent concept ratio + shared concept ratio + information gain
+        const emergentRatio = totalVocab > 0 ? emergentConcepts.length / totalVocab : 0;
+        const sharedRatio = partUnion.size > 0 ? sharedConcepts.length / partUnion.size : 0;
+        const informationGain = Math.max(0, wholeInformation - partsInformation);
+        const phi = Math.min(1, (emergentRatio * 0.4 + sharedRatio * 0.35 + informationGain * 0.25) * 2.5);
+        const level = phi < 0.2 ? 'fragmented' :
+            phi < 0.5 ? 'partial' :
+                phi < 0.8 ? 'integrated' : 'unified';
+        const score = {
+            phi,
+            wholeInformation,
+            partsInformation,
+            emergentConcepts: emergentConcepts.slice(0, 10),
+            sharedConcepts: sharedConcepts.slice(0, 10),
+            level,
+        };
+        this.history.push(score);
+        return score;
+    }
+    /**
+     * Should the synthesis be re-run with deeper integration?
+     * Returns true if Φ is too low for the number of contributing agents.
+     */
+    needsDeeperSynthesis(phi, agentCount) {
+        // More agents should produce higher integration
+        const threshold = Math.min(0.6, 0.2 + agentCount * 0.1);
+        return phi < threshold;
+    }
+    /** Get consciousness state summary */
+    getState() {
+        if (this.history.length === 0) {
+            return { avgPhi: 0, peakPhi: 0, measurements: 0, trend: 'stable' };
+        }
+        const avgPhi = this.history.reduce((sum, s) => sum + s.phi, 0) / this.history.length;
+        const peakPhi = Math.max(...this.history.map(s => s.phi));
+        // Trend: compare recent half to earlier half
+        let trend = 'stable';
+        if (this.history.length >= 4) {
+            const mid = Math.floor(this.history.length / 2);
+            const early = this.history.slice(0, mid).reduce((s, h) => s + h.phi, 0) / mid;
+            const late = this.history.slice(mid).reduce((s, h) => s + h.phi, 0) / (this.history.length - mid);
+            if (late - early > 0.1)
+                trend = 'rising';
+            else if (early - late > 0.1)
+                trend = 'falling';
+        }
+        return { avgPhi, peakPhi, measurements: this.history.length, trend };
+    }
+    /** Reset for new conversation */
+    reset() {
+        this.history = [];
+    }
+}
+//# sourceMappingURL=integrated-information.js.map

package/dist/integrated-information.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrated-information.js","sourceRoot":"","sources":["../src/integrated-information.ts"],"names":[],"mappings":"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"}

package/dist/matrix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../src/matrix.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;CACpB;AAaD,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAkB1G;AAED,yBAAyB;AACzB,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAE5D;AAED,sBAAsB;AACtB,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,oCAAoC;AACpC,wBAAgB,UAAU,IAAI,WAAW,EAAE,CAE1C;AAED,6DAA6D;AAC7D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKpE;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,oCAAoC;AACpC,wBAAgB,eAAe,IAAI,MAAM,CAUxC;AAED,mCAAmC;AACnC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAQ5D;AAKD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA6CpE,CAAA;AAOD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAsKvD,CAAA;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAmBnE;AAuCD,4EAA4E;AAC5E,wBAAgB,qBAAqB,IAAI,IAAI,CAgB5C;AAED,yCAAyC;AACzC,wBAAgB,sBAAsB,IAAI,MAAM,CAwB/C;AAED,4CAA4C;AAC5C,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBlE;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,IAAI,YAAY,EAAE,CAElD;AAED,8BAA8B;AAC9B,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEpE"}
+{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../src/matrix.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;CACpB;AAaD,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAkB1G;AAED,yBAAyB;AACzB,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAE5D;AAED,sBAAsB;AACtB,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,oCAAoC;AACpC,wBAAgB,UAAU,IAAI,WAAW,EAAE,CAE1C;AAED,6DAA6D;AAC7D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKpE;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,oCAAoC;AACpC,wBAAgB,eAAe,IAAI,MAAM,CAUxC;AAED,mCAAmC;AACnC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAQ5D;AAKD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA6CpE,CAAA;AAOD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAsKvD,CAAA;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAmBnE;AA4CD,4EAA4E;AAC5E,wBAAgB,qBAAqB,IAAI,IAAI,CAgB5C;AAED,yCAAyC;AACzC,wBAAgB,sBAAsB,IAAI,MAAM,CA0D/C;AAED,4CAA4C;AAC5C,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBlE;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,IAAI,YAAY,EAAE,CAElD;AAED,8BAA8B;AAC9B,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEpE"}

package/dist/matrix.js

@@ -6,6 +6,7 @@ import chalk from 'chalk';
 import { registerAgentVisuals } from './ui.js';
 import { CREATIVE_PRESET, CREATIVE_BUILTIN } from './agents/creative.js';
 import { DEVELOPER_PRESET, DEVELOPER_BUILTIN } from './agents/developer.js';
+import { SPECIALISTS } from './agents/specialists.js';
 const AGENT_ICONS = ['◆', '◈', '⟐', '◇', '▣', '✦', '◉', '❖', '▲', '⬡', '∑', '⊕', '☉', '◷', '✧', '◎', '⟳', '⊗', '⊘', '⊛'];
 const AGENT_COLORS = ['#6B5B95', '#5B8BA0', '#6B8E6B', '#B8875C', '#A0768C', '#C4956A', '#4682B4', '#DAA520', '#228B22', '#9370DB', '#DB7093', '#20B2AA', '#8B4513', '#CD853F'];
 /** In-memory agent registry for this session */
@@ -317,6 +318,9 @@ export function activateMimic(profileId) {
 // These are always available without manual creation.
 // Registered on startup so `kbot --agent hacker` works out of the box.
 const BUILTIN_AGENTS = {
+    // ── Specialist Agents (17) ──
+    ...Object.fromEntries(Object.entries(SPECIALISTS).map(([id, def]) => [id, { name: def.name, icon: def.icon, color: def.color, prompt: def.prompt }])),
+    // ── Preset Agents (5) ──
     hacker: {
         name: 'Hacker',
         icon: '⚡',
@@ -368,29 +372,53 @@ export function registerBuiltinAgents() {
 }
 /** Format built-in agents for display */
 export function formatBuiltinAgentList() {
-    const builtins = Object.entries(BUILTIN_AGENTS).map(([id, def]) => {
-        const color = chalk.hex(def.color);
-        return `  ${color(def.icon)} ${color(def.name)} ${chalk.dim(`(${id})`)} — ${chalk.dim(PRESETS[id]?.prompt.slice(0, 80) + '...')}`;
-    });
+    const specialistIds = Object.keys(SPECIALISTS);
+    const presetAgentIds = ['hacker', 'operator', 'dreamer', 'creative', 'developer'];
+    // Core specialists
+    const coreIds = ['kernel', 'researcher', 'coder', 'writer', 'analyst'];
+    const extendedIds = ['aesthete', 'guardian', 'curator', 'strategist'];
+    const domainIds = specialistIds.filter(id => !coreIds.includes(id) && !extendedIds.includes(id));
+    const formatEntry = (id, def) => {
+        const c = chalk.hex(def.color);
+        return `  ${c(def.icon)} ${c(def.name)} ${chalk.dim(`(${id})`)} — ${chalk.dim(def.prompt.slice(0, 80) + '...')}`;
+    };
+    const sections = [];
+    // Core specialists
+    sections.push(chalk.bold('Core Specialists:'));
+    sections.push(...coreIds.map(id => formatEntry(id, BUILTIN_AGENTS[id])));
+    // Extended specialists
+    sections.push('');
+    sections.push(chalk.bold('Extended Specialists:'));
+    sections.push(...extendedIds.map(id => formatEntry(id, BUILTIN_AGENTS[id])));
+    // Domain specialists
+    sections.push('');
+    sections.push(chalk.bold('Domain Specialists:'));
+    sections.push(...domainIds.map(id => formatEntry(id, BUILTIN_AGENTS[id])));
+    // Preset agents
+    sections.push('');
+    sections.push(chalk.bold('Preset Agents:'));
+    sections.push(...presetAgentIds.map(id => formatEntry(id, BUILTIN_AGENTS[id])));
+    // Custom agents (session-created)
     const customs = listAgents().filter(a => !BUILTIN_AGENTS[a.id]);
-    const customLines = customs.map(a => {
-        const color = chalk.hex(a.color);
-        return `  ${color(a.icon)} ${color(a.name)} ${chalk.dim(`(${a.id})`)} — ${chalk.dim(a.systemPrompt.slice(0, 80) + '...')}`;
-    });
-    let out = chalk.bold('Built-in Agents:\n') + builtins.join('\n');
-    if (customLines.length > 0) {
-        out += '\n\n' + chalk.bold('Custom Agents (this session):\n') + customLines.join('\n');
+    if (customs.length > 0) {
+        sections.push('');
+        sections.push(chalk.bold('Custom Agents (this session):'));
+        sections.push(...customs.map(a => {
+            const c = chalk.hex(a.color);
+            return `  ${c(a.icon)} ${c(a.name)} ${chalk.dim(`(${a.id})`)} — ${chalk.dim(a.systemPrompt.slice(0, 80) + '...')}`;
+        }));
     }
-    // Also show presets
-    const presetIds = Object.keys(PRESETS).filter(id => !BUILTIN_AGENTS[id]);
-    if (presetIds.length > 0) {
-        const presetLines = presetIds.map(id => {
+    // Template presets (not already in builtin)
+    const templateIds = Object.keys(PRESETS).filter(id => !BUILTIN_AGENTS[id]);
+    if (templateIds.length > 0) {
+        sections.push('');
+        sections.push(chalk.bold('Templates (spawn with: /matrix create <id>):'));
+        sections.push(...templateIds.map(id => {
             const p = PRESETS[id];
             return `  ${chalk.dim('◇')} ${p.name} ${chalk.dim(`(${id})`)} — ${chalk.dim(p.prompt.slice(0, 80) + '...')}`;
-        });
-        out += '\n\n' + chalk.bold('Presets (spawn with: /matrix create <id>):\n') + presetLines.join('\n');
+        }));
     }
-    return out;
+    return sections.join('\n');
 }
 /** Format a single built-in agent detail */
 export function formatBuiltinAgentDetail(id) {