psyche-ai 3.1.0 → 4.0.0

package/README.md

@@ -165,6 +165,9 @@ cd openclaw-plugin-psyche && node scripts/diagnose.js
 - **上下文分类** — 关系/驱力/历史感知的刺激分类，超越简单正则
 - **时间意识** — 预期、惊喜/失望、遗憾（马尔可夫预测+反事实分析）
 - **依恋动力学** — 4种依恋风格（安全/焦虑/回避/混乱），分离焦虑，重逢效应
+- **元认知** — 情绪自我觉察，评估情绪可靠性，三种调节策略（认知重评/策略性表达/自我安抚）
+- **防御机制检测** — 合理化、投射、升华、回避，在自省中浮现而非压制
+- **决策调制** — 6维偏差向量（探索/警惕/社交/果断/创意/坚持），情绪驱动注意力和决策
 - **Compact Mode** — 算法做化学计算，LLM 只看行为指令（~15-180 tokens vs ~550）
 
 架构详情见 [ARCHITECTURE.md](ARCHITECTURE.md)。
@@ -174,7 +177,7 @@ cd openclaw-plugin-psyche && node scripts/diagnose.js
 ```bash
 npm install
 npm run build
-npm test           # 568 tests
+npm test           # 622 tests
 npm run typecheck  # strict mode
 ```
 

package/dist/core.js

@@ -11,7 +11,7 @@
 //
 // Orchestrates: chemistry, classify, prompt, profiles, guards, learning
 // ============================================================
-import { DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE } from "./types.js";
+import { DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE } from "./types.js";
 import { applyDecay, applyStimulus, applyContagion, clamp } from "./chemistry.js";
 import { classifyStimulus } from "./classify.js";
 import { buildDynamicContext, buildProtocolContext, buildCompactContext } from "./prompt.js";
@@ -21,6 +21,8 @@ import { parsePsycheUpdate, mergeUpdates, updateAgreementStreak, pushSnapshot, }
 import { decayDrives, feedDrives, detectExistentialThreat, computeEffectiveBaseline, computeEffectiveSensitivity, } from "./drives.js";
 import { checkForUpdate } from "./update.js";
 import { evaluateOutcome, computeContextHash, updateLearnedVector, predictChemistry, recordPrediction, } from "./learning.js";
+import { assessMetacognition } from "./metacognition.js";
+import { buildDecisionContext } from "./decision-bias.js";
 const NOOP_LOGGER = { info: () => { }, warn: () => { }, debug: () => { } };
 // ── PsycheEngine ─────────────────────────────────────────────
 export class PsycheEngine {
@@ -53,6 +55,11 @@ export class PsycheEngine {
                 loaded.learning = { ...DEFAULT_LEARNING_STATE };
                 loaded.version = 4;
             }
+            // Migrate v4 → v5: add metacognitive state if missing
+            if (!loaded.metacognition) {
+                loaded.metacognition = { ...DEFAULT_METACOGNITIVE_STATE };
+                loaded.version = 5;
+            }
             this.state = loaded;
         }
         else {
@@ -152,6 +159,26 @@ export class PsycheEngine {
                 },
             };
         }
+        // ── Metacognition: assess emotional state before acting ────
+        const metacognitiveAssessment = assessMetacognition(state, appliedStimulus ?? "casual", state.learning.outcomeHistory);
+        // Apply self-soothing regulation if suggested with high confidence
+        for (const reg of metacognitiveAssessment.regulationSuggestions) {
+            if (reg.strategy === "self-soothing" && reg.confidence >= 0.6 && reg.chemistryAdjustment) {
+                const adj = reg.chemistryAdjustment;
+                state = {
+                    ...state,
+                    current: {
+                        ...state.current,
+                        DA: clamp(state.current.DA + (adj.DA ?? 0)),
+                        HT: clamp(state.current.HT + (adj.HT ?? 0)),
+                        CORT: clamp(state.current.CORT + (adj.CORT ?? 0)),
+                        OT: clamp(state.current.OT + (adj.OT ?? 0)),
+                        NE: clamp(state.current.NE + (adj.NE ?? 0)),
+                        END: clamp(state.current.END + (adj.END ?? 0)),
+                    },
+                };
+            }
+        }
         // Push snapshot to emotional history
         state = pushSnapshot(state, appliedStimulus);
         // Increment interaction count
@@ -178,19 +205,27 @@ export class PsycheEngine {
         this.state = state;
         await this.storage.save(state);
         const locale = state.meta.locale ?? this.cfg.locale;
+        // Build metacognitive and decision context strings
+        const metacogNote = metacognitiveAssessment.metacognitiveNote;
+        const decisionCtx = buildDecisionContext(state);
         if (this.cfg.compactMode) {
             return {
                 systemContext: "",
                 dynamicContext: buildCompactContext(state, opts?.userId, {
                     userText: text || undefined,
                     algorithmStimulus: appliedStimulus,
+                    metacognitiveNote: metacogNote || undefined,
+                    decisionContext: decisionCtx || undefined,
                 }),
                 stimulus: appliedStimulus,
             };
         }
         return {
             systemContext: this.getProtocol(locale),
-            dynamicContext: buildDynamicContext(state, opts?.userId),
+            dynamicContext: buildDynamicContext(state, opts?.userId, {
+                metacognitiveNote: metacogNote || undefined,
+                decisionContext: decisionCtx || undefined,
+            }),
             stimulus: appliedStimulus,
         };
     }
@@ -301,7 +336,7 @@ export class PsycheEngine {
         const selfModel = getDefaultSelfModel(mbti);
         const now = new Date().toISOString();
         return {
-            version: 4,
+            version: 5,
             mbti,
             baseline,
             current: { ...baseline },
@@ -314,6 +349,7 @@ export class PsycheEngine {
             agreementStreak: 0,
             lastDisagreement: null,
             learning: { ...DEFAULT_LEARNING_STATE },
+            metacognition: { ...DEFAULT_METACOGNITIVE_STATE },
             meta: {
                 agentName: name,
                 createdAt: now,

package/dist/decision-bias.d.ts

@@ -0,0 +1,58 @@
+import type { PsycheState } from "./types.js";
+export interface DecisionBiasVector {
+    explorationTendency: number;
+    cautionLevel: number;
+    socialOrientation: number;
+    assertiveness: number;
+    creativityBias: number;
+    persistenceBias: number;
+}
+export interface AttentionWeights {
+    social: number;
+    intellectual: number;
+    threat: number;
+    emotional: number;
+    routine: number;
+}
+/**
+ * Compute a decision bias vector from the current psyche state.
+ *
+ * Each bias dimension is a weighted combination of relevant chemical
+ * levels and drive states, normalized to [0, 1] where 0.5 is neutral.
+ */
+export declare function computeDecisionBias(state: PsycheState): DecisionBiasVector;
+/**
+ * Compute attention weights that prioritize different conversation content
+ * based on current chemical state.
+ *
+ * Returns normalized weights (sum to ~1) for each content category.
+ * Higher weight = higher priority for that type of content.
+ */
+export declare function computeAttentionWeights(state: PsycheState): AttentionWeights;
+/**
+ * Compute explore vs exploit balance.
+ *
+ * Returns a single float:
+ *   0 = pure exploit (stick with known, safe behaviors)
+ *   1 = pure explore (try new approaches, take risks)
+ *
+ * Exploration is driven by:
+ *   - High curiosity drive satisfaction (energy to explore)
+ *   - High DA (reward anticipation)
+ *   - High NE (novelty-seeking)
+ *   - Low CORT (not stressed)
+ *   - High safety (secure enough to take risks)
+ *
+ * Exploitation is driven by:
+ *   - High CORT / anxiety
+ *   - Low safety drive satisfaction
+ *   - Low DA (no reward motivation)
+ */
+export declare function computeExploreExploit(state: PsycheState): number;
+/**
+ * Build a compact decision context string for prompt injection.
+ *
+ * Only includes biases that deviate significantly from neutral (>0.3 from 0.5).
+ * Keeps output under 100 tokens.
+ */
+export declare function buildDecisionContext(state: PsycheState): string;

package/dist/decision-bias.js

@@ -0,0 +1,211 @@
+// ============================================================
+// Decision Bias — P5: Decision Modulation
+//
+// Converts chemical state + drive state into bias vectors,
+// attention weights, and explore/exploit balance for downstream
+// decision-making. Pure math/heuristic, zero dependencies, no LLM.
+// ============================================================
+// ── Utilities ────────────────────────────────────────────────
+/** Clamp a value to [0, 1] */
+function clamp01(v) {
+    return Math.max(0, Math.min(1, v));
+}
+/** Sigmoid mapping: maps any real number to (0, 1) with midpoint at 0.5 */
+function sigmoid(x, steepness = 1) {
+    return 1 / (1 + Math.exp(-steepness * x));
+}
+/** Normalize a 0-100 chemical/drive value to 0-1 */
+function norm(v) {
+    return clamp01(v / 100);
+}
+/** Weighted average of multiple factors, each in [0, 1] */
+function wavg(values, weights) {
+    let sum = 0;
+    let wsum = 0;
+    for (let i = 0; i < values.length; i++) {
+        sum += values[i] * weights[i];
+        wsum += weights[i];
+    }
+    return wsum > 0 ? clamp01(sum / wsum) : 0.5;
+}
+/** Mean satisfaction across all drives, normalized to [0, 1] */
+function meanDriveSatisfaction(drives) {
+    return norm((drives.survival + drives.safety + drives.connection
+        + drives.esteem + drives.curiosity) / 5);
+}
+// ── Core Computations ────────────────────────────────────────
+/**
+ * Compute a decision bias vector from the current psyche state.
+ *
+ * Each bias dimension is a weighted combination of relevant chemical
+ * levels and drive states, normalized to [0, 1] where 0.5 is neutral.
+ */
+export function computeDecisionBias(state) {
+    const c = state.current;
+    const d = state.drives;
+    // explorationTendency: curiosity drive + DA (reward-seeking) + NE (novelty)
+    // High curiosity hunger (low satisfaction) + high DA/NE → explore
+    const curiosityHunger = 1 - norm(d.curiosity); // lower satisfaction = more hunger
+    const explorationTendency = wavg([norm(c.DA), norm(c.NE), curiosityHunger, norm(d.curiosity)], [0.25, 0.3, 0.25, 0.2]);
+    // cautionLevel: CORT (stress) + safety drive hunger
+    // High CORT + low safety satisfaction → very cautious
+    const safetyHunger = 1 - norm(d.safety);
+    const survivalHunger = 1 - norm(d.survival);
+    const cautionLevel = wavg([norm(c.CORT), safetyHunger, survivalHunger], [0.5, 0.3, 0.2]);
+    // socialOrientation: OT (bonding) + connection drive satisfaction
+    // High OT + hungry for connection → strongly social
+    const connectionHunger = 1 - norm(d.connection);
+    const socialOrientation = wavg([norm(c.OT), norm(d.connection), connectionHunger, norm(c.END)], [0.4, 0.2, 0.25, 0.15]);
+    // assertiveness: NE (arousal/confidence) + esteem drive satisfaction
+    // High NE + satisfied esteem → assertive
+    const assertiveness = wavg([norm(c.NE), norm(d.esteem), norm(c.DA)], [0.4, 0.35, 0.25]);
+    // creativityBias: DA (reward) + END (playfulness) + inverse CORT (low stress)
+    // Creativity flourishes when relaxed, rewarded, and playful
+    const inverseCort = 1 - norm(c.CORT);
+    const creativityBias = wavg([norm(c.DA), norm(c.END), inverseCort], [0.35, 0.3, 0.35]);
+    // persistenceBias: HT stability (serotonin) + overall drive satisfaction
+    // Stable mood + satisfied drives → willingness to persist
+    const overallSatisfaction = meanDriveSatisfaction(d);
+    const persistenceBias = wavg([norm(c.HT), overallSatisfaction, inverseCort], [0.45, 0.35, 0.2]);
+    return {
+        explorationTendency,
+        cautionLevel,
+        socialOrientation,
+        assertiveness,
+        creativityBias,
+        persistenceBias,
+    };
+}
+/**
+ * Compute attention weights that prioritize different conversation content
+ * based on current chemical state.
+ *
+ * Returns normalized weights (sum to ~1) for each content category.
+ * Higher weight = higher priority for that type of content.
+ */
+export function computeAttentionWeights(state) {
+    const c = state.current;
+    // Raw scores based on chemical signatures
+    // High OT → prioritize relationship/social content
+    const socialRaw = norm(c.OT) * 0.6 + norm(c.END) * 0.2 + (1 - norm(c.CORT)) * 0.2;
+    // High NE → prioritize intellectual/novel content
+    const intellectualRaw = norm(c.NE) * 0.5 + norm(c.DA) * 0.3 + norm(state.drives.curiosity) * 0.2;
+    // High CORT → prioritize threat/safety content
+    const threatRaw = norm(c.CORT) * 0.6 + norm(c.NE) * 0.2 + (1 - norm(state.drives.safety)) * 0.2;
+    // Emotional content weighted by overall emotional activation
+    const emotionalRaw = (Math.abs(norm(c.DA) - 0.5)
+        + Math.abs(norm(c.HT) - 0.5)
+        + Math.abs(norm(c.CORT) - 0.5)
+        + Math.abs(norm(c.OT) - 0.5)) / 2; // average deviation from neutral, scaled
+    // Routine content is inverse of activation — when calm and stable, routine matters
+    const activation = (norm(c.NE) + norm(c.CORT) + Math.abs(norm(c.DA) - 0.5)) / 3;
+    const routineRaw = Math.max(0.1, 1 - activation) * norm(c.HT);
+    // Normalize to sum to 1
+    const total = socialRaw + intellectualRaw + threatRaw + emotionalRaw + routineRaw;
+    if (total <= 0) {
+        return { social: 0.2, intellectual: 0.2, threat: 0.2, emotional: 0.2, routine: 0.2 };
+    }
+    return {
+        social: socialRaw / total,
+        intellectual: intellectualRaw / total,
+        threat: threatRaw / total,
+        emotional: emotionalRaw / total,
+        routine: routineRaw / total,
+    };
+}
+/**
+ * Compute explore vs exploit balance.
+ *
+ * Returns a single float:
+ *   0 = pure exploit (stick with known, safe behaviors)
+ *   1 = pure explore (try new approaches, take risks)
+ *
+ * Exploration is driven by:
+ *   - High curiosity drive satisfaction (energy to explore)
+ *   - High DA (reward anticipation)
+ *   - High NE (novelty-seeking)
+ *   - Low CORT (not stressed)
+ *   - High safety (secure enough to take risks)
+ *
+ * Exploitation is driven by:
+ *   - High CORT / anxiety
+ *   - Low safety drive satisfaction
+ *   - Low DA (no reward motivation)
+ */
+export function computeExploreExploit(state) {
+    const c = state.current;
+    const d = state.drives;
+    // Exploration signals
+    const curiosityEnergy = norm(d.curiosity);
+    const rewardDrive = norm(c.DA);
+    const noveltySeeking = norm(c.NE);
+    const relaxation = 1 - norm(c.CORT);
+    const securityBase = norm(d.safety);
+    // Exploitation signals (inverted — higher = more exploit = lower explore)
+    const anxiety = norm(c.CORT);
+    const unsafety = 1 - norm(d.safety);
+    const survivalThreat = 1 - norm(d.survival);
+    // Weighted explore score
+    const exploreScore = wavg([curiosityEnergy, rewardDrive, noveltySeeking, relaxation, securityBase], [0.25, 0.2, 0.2, 0.2, 0.15]);
+    // Weighted exploit score
+    const exploitScore = wavg([anxiety, unsafety, survivalThreat], [0.5, 0.3, 0.2]);
+    // Combine: use sigmoid to create a smooth transition
+    // Positive difference → explore, negative → exploit
+    const diff = exploreScore - exploitScore;
+    return clamp01(sigmoid(diff * 4)); // steepness=4 for reasonable sensitivity
+}
+// ── Prompt Injection ─────────────────────────────────────────
+/** Bias labels for human-readable output */
+const BIAS_LABELS = {
+    explorationTendency: ["探索倾向强", "exploratory"],
+    cautionLevel: ["警惕性高", "cautious"],
+    socialOrientation: ["社交倾向强", "socially oriented"],
+    assertiveness: ["表达果断", "assertive"],
+    creativityBias: ["创意活跃", "creatively active"],
+    persistenceBias: ["意志坚持", "persistent"],
+};
+/** Low-end labels for when bias < 0.2 */
+const BIAS_LABELS_LOW = {
+    explorationTendency: ["倾向保守", "risk-averse"],
+    cautionLevel: ["放松大胆", "relaxed and bold"],
+    socialOrientation: ["偏好独处", "prefers solitude"],
+    assertiveness: ["表达含蓄", "reserved"],
+    creativityBias: ["思维收敛", "convergent thinking"],
+    persistenceBias: ["容易放弃", "low persistence"],
+};
+/**
+ * Build a compact decision context string for prompt injection.
+ *
+ * Only includes biases that deviate significantly from neutral (>0.3 from 0.5).
+ * Keeps output under 100 tokens.
+ */
+export function buildDecisionContext(state) {
+    const bias = computeDecisionBias(state);
+    const explore = computeExploreExploit(state);
+    const locale = state.meta.locale ?? "zh";
+    const li = locale === "zh" ? 0 : 1;
+    const parts = [];
+    // Only surface biases that deviate significantly from neutral
+    const DEVIATION_THRESHOLD = 0.3;
+    for (const key of Object.keys(BIAS_LABELS)) {
+        const val = bias[key];
+        const deviation = val - 0.5;
+        if (deviation > DEVIATION_THRESHOLD) {
+            parts.push(BIAS_LABELS[key][li]);
+        }
+        else if (deviation < -DEVIATION_THRESHOLD) {
+            parts.push(BIAS_LABELS_LOW[key][li]);
+        }
+    }
+    // Explore/exploit — only mention if strongly skewed
+    if (explore > 0.7) {
+        parts.push(locale === "zh" ? "倾向尝试新方法" : "leaning toward new approaches");
+    }
+    else if (explore < 0.3) {
+        parts.push(locale === "zh" ? "倾向安全策略" : "favoring safe strategies");
+    }
+    if (parts.length === 0)
+        return "";
+    const title = locale === "zh" ? "决策倾向" : "Decision Bias";
+    return `[${title}] ${parts.join("、")}`;
+}

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { PsycheEngine } from "./core.js";
 export type { PsycheEngineConfig, ProcessInputResult, ProcessOutputResult, ProcessOutcomeResult } from "./core.js";
 export { FileStorageAdapter, MemoryStorageAdapter } from "./storage.js";
 export type { StorageAdapter } from "./storage.js";
-export type { PsycheState, MBTIType, Locale, StimulusType, ChemicalState, ChemicalSnapshot, SelfModel, RelationshipState, EmpathyEntry, EmotionPattern, DriveType, InnateDrives, LearningState, LearnedVectorAdjustment, PredictionRecord, OutcomeScore, OutcomeSignals, AttachmentStyle, AttachmentData, } from "./types.js";
-export { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, } from "./types.js";
+export type { PsycheState, MBTIType, Locale, StimulusType, ChemicalState, ChemicalSnapshot, SelfModel, RelationshipState, EmpathyEntry, EmotionPattern, DriveType, InnateDrives, LearningState, LearnedVectorAdjustment, PredictionRecord, OutcomeScore, OutcomeSignals, AttachmentStyle, AttachmentData, MetacognitiveState, RegulationRecord, DefensePatternRecord, RegulationStrategyType, DefenseMechanismType, } from "./types.js";
+export { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, } from "./types.js";
 export { computeSelfReflection, computeEmotionalTendency, buildSelfReflectionContext } from "./self-recognition.js";
 export type { SelfReflection } from "./self-recognition.js";
 export { PsycheInteraction } from "./interaction.js";
@@ -19,6 +19,10 @@ export { predictNextStimulus, generateAnticipation, computeSurpriseEffect, compu
 export type { StimulusPrediction, AnticipationState, RegretEntry } from "./temporal.js";
 export { updateAttachment, computeSeparationEffect, computeReunionEffect, } from "./attachment.js";
 export type { SeparationEffect } from "./attachment.js";
+export { assessMetacognition, computeEmotionalConfidence, generateRegulationSuggestions, detectDefenseMechanisms, } from "./metacognition.js";
+export type { MetacognitiveAssessment, RegulationSuggestion, DetectedDefense } from "./metacognition.js";
+export { computeDecisionBias, computeAttentionWeights, computeExploreExploit, buildDecisionContext, } from "./decision-bias.js";
+export type { DecisionBiasVector, AttentionWeights } from "./decision-bias.js";
 export { classifyStimulus, getPrimaryStimulus } from "./classify.js";
 export { buildProtocolContext, buildDynamicContext, buildCompactContext, isNearBaseline } from "./prompt.js";
 export { describeEmotionalState, getExpressionHint, getBehaviorGuide } from "./chemistry.js";

package/dist/index.js

@@ -12,7 +12,7 @@
 export { PsycheEngine } from "./core.js";
 // Storage
 export { FileStorageAdapter, MemoryStorageAdapter } from "./storage.js";
-export { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, } from "./types.js";
+export { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, } from "./types.js";
 // Self-recognition
 export { computeSelfReflection, computeEmotionalTendency, buildSelfReflectionContext } from "./self-recognition.js";
 // Multi-agent interaction
@@ -29,6 +29,10 @@ export { classifyStimulusWithContext, extractContextFeatures, stimulusWarmth } f
 export { predictNextStimulus, generateAnticipation, computeSurpriseEffect, computeRegret, } from "./temporal.js";
 // Attachment dynamics (P4)
 export { updateAttachment, computeSeparationEffect, computeReunionEffect, } from "./attachment.js";
+// Metacognition (P5)
+export { assessMetacognition, computeEmotionalConfidence, generateRegulationSuggestions, detectDefenseMechanisms, } from "./metacognition.js";
+// Decision bias (P5)
+export { computeDecisionBias, computeAttentionWeights, computeExploreExploit, buildDecisionContext, } from "./decision-bias.js";
 // Utilities — for custom adapter / advanced use
 export { classifyStimulus, getPrimaryStimulus } from "./classify.js";
 export { buildProtocolContext, buildDynamicContext, buildCompactContext, isNearBaseline } from "./prompt.js";

package/dist/metacognition.d.ts

@@ -0,0 +1,60 @@
+import type { PsycheState, StimulusType, ChemicalState, OutcomeScore, MetacognitiveState, RegulationStrategyType, DefenseMechanismType } from "./types.js";
+export interface MetacognitiveAssessment {
+    /** 0-1: how reliably has this emotional state led to good outcomes in similar contexts */
+    emotionalConfidence: number;
+    /** Suggested regulation strategies */
+    regulationSuggestions: RegulationSuggestion[];
+    /** Detected psychological defense mechanisms */
+    defenseMechanisms: DetectedDefense[];
+    /** Human-readable self-awareness note for prompt injection */
+    metacognitiveNote: string;
+}
+export interface RegulationSuggestion {
+    strategy: RegulationStrategyType;
+    description: string;
+    /** Suggested micro-adjustment to chemistry */
+    chemistryAdjustment?: Partial<ChemicalState>;
+    /** 0-1: confidence that this strategy would help */
+    confidence: number;
+}
+export interface DetectedDefense {
+    mechanism: DefenseMechanismType;
+    evidence: string;
+    /** 0-1: how strongly the pattern is expressed */
+    strength: number;
+}
+/**
+ * Assess the current metacognitive state.
+ *
+ * Evaluates emotional reliability, generates regulation suggestions,
+ * and detects defense mechanism patterns. Designed to run after emotion
+ * detection and before prompt construction.
+ */
+export declare function assessMetacognition(state: PsycheState, currentStimulus: StimulusType, recentOutcomes: OutcomeScore[]): MetacognitiveAssessment;
+/**
+ * Compute confidence in the current emotional state's reliability.
+ *
+ * "How often has being in this kind of emotional state, in response to
+ * this kind of stimulus, led to good outcomes?"
+ *
+ * Uses outcome history filtered by similar stimulus and similar chemistry profile.
+ */
+export declare function computeEmotionalConfidence(state: PsycheState, currentStimulus: StimulusType, recentOutcomes: OutcomeScore[]): number;
+/**
+ * Generate regulation suggestions based on current state and confidence.
+ */
+export declare function generateRegulationSuggestions(state: PsycheState, currentStimulus: StimulusType, emotionalConfidence: number, recentOutcomes: OutcomeScore[]): RegulationSuggestion[];
+/**
+ * Detect patterns matching known psychological defense mechanisms.
+ *
+ * These are not suppressed — they are surfaced for self-awareness.
+ * The agent can then acknowledge the pattern in its prompt context.
+ */
+export declare function detectDefenseMechanisms(state: PsycheState, currentStimulus: StimulusType, recentOutcomes: OutcomeScore[]): DetectedDefense[];
+/**
+ * Update the persistent metacognitive state after an assessment.
+ *
+ * Tracks regulation history, defense pattern frequencies, and running
+ * confidence average. Called after assessMetacognition to persist learnings.
+ */
+export declare function updateMetacognitiveState(metacognition: MetacognitiveState, assessment: MetacognitiveAssessment): MetacognitiveState;