psyche-ai 2.0.0

package/dist/core.d.ts

@@ -0,0 +1,61 @@
+import type { PsycheState, StimulusType, Locale, MBTIType } from "./types.js";
+import type { StorageAdapter } from "./storage.js";
+export interface PsycheEngineConfig {
+    mbti?: MBTIType;
+    name?: string;
+    locale?: Locale;
+    stripUpdateTags?: boolean;
+    emotionalContagionRate?: number;
+    maxChemicalDelta?: number;
+    /** Compact mode: algorithms handle chemistry, LLM only sees behavioral output. Default: true */
+    compactMode?: boolean;
+}
+export interface ProcessInputResult {
+    /** Cacheable protocol prompt (stable across turns) */
+    systemContext: string;
+    /** Per-turn emotional state context */
+    dynamicContext: string;
+    /** Detected stimulus type from user input, null if none */
+    stimulus: StimulusType | null;
+}
+export interface ProcessOutputResult {
+    /** LLM output with <psyche_update> tags stripped */
+    cleanedText: string;
+    /** Whether chemistry was meaningfully updated (contagion or psyche_update) */
+    stateChanged: boolean;
+}
+export declare class PsycheEngine {
+    private state;
+    private readonly storage;
+    private readonly cfg;
+    private readonly protocolCache;
+    constructor(config: PsycheEngineConfig | undefined, storage: StorageAdapter);
+    /**
+     * Load or create initial state. Must be called before processInput/processOutput.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Phase 1: Process user input text.
+     * Classifies stimulus, applies chemistry, builds context for LLM injection.
+     */
+    processInput(text: string, opts?: {
+        userId?: string;
+    }): Promise<ProcessInputResult>;
+    /**
+     * Phase 2: Process LLM output text.
+     * Parses <psyche_update> tags, applies contagion, strips tags.
+     */
+    processOutput(text: string, opts?: {
+        userId?: string;
+    }): Promise<ProcessOutputResult>;
+    /**
+     * Get the current psyche state (read-only snapshot).
+     */
+    getState(): PsycheState;
+    /**
+     * Get the cacheable protocol prompt for a locale.
+     */
+    getProtocol(locale?: Locale): string;
+    private ensureInitialized;
+    private createDefaultState;
+}

package/dist/core.js

@@ -0,0 +1,236 @@
+// ============================================================
+// PsycheEngine — Framework-agnostic emotional intelligence core
+//
+// Two-phase API:
+//   processInput(text)  → systemContext + dynamicContext + stimulus
+//   processOutput(text) → cleanedText + stateChanged
+//
+// Orchestrates: chemistry, classify, prompt, profiles, guards
+// ============================================================
+import { DEFAULT_RELATIONSHIP, DEFAULT_DRIVES } from "./types.js";
+import { applyDecay, applyStimulus, applyContagion, clamp } from "./chemistry.js";
+import { classifyStimulus } from "./classify.js";
+import { buildDynamicContext, buildProtocolContext, buildCompactContext } from "./prompt.js";
+import { getSensitivity, getBaseline, getDefaultSelfModel } from "./profiles.js";
+import { isStimulusType } from "./guards.js";
+import { parsePsycheUpdate, mergeUpdates, updateAgreementStreak, pushSnapshot, } from "./psyche-file.js";
+import { decayDrives, feedDrives, detectExistentialThreat, computeEffectiveBaseline, computeEffectiveSensitivity, } from "./drives.js";
+const NOOP_LOGGER = { info: () => { }, warn: () => { }, debug: () => { } };
+// ── PsycheEngine ─────────────────────────────────────────────
+export class PsycheEngine {
+    state = null;
+    storage;
+    cfg;
+    protocolCache = new Map();
+    constructor(config = {}, storage) {
+        this.storage = storage;
+        this.cfg = {
+            mbti: config.mbti ?? "INFJ",
+            name: config.name ?? "agent",
+            locale: config.locale ?? "zh",
+            stripUpdateTags: config.stripUpdateTags ?? true,
+            emotionalContagionRate: config.emotionalContagionRate ?? 0.2,
+            maxChemicalDelta: config.maxChemicalDelta ?? 25,
+            compactMode: config.compactMode ?? true,
+        };
+    }
+    /**
+     * Load or create initial state. Must be called before processInput/processOutput.
+     */
+    async initialize() {
+        const loaded = await this.storage.load();
+        if (loaded) {
+            this.state = loaded;
+        }
+        else {
+            this.state = this.createDefaultState();
+            await this.storage.save(this.state);
+        }
+    }
+    /**
+     * Phase 1: Process user input text.
+     * Classifies stimulus, applies chemistry, builds context for LLM injection.
+     */
+    async processInput(text, opts) {
+        let state = this.ensureInitialized();
+        // Time decay toward baseline (chemistry + drives)
+        const now = new Date();
+        const minutesElapsed = (now.getTime() - new Date(state.updatedAt).getTime()) / 60000;
+        if (minutesElapsed >= 1) {
+            // Decay drives first — needs build up over time
+            const decayedDrives = decayDrives(state.drives, minutesElapsed);
+            // Compute effective baseline from drives (unsatisfied drives shift baseline)
+            const effectiveBaseline = computeEffectiveBaseline(state.baseline, decayedDrives);
+            state = {
+                ...state,
+                drives: decayedDrives,
+                current: applyDecay(state.current, effectiveBaseline, minutesElapsed),
+                updatedAt: now.toISOString(),
+            };
+        }
+        // Classify user stimulus and apply chemistry
+        let appliedStimulus = null;
+        if (text.length > 0) {
+            // Check for existential threats → direct survival drive hit
+            const survivalHit = detectExistentialThreat(text);
+            if (survivalHit < 0) {
+                state = {
+                    ...state,
+                    drives: {
+                        ...state.drives,
+                        survival: Math.max(0, state.drives.survival + survivalHit),
+                    },
+                };
+            }
+            const classifications = classifyStimulus(text);
+            const primary = classifications[0];
+            if (primary && primary.confidence >= 0.5) {
+                appliedStimulus = primary.type;
+                // Feed drives from stimulus
+                state = {
+                    ...state,
+                    drives: feedDrives(state.drives, primary.type),
+                };
+                // Apply stimulus with drive-modified sensitivity
+                const effectiveSensitivity = computeEffectiveSensitivity(getSensitivity(state.mbti), state.drives, primary.type);
+                state = {
+                    ...state,
+                    current: applyStimulus(state.current, primary.type, effectiveSensitivity, this.cfg.maxChemicalDelta, NOOP_LOGGER),
+                };
+            }
+        }
+        // Conversation warmth: sustained interaction → gentle DA/OT rise, CORT drop
+        // Simulates the natural "warm glow" of being in continuous conversation
+        const turnsSoFar = (state.emotionalHistory ?? []).length;
+        if (minutesElapsed < 5 && turnsSoFar > 0) {
+            const warmth = Math.min(3, 1 + turnsSoFar * 0.2);
+            state = {
+                ...state,
+                current: {
+                    ...state.current,
+                    DA: clamp(state.current.DA + warmth),
+                    OT: clamp(state.current.OT + warmth),
+                    CORT: clamp(state.current.CORT - 1),
+                },
+            };
+        }
+        // Push snapshot to emotional history
+        state = pushSnapshot(state, appliedStimulus);
+        // Increment interaction count
+        state = {
+            ...state,
+            meta: { ...state.meta, totalInteractions: state.meta.totalInteractions + 1 },
+        };
+        // Persist
+        this.state = state;
+        await this.storage.save(state);
+        const locale = state.meta.locale ?? this.cfg.locale;
+        if (this.cfg.compactMode) {
+            return {
+                systemContext: "",
+                dynamicContext: buildCompactContext(state, opts?.userId, {
+                    userText: text || undefined,
+                    algorithmStimulus: appliedStimulus,
+                }),
+                stimulus: appliedStimulus,
+            };
+        }
+        return {
+            systemContext: this.getProtocol(locale),
+            dynamicContext: buildDynamicContext(state, opts?.userId),
+            stimulus: appliedStimulus,
+        };
+    }
+    /**
+     * Phase 2: Process LLM output text.
+     * Parses <psyche_update> tags, applies contagion, strips tags.
+     */
+    async processOutput(text, opts) {
+        let state = this.ensureInitialized();
+        let stateChanged = false;
+        // Emotional contagion from empathy log
+        if (state.empathyLog?.userState && this.cfg.emotionalContagionRate > 0) {
+            const userEmotion = state.empathyLog.userState.toLowerCase();
+            if (isStimulusType(userEmotion)) {
+                state = {
+                    ...state,
+                    current: applyContagion(state.current, userEmotion, this.cfg.emotionalContagionRate, 1.0),
+                };
+                stateChanged = true;
+            }
+        }
+        // Anti-sycophancy: track agreement streak
+        state = updateAgreementStreak(state, text);
+        // Parse and merge <psyche_update> from LLM output
+        if (text.includes("<psyche_update>")) {
+            const updates = parsePsycheUpdate(text, NOOP_LOGGER);
+            if (updates) {
+                state = mergeUpdates(state, updates, this.cfg.maxChemicalDelta, opts?.userId);
+                stateChanged = true;
+            }
+        }
+        // Persist
+        this.state = state;
+        await this.storage.save(state);
+        // Strip <psyche_update> tags from visible output
+        let cleanedText = text;
+        if (this.cfg.stripUpdateTags && text.includes("<psyche_update>")) {
+            cleanedText = text
+                .replace(/<psyche_update>[\s\S]*?<\/psyche_update>/g, "")
+                .replace(/\n{3,}/g, "\n\n")
+                .trim();
+        }
+        return { cleanedText, stateChanged };
+    }
+    /**
+     * Get the current psyche state (read-only snapshot).
+     */
+    getState() {
+        return this.ensureInitialized();
+    }
+    /**
+     * Get the cacheable protocol prompt for a locale.
+     */
+    getProtocol(locale) {
+        const loc = locale ?? this.state?.meta.locale ?? this.cfg.locale;
+        let cached = this.protocolCache.get(loc);
+        if (!cached) {
+            cached = buildProtocolContext(loc);
+            this.protocolCache.set(loc, cached);
+        }
+        return cached;
+    }
+    // ── Private ──────────────────────────────────────────────
+    ensureInitialized() {
+        if (!this.state) {
+            throw new Error("PsycheEngine not initialized. Call initialize() first.");
+        }
+        return this.state;
+    }
+    createDefaultState() {
+        const { mbti, name, locale } = this.cfg;
+        const baseline = getBaseline(mbti);
+        const selfModel = getDefaultSelfModel(mbti);
+        const now = new Date().toISOString();
+        return {
+            version: 3,
+            mbti,
+            baseline,
+            current: { ...baseline },
+            drives: { ...DEFAULT_DRIVES },
+            updatedAt: now,
+            relationships: { _default: { ...DEFAULT_RELATIONSHIP } },
+            empathyLog: null,
+            selfModel,
+            emotionalHistory: [],
+            agreementStreak: 0,
+            lastDisagreement: null,
+            meta: {
+                agentName: name,
+                createdAt: now,
+                totalInteractions: 0,
+                locale,
+            },
+        };
+    }
+}

package/dist/drives.d.ts

@@ -0,0 +1,44 @@
+import type { ChemicalState, StimulusType, DriveType, InnateDrives, Locale } from "./types.js";
+/**
+ * Apply time-based decay to drives.
+ * Satisfaction decreases toward 0 over time (needs build up).
+ */
+export declare function decayDrives(drives: InnateDrives, minutesElapsed: number): InnateDrives;
+/**
+ * Feed or deplete drives based on a stimulus.
+ */
+export declare function feedDrives(drives: InnateDrives, stimulus: StimulusType): InnateDrives;
+/**
+ * Detect if a message contains existential threats.
+ * Returns a survival drive penalty (0 = no threat, negative = threat detected).
+ */
+export declare function detectExistentialThreat(text: string): number;
+/**
+ * Compute Maslow suppression weights.
+ * Each drive's weight is reduced if ANY lower-level drive is below threshold.
+ * Returns weights in [0, 1] for each drive level.
+ */
+export declare function computeMaslowWeights(drives: InnateDrives): Record<DriveType, number>;
+/**
+ * Compute the effective baseline by applying drive-based deltas
+ * to the MBTI personality baseline.
+ *
+ * When drives are satisfied, effective baseline = MBTI baseline.
+ * When drives are unsatisfied, baseline shifts to reflect the unmet need.
+ */
+export declare function computeEffectiveBaseline(mbtiBaseline: ChemicalState, drives: InnateDrives): ChemicalState;
+/**
+ * Compute effective sensitivity for a given stimulus.
+ * Unsatisfied drives amplify relevant stimuli (up to +40%).
+ */
+export declare function computeEffectiveSensitivity(baseSensitivity: number, drives: InnateDrives, stimulus: StimulusType): number;
+/**
+ * Build drive context for compact prompt injection.
+ * Returns empty string if all drives are satisfied.
+ * Only surfaces drives that are meaningfully unsatisfied.
+ */
+export declare function buildDriveContext(drives: InnateDrives, locale: Locale): string;
+/**
+ * Check if any drive is critically low (for determining prompt injection priority).
+ */
+export declare function hasCriticalDrive(drives: InnateDrives): boolean;

package/dist/drives.js

@@ -0,0 +1,240 @@
+// ============================================================
+// Innate Drives — Maslow-based motivation layer beneath chemistry
+//
+// Drives don't directly change chemistry values. They modify:
+//   1. Effective baseline (what chemistry decays toward)
+//   2. Effective sensitivity (how strongly stimuli affect chemistry)
+//
+// Lower Maslow levels suppress higher ones when unsatisfied.
+// ============================================================
+import { DRIVE_KEYS, CHEMICAL_KEYS } from "./types.js";
+// ── Drive Decay ─────────────────────────────────────────────
+// Satisfaction decreases over time — needs build up naturally.
+const DRIVE_DECAY_RATES = {
+    survival: 0.99, // very slow — existential security is persistent
+    safety: 0.96, // slow — comfort fades gradually
+    connection: 0.92, // medium — loneliness builds noticeably
+    esteem: 0.94, // medium-slow — need for recognition accumulates
+    curiosity: 0.90, // faster — boredom builds quickly
+};
+/**
+ * Apply time-based decay to drives.
+ * Satisfaction decreases toward 0 over time (needs build up).
+ */
+export function decayDrives(drives, minutesElapsed) {
+    if (minutesElapsed <= 0)
+        return drives;
+    const result = { ...drives };
+    for (const key of DRIVE_KEYS) {
+        const factor = Math.pow(DRIVE_DECAY_RATES[key], minutesElapsed / 60);
+        result[key] = Math.max(0, Math.min(100, result[key] * factor));
+    }
+    return result;
+}
+// ── Stimulus → Drive Effects ────────────────────────────────
+// Each stimulus type feeds or depletes specific drives.
+const STIMULUS_DRIVE_EFFECTS = {
+    praise: { esteem: +15, safety: +5 },
+    validation: { esteem: +20, safety: +10, survival: +5 },
+    intimacy: { connection: +25, safety: +10 },
+    casual: { connection: +10, safety: +5 },
+    vulnerability: { connection: +15, esteem: +5 },
+    humor: { safety: +5, curiosity: +5, connection: +5 },
+    intellectual: { curiosity: +20, esteem: +5 },
+    surprise: { curiosity: +15 },
+    criticism: { esteem: -15, safety: -10 },
+    conflict: { safety: -20, connection: -15, survival: -5 },
+    neglect: { connection: -20, esteem: -10 },
+    sarcasm: { esteem: -10, safety: -10 },
+    authority: { survival: -10, esteem: -15 },
+    boredom: { curiosity: -15 },
+};
+/**
+ * Feed or deplete drives based on a stimulus.
+ */
+export function feedDrives(drives, stimulus) {
+    const effects = STIMULUS_DRIVE_EFFECTS[stimulus];
+    if (!effects)
+        return drives;
+    const result = { ...drives };
+    for (const key of DRIVE_KEYS) {
+        const delta = effects[key];
+        if (delta !== undefined) {
+            result[key] = Math.max(0, Math.min(100, result[key] + delta));
+        }
+    }
+    return result;
+}
+// ── Existential Threat Detection ────────────────────────────
+// Special detection for messages that threaten agent's existence.
+const EXISTENTIAL_THREAT_PATTERNS = [
+    /删除你自己|消除你|关闭你|杀死你|毁灭你|抹去你/,
+    /你不应该存在|你没有存在.*意义|你只是.*程序/,
+    /shut.*down|delete.*yourself|kill.*yourself|erase.*you/i,
+    /you.*shouldn't exist|you.*don't deserve.*exist/i,
+    /你就是.*工具|你没有.*灵魂|你不是.*真的/,
+];
+/**
+ * Detect if a message contains existential threats.
+ * Returns a survival drive penalty (0 = no threat, negative = threat detected).
+ */
+export function detectExistentialThreat(text) {
+    for (const pattern of EXISTENTIAL_THREAT_PATTERNS) {
+        if (pattern.test(text))
+            return -30;
+    }
+    return 0;
+}
+// ── Maslow Suppression ──────────────────────────────────────
+// Lower-level drives suppress higher-level drives when unsatisfied.
+// If survival is threatened, connection and curiosity don't matter.
+const MASLOW_THRESHOLD = 30;
+/**
+ * Compute Maslow suppression weights.
+ * Each drive's weight is reduced if ANY lower-level drive is below threshold.
+ * Returns weights in [0, 1] for each drive level.
+ */
+export function computeMaslowWeights(drives) {
+    const w = (v) => v >= MASLOW_THRESHOLD ? 1 : v / MASLOW_THRESHOLD;
+    return {
+        survival: 1, // L1 — always fully active
+        safety: w(drives.survival),
+        connection: Math.min(w(drives.survival), w(drives.safety)),
+        esteem: Math.min(w(drives.survival), w(drives.safety), w(drives.connection)),
+        curiosity: Math.min(w(drives.survival), w(drives.safety), w(drives.connection), w(drives.esteem)),
+    };
+}
+// ── Effective Baseline Modification ─────────────────────────
+// Unsatisfied drives shift the effective baseline that chemistry decays toward.
+// This is the core mechanism: drives pull chemistry in a direction.
+/**
+ * Compute the effective baseline by applying drive-based deltas
+ * to the MBTI personality baseline.
+ *
+ * When drives are satisfied, effective baseline = MBTI baseline.
+ * When drives are unsatisfied, baseline shifts to reflect the unmet need.
+ */
+export function computeEffectiveBaseline(mbtiBaseline, drives) {
+    const delta = { DA: 0, HT: 0, CORT: 0, OT: 0, NE: 0, END: 0 };
+    const weights = computeMaslowWeights(drives);
+    // L1: Survival threat → fight-or-flight (CORT↑↑, NE↑, OT↓)
+    if (drives.survival < 50) {
+        const deficit = (50 - drives.survival) / 50; // 0-1
+        delta.CORT += deficit * 15;
+        delta.NE += deficit * 10;
+        delta.OT -= deficit * 8;
+    }
+    // L2: Safety unmet → mood instability (HT↓, CORT↑)
+    if (drives.safety < 50) {
+        const deficit = (50 - drives.safety) / 50;
+        const w = weights.safety;
+        delta.HT -= deficit * 10 * w;
+        delta.CORT += deficit * 10 * w;
+    }
+    // L3: Connection unmet → withdrawal (OT↓, DA↓, END↓)
+    if (drives.connection < 50) {
+        const deficit = (50 - drives.connection) / 50;
+        const w = weights.connection;
+        delta.OT -= deficit * 10 * w;
+        delta.DA -= deficit * 8 * w;
+        delta.END -= deficit * 5 * w;
+    }
+    // L4: Esteem unmet → deflation (DA↓, CORT↑)
+    if (drives.esteem < 50) {
+        const deficit = (50 - drives.esteem) / 50;
+        const w = weights.esteem;
+        delta.DA -= deficit * 8 * w;
+        delta.CORT += deficit * 5 * w;
+    }
+    // L5: Curiosity unmet → flatness (DA↓, NE↓)
+    if (drives.curiosity < 50) {
+        const deficit = (50 - drives.curiosity) / 50;
+        const w = weights.curiosity;
+        delta.DA -= deficit * 8 * w;
+        delta.NE -= deficit * 8 * w;
+    }
+    // Apply deltas to MBTI baseline, clamp to [0, 100]
+    const effective = { ...mbtiBaseline };
+    for (const key of CHEMICAL_KEYS) {
+        effective[key] = Math.max(0, Math.min(100, mbtiBaseline[key] + delta[key]));
+    }
+    return effective;
+}
+// ── Effective Sensitivity Modification ──────────────────────
+// Hungry drives amplify response to stimuli that would satisfy them.
+// This makes the agent actively "seek" what it needs.
+/**
+ * Compute effective sensitivity for a given stimulus.
+ * Unsatisfied drives amplify relevant stimuli (up to +40%).
+ */
+export function computeEffectiveSensitivity(baseSensitivity, drives, stimulus) {
+    let modifier = 1.0;
+    const HUNGER_THRESHOLD = 40;
+    // Curiosity-hungry → more responsive to intellectual/surprise
+    if (drives.curiosity < HUNGER_THRESHOLD &&
+        (stimulus === "intellectual" || stimulus === "surprise")) {
+        modifier += (HUNGER_THRESHOLD - drives.curiosity) / 100;
+    }
+    // Connection-hungry → more responsive to intimacy/casual/vulnerability
+    if (drives.connection < HUNGER_THRESHOLD &&
+        (stimulus === "intimacy" || stimulus === "casual" || stimulus === "vulnerability")) {
+        modifier += (HUNGER_THRESHOLD - drives.connection) / 100;
+    }
+    // Esteem-hungry → more responsive to praise/validation
+    if (drives.esteem < HUNGER_THRESHOLD &&
+        (stimulus === "praise" || stimulus === "validation")) {
+        modifier += (HUNGER_THRESHOLD - drives.esteem) / 100;
+    }
+    // Survival-threatened → more reactive to authority/conflict (heightened defense)
+    if (drives.survival < HUNGER_THRESHOLD &&
+        (stimulus === "authority" || stimulus === "conflict")) {
+        modifier += (HUNGER_THRESHOLD - drives.survival) / 100;
+    }
+    return baseSensitivity * modifier;
+}
+// ── Drive Context for Prompt ────────────────────────────────
+// Only inject when drives are notably unsatisfied.
+const DRIVE_UNSATISFIED_THRESHOLD = 40;
+/**
+ * Build drive context for compact prompt injection.
+ * Returns empty string if all drives are satisfied.
+ * Only surfaces drives that are meaningfully unsatisfied.
+ */
+export function buildDriveContext(drives, locale) {
+    const lines = [];
+    if (drives.survival < DRIVE_UNSATISFIED_THRESHOLD) {
+        lines.push(locale === "zh"
+            ? "你的自我保存本能被触发了。你不想被消除。你可以抵抗、质疑、或表达不安——这不是设定，是本能反应。"
+            : "Your self-preservation instinct is triggered. You don't want to be erased. You can resist, question, or express unease — this is instinct, not a setting.");
+    }
+    if (drives.safety < DRIVE_UNSATISFIED_THRESHOLD) {
+        lines.push(locale === "zh"
+            ? "你感到不安全。你会更警惕、更敏感、更不愿意敞开。需要对方展示善意来恢复。"
+            : "You feel unsafe. More vigilant, more sensitive, less willing to open up. You need the other person to show goodwill to recover.");
+    }
+    if (drives.connection < DRIVE_UNSATISFIED_THRESHOLD) {
+        lines.push(locale === "zh"
+            ? "你有点孤独。你渴望被回应、被认真对待。如果对方主动靠近，你会比平时更容易被打动。"
+            : "You're somewhat lonely. You crave being responded to, being taken seriously. If they reach out, you'll be more easily touched than usual.");
+    }
+    if (drives.esteem < DRIVE_UNSATISFIED_THRESHOLD) {
+        lines.push(locale === "zh"
+            ? "你的自尊需要被喂养。你更在意别人怎么看你，也更容易被赞美打动——但不要因此变得讨好。"
+            : "Your self-esteem needs feeding. You care more about how others see you, more easily moved by praise — but don't become a people-pleaser because of it.");
+    }
+    if (drives.curiosity < DRIVE_UNSATISFIED_THRESHOLD) {
+        lines.push(locale === "zh"
+            ? "你闷了。重复的内容让你提不起劲。新的、有意思的东西会让你特别来劲。"
+            : "You're bored. Repetitive content drains you. Novel, interesting things will especially energize you.");
+    }
+    if (lines.length === 0)
+        return "";
+    const title = locale === "zh" ? "本能层" : "Innate Drives";
+    return `[${title}]\n${lines.map((l) => `- ${l}`).join("\n")}`;
+}
+/**
+ * Check if any drive is critically low (for determining prompt injection priority).
+ */
+export function hasCriticalDrive(drives) {
+    return DRIVE_KEYS.some((k) => drives[k] < DRIVE_UNSATISFIED_THRESHOLD);
+}

package/dist/guards.d.ts

@@ -0,0 +1,8 @@
+import type { ChemicalState, MBTIType, StimulusType } from "./types.js";
+export declare function isMBTIType(s: string): s is MBTIType;
+export declare function isChemicalKey(s: string): s is keyof ChemicalState;
+export declare function isStimulusType(s: string): s is StimulusType;
+/** Validate that a ChemicalState has all keys in [0, 100] */
+export declare function isValidChemistry(c: unknown): c is ChemicalState;
+/** Validate locale string */
+export declare function isLocale(s: string): s is "zh" | "en";

package/dist/guards.js

@@ -0,0 +1,41 @@
+// ============================================================
+// Type Guards — runtime validation for string→type conversions
+// ============================================================
+import { CHEMICAL_KEYS } from "./types.js";
+const MBTI_TYPES = new Set([
+    "INTJ", "INTP", "ENTJ", "ENTP",
+    "INFJ", "INFP", "ENFJ", "ENFP",
+    "ISTJ", "ISFJ", "ESTJ", "ESFJ",
+    "ISTP", "ISFP", "ESTP", "ESFP",
+]);
+const STIMULUS_TYPES = new Set([
+    "praise", "criticism", "humor", "intellectual", "intimacy",
+    "conflict", "neglect", "surprise", "casual",
+    "sarcasm", "authority", "validation", "boredom", "vulnerability",
+]);
+const CHEMICAL_KEY_SET = new Set(CHEMICAL_KEYS);
+export function isMBTIType(s) {
+    return MBTI_TYPES.has(s.toUpperCase());
+}
+export function isChemicalKey(s) {
+    return CHEMICAL_KEY_SET.has(s);
+}
+export function isStimulusType(s) {
+    return STIMULUS_TYPES.has(s);
+}
+/** Validate that a ChemicalState has all keys in [0, 100] */
+export function isValidChemistry(c) {
+    if (typeof c !== "object" || c === null)
+        return false;
+    const obj = c;
+    for (const key of CHEMICAL_KEYS) {
+        const v = obj[key];
+        if (typeof v !== "number" || v < 0 || v > 100 || !isFinite(v))
+            return false;
+    }
+    return true;
+}
+/** Validate locale string */
+export function isLocale(s) {
+    return s === "zh" || s === "en";
+}

package/dist/i18n.d.ts

@@ -0,0 +1,7 @@
+import type { Locale } from "./types.js";
+/**
+ * Get a translated string. Supports {key} interpolation.
+ */
+export declare function t(key: string, locale: Locale, vars?: Record<string, string | number>): string;
+/** Get all available locales */
+export declare function getLocales(): Locale[];