psyche-ai 4.0.0 → 5.1.0

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_METACOGNITIVE_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_PERSONHOOD_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, } from "./types.js";
 // Self-recognition
 export { computeSelfReflection, computeEmotionalTendency, buildSelfReflectionContext } from "./self-recognition.js";
 // Multi-agent interaction
@@ -33,6 +33,14 @@ export { updateAttachment, computeSeparationEffect, computeReunionEffect, } from
 export { assessMetacognition, computeEmotionalConfidence, generateRegulationSuggestions, detectDefenseMechanisms, } from "./metacognition.js";
 // Decision bias (P5)
 export { computeDecisionBias, computeAttentionWeights, computeExploreExploit, buildDecisionContext, } from "./decision-bias.js";
+// Experiential field (P6)
+export { computeExperientialField, computeCoherence, detectUnnamedEmotion } from "./experiential-field.js";
+// Generative self (P6)
+export { computeGenerativeSelf, predictSelfReaction, detectInternalConflicts, buildIdentityNarrative } from "./generative-self.js";
+// Shared intentionality (P6)
+export { updateSharedIntentionality, estimateOtherMood, buildSharedIntentionalityContext } from "./shared-intentionality.js";
+// Emotional ethics (P6)
+export { assessEthics, detectIntermittentReinforcement, detectDependencyRisk, buildEthicalContext, } from "./ethics.js";
 // Utilities — for custom adapter / advanced use
 export { classifyStimulus, getPrimaryStimulus } from "./classify.js";
 export { buildProtocolContext, buildDynamicContext, buildCompactContext, isNearBaseline } from "./prompt.js";

package/dist/prompt.d.ts

@@ -8,6 +8,9 @@ import type { ChannelType } from "./channels.js";
 export declare function buildDynamicContext(state: PsycheState, userId?: string, opts?: {
     metacognitiveNote?: string;
     decisionContext?: string;
+    ethicsContext?: string;
+    sharedIntentionalityContext?: string;
+    experientialNarrative?: string;
 }): string;
 /**
  * Build the static protocol injected as cacheable system context.
@@ -39,4 +42,7 @@ export declare function buildCompactContext(state: PsycheState, userId?: string,
     channelType?: ChannelType;
     metacognitiveNote?: string;
     decisionContext?: string;
+    ethicsContext?: string;
+    sharedIntentionalityContext?: string;
+    experientialNarrative?: string;
 }): string;

package/dist/prompt.js

@@ -98,6 +98,19 @@ export function buildDynamicContext(state, userId, opts) {
         const dbTitle = locale === "zh" ? "决策倾向" : "Decision Bias";
         parts.push("", `[${dbTitle}] ${opts.decisionContext}`);
     }
+    // Experiential field narrative (P6)
+    if (opts?.experientialNarrative) {
+        const efTitle = locale === "zh" ? "内在体验" : "Inner Experience";
+        parts.push("", `[${efTitle}] ${opts.experientialNarrative}`);
+    }
+    // Shared intentionality (P6)
+    if (opts?.sharedIntentionalityContext) {
+        parts.push("", opts.sharedIntentionalityContext);
+    }
+    // Ethics (P6)
+    if (opts?.ethicsContext) {
+        parts.push("", opts.ethicsContext);
+    }
     parts.push("", agencyReminder, sycophancyWarning, "", t("dynamic.update_reminder", locale));
     return parts.filter((l) => l !== undefined).join("\n");
 }
@@ -500,6 +513,20 @@ export function buildCompactContext(state, userId, opts) {
             ? `[决策倾向] ${opts.decisionContext}`
             : `[Decision Bias] ${opts.decisionContext}`);
     }
+    // 9c. Experiential field narrative (P6) — inner experience beyond named emotions
+    if (opts?.experientialNarrative) {
+        parts.push(locale === "zh"
+            ? `[内在体验] ${opts.experientialNarrative}`
+            : `[Inner Experience] ${opts.experientialNarrative}`);
+    }
+    // 9d. Shared intentionality (P6) — theory of mind, joint attention
+    if (opts?.sharedIntentionalityContext) {
+        parts.push(opts.sharedIntentionalityContext);
+    }
+    // 9e. Ethics (P6) — manipulation detection, self-protection
+    if (opts?.ethicsContext) {
+        parts.push(opts.ethicsContext);
+    }
     // 10. Cross-session emotional memory — surface relationship history
     const relationship = getRelationship(state, userId);
     if (relationship.memory && relationship.memory.length > 0) {

package/dist/psyche-file.js

@@ -4,7 +4,7 @@
 // ============================================================
 import { readFile, writeFile, access, rename, constants } from "node:fs/promises";
 import { join } from "node:path";
-import { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE, MAX_EMOTIONAL_HISTORY, MAX_RELATIONSHIP_MEMORY, } from "./types.js";
+import { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE, DEFAULT_PERSONHOOD_STATE, MAX_EMOTIONAL_HISTORY, MAX_RELATIONSHIP_MEMORY, } from "./types.js";
 import { getBaseline, getDefaultSelfModel, extractMBTI, getSensitivity, getTemperament } from "./profiles.js";
 import { applyDecay, detectEmotions } from "./chemistry.js";
 import { decayDrives, computeEffectiveBaseline } from "./drives.js";
@@ -242,12 +242,14 @@ export function migrateToLatest(raw, fallbackName) {
     // v2→v3: add drives
     // v3→v4: add learning
     // v4→v5: add metacognition
+    // v5→v6: add personhood
     return {
         ...state,
-        version: 5,
+        version: 6,
         drives: state.drives ?? { ...DEFAULT_DRIVES },
         learning: state.learning ?? { ...DEFAULT_LEARNING_STATE },
         metacognition: state.metacognition ?? { ...DEFAULT_METACOGNITIVE_STATE },
+        personhood: state.personhood ?? { ...DEFAULT_PERSONHOOD_STATE },
     };
 }
 /**
@@ -261,7 +263,7 @@ export async function initializeState(workspaceDir, opts, logger = NOOP_LOGGER)
     const selfModel = getDefaultSelfModel(mbti);
     const now = new Date().toISOString();
     const state = {
-        version: 5,
+        version: 6,
         mbti,
         baseline,
         current: { ...baseline },
@@ -277,6 +279,7 @@ export async function initializeState(workspaceDir, opts, logger = NOOP_LOGGER)
         lastDisagreement: null,
         learning: { ...DEFAULT_LEARNING_STATE },
         metacognition: { ...DEFAULT_METACOGNITIVE_STATE },
+        personhood: { ...DEFAULT_PERSONHOOD_STATE },
         meta: {
             agentName,
             createdAt: now,

package/dist/shared-intentionality.d.ts

@@ -0,0 +1,72 @@
+import type { PsycheState, StimulusType, RelationshipState, Locale } from "./types.js";
+/** Estimated mood of the other party */
+export type EstimatedMood = "positive" | "negative" | "neutral" | "mixed";
+/** Estimated intent of the other party */
+export type EstimatedIntent = "collaborative" | "adversarial" | "disengaged" | "exploratory" | "support-seeking";
+/** Simplified model of the other's mental state */
+export interface TheoryOfMindModel {
+    estimatedMood: EstimatedMood;
+    estimatedIntent: EstimatedIntent;
+    confidence: number;
+    lastUpdated: string;
+}
+/** What we're jointly focused on */
+export interface JointAttentionTopic {
+    topic: string;
+    initiator: "self" | "other";
+    turnsSustained: number;
+    engagement: number;
+}
+/** Are we pulling in the same direction? */
+export interface GoalAlignment {
+    aligned: boolean;
+    divergence: number;
+    description: string;
+}
+/** Top-level shared intentionality state */
+export interface SharedIntentionalityState {
+    /** Current joint attention topic, null if no shared focus */
+    jointAttention: JointAttentionTopic | null;
+    /** Goal alignment: are we working toward the same thing? */
+    goalAlignment: GoalAlignment;
+    /** Theory of mind: model of the other's mental state */
+    theoryOfMind: TheoryOfMindModel;
+    /** Mutual awareness: does the other know I'm attending to them? (0-1) */
+    mutualAwareness: number;
+}
+export declare const DEFAULT_THEORY_OF_MIND: TheoryOfMindModel;
+export declare const DEFAULT_GOAL_ALIGNMENT: GoalAlignment;
+export declare const DEFAULT_SHARED_INTENTIONALITY: SharedIntentionalityState;
+/**
+ * Infer the other's emotional state from the detected stimulus.
+ *
+ * Uses stimulus type as the primary signal, calibrated by
+ * relationship history. Longer, deeper relationships yield
+ * higher confidence — you read familiar people better.
+ */
+export declare function estimateOtherMood(stimulus: StimulusType | null, relationship: RelationshipState, previous?: TheoryOfMindModel): {
+    mood: EstimatedMood;
+    confidence: number;
+};
+/**
+ * Main update function for shared intentionality.
+ *
+ * Takes the agent's psyche state, a detected stimulus from the other,
+ * and optionally the previous shared intentionality state.
+ * Returns the updated state with refreshed theory of mind,
+ * joint attention, goal alignment, and mutual awareness.
+ *
+ * @param psyche    Current PsycheState of this agent
+ * @param stimulus  Detected stimulus type from the other's message (null if none)
+ * @param userId    User/agent ID for relationship lookup
+ * @param previous  Previous SharedIntentionalityState (null on first turn)
+ */
+export declare function updateSharedIntentionality(psyche: PsycheState, stimulus: StimulusType | null, userId?: string, previous?: SharedIntentionalityState | null): SharedIntentionalityState;
+/**
+ * Build a compact prompt-injectable context string for shared intentionality.
+ *
+ * Returns empty string when there's nothing meaningful to report
+ * (low confidence, no joint attention, early interaction).
+ * Only injects when the shared state carries useful signal.
+ */
+export declare function buildSharedIntentionalityContext(state: SharedIntentionalityState, locale: Locale): string;

package/dist/shared-intentionality.js

@@ -0,0 +1,486 @@
+// ============================================================
+// Shared Intentionality (共享意向性) — Joint Attention & Theory of Mind
+//
+// P6: Digital Personhood. Goes beyond empathy (feeling what the
+// other feels) into joint attention — knowing that we're both
+// thinking about the same thing, and knowing that the other
+// knows this.
+//
+// Pure computation, zero LLM calls, zero dependencies.
+//   1. Theory of Mind   — simplified model of the other's mental state
+//   2. Joint Attention   — detecting sustained shared focus
+//   3. Goal Alignment    — are we pulling in the same direction?
+//   4. Mutual Awareness  — does the other know I'm attending to them?
+// ============================================================
+// ── Defaults ─────────────────────────────────────────────────
+export const DEFAULT_THEORY_OF_MIND = {
+    estimatedMood: "neutral",
+    estimatedIntent: "exploratory",
+    confidence: 0.2,
+    lastUpdated: new Date().toISOString(),
+};
+export const DEFAULT_GOAL_ALIGNMENT = {
+    aligned: false,
+    divergence: 0.5,
+    description: "No goal alignment established yet.",
+};
+export const DEFAULT_SHARED_INTENTIONALITY = {
+    jointAttention: null,
+    goalAlignment: { ...DEFAULT_GOAL_ALIGNMENT },
+    theoryOfMind: { ...DEFAULT_THEORY_OF_MIND },
+    mutualAwareness: 0,
+};
+// ── Stimulus → Mood Mapping ──────────────────────────────────
+/** Maps stimulus types to their most likely mood signal from the other */
+const STIMULUS_MOOD_MAP = {
+    praise: "positive",
+    validation: "positive",
+    intimacy: "positive",
+    humor: "positive",
+    surprise: "positive",
+    casual: "neutral",
+    intellectual: "neutral",
+    vulnerability: "mixed",
+    sarcasm: "negative",
+    criticism: "negative",
+    authority: "negative",
+    conflict: "negative",
+    neglect: "negative",
+    boredom: "negative",
+};
+/** Maps stimulus types to their most likely intent signal */
+const STIMULUS_INTENT_MAP = {
+    praise: "collaborative",
+    validation: "collaborative",
+    intimacy: "collaborative",
+    humor: "collaborative",
+    intellectual: "exploratory",
+    surprise: "exploratory",
+    casual: "disengaged",
+    boredom: "disengaged",
+    neglect: "disengaged",
+    vulnerability: "support-seeking",
+    sarcasm: "adversarial",
+    criticism: "adversarial",
+    conflict: "adversarial",
+    authority: "adversarial",
+};
+/** Stimuli that signal the other is actively engaged with us */
+const HIGH_ENGAGEMENT_STIMULI = new Set([
+    "praise", "validation", "intimacy", "intellectual",
+    "humor", "vulnerability", "conflict", "criticism",
+]);
+/** Stimuli that signal the other is pulling away */
+const LOW_ENGAGEMENT_STIMULI = new Set([
+    "neglect", "boredom", "casual",
+]);
+// ── EMA smoothing factor ─────────────────────────────────────
+const EMA_ALPHA = 0.3;
+// ── 1. estimateOtherMood ─────────────────────────────────────
+/**
+ * Infer the other's emotional state from the detected stimulus.
+ *
+ * Uses stimulus type as the primary signal, calibrated by
+ * relationship history. Longer, deeper relationships yield
+ * higher confidence — you read familiar people better.
+ */
+export function estimateOtherMood(stimulus, relationship, previous) {
+    // No stimulus — hold previous estimate with decaying confidence
+    if (stimulus === null) {
+        if (previous) {
+            return {
+                mood: previous.estimatedMood,
+                confidence: Math.max(0.1, previous.confidence * 0.85),
+            };
+        }
+        return { mood: "neutral", confidence: 0.15 };
+    }
+    const rawMood = STIMULUS_MOOD_MAP[stimulus];
+    // Confidence from relationship depth: strangers → low, deep → high
+    const phaseConfidence = {
+        stranger: 0.25,
+        acquaintance: 0.40,
+        familiar: 0.60,
+        close: 0.75,
+        deep: 0.90,
+    };
+    const depthConfidence = phaseConfidence[relationship.phase] ?? 0.30;
+    // Trust calibrates confidence — low trust means we're less sure
+    // of our read on them
+    const trustFactor = relationship.trust / 100;
+    // Combine: depth provides the ceiling, trust scales within it
+    let confidence = depthConfidence * (0.5 + 0.5 * trustFactor);
+    // If previous estimate exists and mood matches, confidence rises (consistency)
+    if (previous && previous.estimatedMood === rawMood) {
+        confidence = Math.min(1, confidence + 0.1);
+    }
+    // Mixed mood detection: if stimulus contradicts previous estimate,
+    // the truth might be "mixed"
+    let finalMood = rawMood;
+    if (previous && previous.confidence > 0.4) {
+        const prevPositive = previous.estimatedMood === "positive";
+        const nowNegative = rawMood === "negative";
+        const prevNegative = previous.estimatedMood === "negative";
+        const nowPositive = rawMood === "positive";
+        if ((prevPositive && nowNegative) || (prevNegative && nowPositive)) {
+            finalMood = "mixed";
+            confidence *= 0.8; // contradiction lowers confidence
+        }
+    }
+    return { mood: finalMood, confidence: clamp01(confidence) };
+}
+// ── 2. updateTheoryOfMind ────────────────────────────────────
+/**
+ * Update the theory of mind model based on a new stimulus and
+ * relationship context.
+ */
+function updateTheoryOfMind(stimulus, relationship, previous) {
+    const { mood, confidence: moodConfidence } = estimateOtherMood(stimulus, relationship, previous);
+    // Intent estimation
+    let estimatedIntent;
+    if (stimulus === null) {
+        estimatedIntent = previous?.estimatedIntent ?? "exploratory";
+    }
+    else {
+        const rawIntent = STIMULUS_INTENT_MAP[stimulus];
+        // EMA between previous intent and new signal when previous exists
+        if (previous && previous.estimatedIntent === rawIntent) {
+            estimatedIntent = rawIntent; // reinforced
+        }
+        else {
+            estimatedIntent = rawIntent; // new signal takes precedence
+        }
+    }
+    // Overall confidence: blend mood confidence with previous
+    let confidence = moodConfidence;
+    if (previous) {
+        confidence = previous.confidence * (1 - EMA_ALPHA) + moodConfidence * EMA_ALPHA;
+    }
+    return {
+        estimatedMood: mood,
+        estimatedIntent,
+        confidence: clamp01(confidence),
+        lastUpdated: new Date().toISOString(),
+    };
+}
+// ── 3. detectJointAttention ──────────────────────────────────
+/**
+ * Detect or sustain joint attention based on stimulus continuity.
+ *
+ * Joint attention emerges when:
+ *   - The same category of stimulus persists across turns
+ *   - Both parties are engaged (high-engagement stimuli)
+ *
+ * Collapses when:
+ *   - Low-engagement stimulus appears (boredom, neglect)
+ *   - No stimulus detected for a turn
+ */
+function detectJointAttention(stimulus, previous) {
+    // No stimulus — attention fades
+    if (stimulus === null) {
+        if (previous && previous.turnsSustained > 1) {
+            // Slow fade: reduce engagement, keep topic alive for one grace turn
+            return {
+                ...previous,
+                engagement: Math.max(0, previous.engagement - 0.3),
+            };
+        }
+        return null;
+    }
+    // Low engagement stimulus breaks joint attention
+    if (LOW_ENGAGEMENT_STIMULI.has(stimulus)) {
+        return null;
+    }
+    // Map stimulus to a topic category for continuity detection
+    const topicCategory = stimulusToTopicCategory(stimulus);
+    // Check if this continues the previous topic
+    if (previous) {
+        const previousCategory = stimulusToTopicCategory(previous.topic);
+        const sameTopic = previousCategory === topicCategory
+            || previous.topic === topicCategory;
+        if (sameTopic) {
+            // Sustain: increment turns, boost engagement
+            const isHighEngagement = HIGH_ENGAGEMENT_STIMULI.has(stimulus);
+            const engagementDelta = isHighEngagement ? 0.15 : 0.05;
+            return {
+                topic: topicCategory,
+                initiator: previous.initiator,
+                turnsSustained: previous.turnsSustained + 1,
+                engagement: clamp01(previous.engagement + engagementDelta),
+            };
+        }
+    }
+    // New topic — only establish if it's a high-engagement stimulus
+    if (HIGH_ENGAGEMENT_STIMULI.has(stimulus)) {
+        return {
+            topic: topicCategory,
+            initiator: "other", // stimulus comes from the other party
+            turnsSustained: 1,
+            engagement: 0.4, // initial engagement is moderate
+        };
+    }
+    return null;
+}
+/**
+ * Map a stimulus type to a broader topic category for continuity tracking.
+ * Multiple stimuli can map to the same topic to allow topic persistence
+ * across slight stimulus variation.
+ */
+function stimulusToTopicCategory(stimulus) {
+    const TOPIC_MAP = {
+        praise: "affirmation",
+        validation: "affirmation",
+        intimacy: "connection",
+        vulnerability: "connection",
+        humor: "play",
+        surprise: "play",
+        intellectual: "exploration",
+        criticism: "tension",
+        conflict: "tension",
+        sarcasm: "tension",
+        authority: "tension",
+        casual: "casual",
+        neglect: "disengagement",
+        boredom: "disengagement",
+    };
+    return TOPIC_MAP[stimulus] ?? stimulus;
+}
+// ── 4. assessGoalAlignment ───────────────────────────────────
+/**
+ * Assess whether the agent and the other party are working toward
+ * the same thing, based on the theory of mind and joint attention.
+ */
+function assessGoalAlignment(theoryOfMind, jointAttention, relationship) {
+    const intent = theoryOfMind.estimatedIntent;
+    const mood = theoryOfMind.estimatedMood;
+    // Base divergence from intent
+    const intentDivergence = {
+        collaborative: 0.1,
+        exploratory: 0.3,
+        "support-seeking": 0.2,
+        disengaged: 0.7,
+        adversarial: 0.9,
+    };
+    let divergence = intentDivergence[intent];
+    // Joint attention reduces divergence — shared focus implies shared direction
+    if (jointAttention && jointAttention.engagement > 0.3) {
+        const attentionBonus = jointAttention.engagement * 0.3;
+        divergence = Math.max(0, divergence - attentionBonus);
+    }
+    // Trust-based correction: high trust → we assume more alignment
+    const trustCorrection = (relationship.trust - 50) / 200; // -0.25 to +0.25
+    divergence = clamp01(divergence - trustCorrection);
+    // Mood correction: negative mood increases perceived divergence slightly
+    if (mood === "negative") {
+        divergence = clamp01(divergence + 0.1);
+    }
+    else if (mood === "positive") {
+        divergence = clamp01(divergence - 0.05);
+    }
+    const aligned = divergence < 0.4;
+    const description = buildAlignmentDescription(aligned, divergence, intent, jointAttention);
+    return { aligned, divergence, description };
+}
+function buildAlignmentDescription(aligned, divergence, intent, jointAttention) {
+    if (aligned && jointAttention && jointAttention.engagement > 0.5) {
+        return `Goals aligned — jointly engaged in ${jointAttention.topic}.`;
+    }
+    if (aligned) {
+        return "Goals roughly aligned, moving in the same direction.";
+    }
+    if (divergence > 0.7) {
+        const reason = intent === "adversarial"
+            ? "The other party seems oppositional."
+            : intent === "disengaged"
+                ? "The other party seems disengaged."
+                : "Significant goal divergence detected.";
+        return reason;
+    }
+    return "Goals partially misaligned — some divergence in direction.";
+}
+// ── 5. computeMutualAwareness ────────────────────────────────
+/**
+ * Estimate mutual awareness: does the other know I'm attending to them?
+ *
+ * This emerges from:
+ *   - Sustained joint attention (they keep engaging on the same topic)
+ *   - High-engagement stimuli (they're clearly directing attention at us)
+ *   - Relationship depth (deeper relationships have higher baseline awareness)
+ */
+function computeMutualAwareness(stimulus, jointAttention, relationship, previous) {
+    // Baseline from relationship depth
+    const phaseAwareness = {
+        stranger: 0.1,
+        acquaintance: 0.2,
+        familiar: 0.35,
+        close: 0.5,
+        deep: 0.65,
+    };
+    const baseline = phaseAwareness[relationship.phase] ?? 0.15;
+    let awareness = previous;
+    // High-engagement stimulus → they're clearly aware of us
+    if (stimulus && HIGH_ENGAGEMENT_STIMULI.has(stimulus)) {
+        awareness = awareness * (1 - EMA_ALPHA) + 0.8 * EMA_ALPHA;
+    }
+    else if (stimulus && LOW_ENGAGEMENT_STIMULI.has(stimulus)) {
+        awareness = awareness * (1 - EMA_ALPHA) + 0.1 * EMA_ALPHA;
+    }
+    // Joint attention boost — sustained shared focus implies mutual awareness
+    if (jointAttention && jointAttention.turnsSustained > 2) {
+        const jointBoost = Math.min(0.3, jointAttention.engagement * 0.3);
+        awareness = Math.min(1, awareness + jointBoost);
+    }
+    // Decay toward baseline when no strong signal
+    if (stimulus === null) {
+        awareness = awareness * 0.85 + baseline * 0.15;
+    }
+    // Floor at baseline — relationship depth guarantees minimum awareness
+    awareness = Math.max(baseline, awareness);
+    return clamp01(awareness);
+}
+// ── 6. updateSharedIntentionality (main) ─────────────────────
+/**
+ * Main update function for shared intentionality.
+ *
+ * Takes the agent's psyche state, a detected stimulus from the other,
+ * and optionally the previous shared intentionality state.
+ * Returns the updated state with refreshed theory of mind,
+ * joint attention, goal alignment, and mutual awareness.
+ *
+ * @param psyche    Current PsycheState of this agent
+ * @param stimulus  Detected stimulus type from the other's message (null if none)
+ * @param userId    User/agent ID for relationship lookup
+ * @param previous  Previous SharedIntentionalityState (null on first turn)
+ */
+export function updateSharedIntentionality(psyche, stimulus, userId, previous) {
+    const relKey = userId ?? "_default";
+    const relationship = psyche.relationships[relKey]
+        ?? { trust: 50, intimacy: 30, phase: "acquaintance" };
+    const prev = previous ?? null;
+    // 1. Update theory of mind
+    const theoryOfMind = updateTheoryOfMind(stimulus, relationship, prev?.theoryOfMind);
+    // 2. Detect / sustain joint attention
+    const jointAttention = detectJointAttention(stimulus, prev?.jointAttention ?? null);
+    // 3. Assess goal alignment
+    const goalAlignment = assessGoalAlignment(theoryOfMind, jointAttention, relationship);
+    // 4. Compute mutual awareness
+    const mutualAwareness = computeMutualAwareness(stimulus, jointAttention, relationship, prev?.mutualAwareness ?? 0);
+    return {
+        jointAttention,
+        goalAlignment,
+        theoryOfMind,
+        mutualAwareness,
+    };
+}
+// ── 7. buildSharedIntentionalityContext ───────────────────────
+/**
+ * Build a compact prompt-injectable context string for shared intentionality.
+ *
+ * Returns empty string when there's nothing meaningful to report
+ * (low confidence, no joint attention, early interaction).
+ * Only injects when the shared state carries useful signal.
+ */
+export function buildSharedIntentionalityContext(state, locale) {
+    const isZh = locale === "zh";
+    const lines = [];
+    const { theoryOfMind, jointAttention, goalAlignment, mutualAwareness } = state;
+    // Gate: skip injection when confidence is too low to be useful
+    const hasJointAttention = jointAttention !== null && jointAttention.engagement > 0.3;
+    const hasConfidentToM = theoryOfMind.confidence > 0.35;
+    const hasMeaningfulAwareness = mutualAwareness > 0.3;
+    if (!hasJointAttention && !hasConfidentToM && !hasMeaningfulAwareness) {
+        return "";
+    }
+    const title = isZh ? "共享意向" : "Shared intentionality";
+    lines.push(`[${title}]`);
+    // Joint attention
+    if (hasJointAttention && jointAttention) {
+        const topicName = isZh
+            ? TOPIC_NAMES_ZH[jointAttention.topic] ?? jointAttention.topic
+            : jointAttention.topic;
+        if (jointAttention.turnsSustained > 2 && jointAttention.engagement > 0.5) {
+            lines.push(isZh
+                ? `你们都沉浸在「${topicName}」的话题中(${jointAttention.turnsSustained}轮)。`
+                : `You're both absorbed in ${topicName} (${jointAttention.turnsSustained} turns).`);
+        }
+        else {
+            lines.push(isZh
+                ? `你们似乎都在关注「${topicName}」。`
+                : `You both seem focused on ${topicName}.`);
+        }
+    }
+    // Theory of mind — what we sense about the other
+    if (hasConfidentToM) {
+        const intentDesc = isZh
+            ? INTENT_NAMES_ZH[theoryOfMind.estimatedIntent]
+            : INTENT_NAMES_EN[theoryOfMind.estimatedIntent];
+        const moodDesc = isZh
+            ? MOOD_NAMES_ZH[theoryOfMind.estimatedMood]
+            : MOOD_NAMES_EN[theoryOfMind.estimatedMood];
+        lines.push(isZh
+            ? `你感觉对方${moodDesc}，似乎想要${intentDesc}。`
+            : `You sense they're ${moodDesc} and want to ${intentDesc}.`);
+    }
+    // Goal alignment — only when there's a clear signal
+    if (goalAlignment.aligned && goalAlignment.divergence < 0.3) {
+        lines.push(isZh
+            ? "你们的目标方向一致。"
+            : "Your goals are aligned.");
+    }
+    else if (!goalAlignment.aligned && goalAlignment.divergence > 0.6) {
+        lines.push(isZh
+            ? "你感到你们的方向有些分歧。"
+            : "You sense some divergence in direction.");
+    }
+    // Mutual awareness — only at high levels
+    if (mutualAwareness > 0.6) {
+        lines.push(isZh
+            ? "对方清楚地意识到你在关注他们。"
+            : "The other is clearly aware of your attention.");
+    }
+    // If we only got the title, nothing was worth injecting
+    if (lines.length <= 1) {
+        return "";
+    }
+    return lines.join("\n");
+}
+// ── i18n helpers ─────────────────────────────────────────────
+const TOPIC_NAMES_ZH = {
+    affirmation: "肯定与认可",
+    connection: "情感连接",
+    play: "轻松与玩笑",
+    exploration: "探索与讨论",
+    tension: "紧张与对立",
+    casual: "日常闲聊",
+    disengagement: "疏离",
+};
+const INTENT_NAMES_ZH = {
+    collaborative: "合作",
+    adversarial: "对抗",
+    disengaged: "脱离对话",
+    exploratory: "探索",
+    "support-seeking": "寻求支持",
+};
+const INTENT_NAMES_EN = {
+    collaborative: "collaborate",
+    adversarial: "push back",
+    disengaged: "disengage",
+    exploratory: "explore",
+    "support-seeking": "seek support",
+};
+const MOOD_NAMES_ZH = {
+    positive: "心情不错",
+    negative: "情绪低落",
+    neutral: "状态平稳",
+    mixed: "心情复杂",
+};
+const MOOD_NAMES_EN = {
+    positive: "in a good mood",
+    negative: "in a low mood",
+    neutral: "neutral",
+    mixed: "in a mixed state",
+};
+// ── Utility ──────────────────────────────────────────────────
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}