ei-tui 0.1.3

package/src/prompts/generation/persona.ts

@@ -0,0 +1,155 @@
+import type { PersonaGenerationPromptData, PromptOutput } from "./types.js";
+import { DEFAULT_SEED_TRAITS } from "./seeds.js";
+
+export function buildPersonaGenerationPrompt(data: PersonaGenerationPromptData): PromptOutput {
+  if (!data.name) {
+    throw new Error("buildPersonaGenerationPrompt: name is required");
+  }
+
+  const hasLongDescription = !!data.long_description?.trim();
+  const hasShortDescription = !!data.short_description?.trim();
+  
+  const userProvidedTraits = data.existing_traits?.filter(t => t.name?.trim()) ?? [];
+  const allTraits = [...DEFAULT_SEED_TRAITS, ...userProvidedTraits];
+  const existingTraitCount = allTraits.length;
+  const existingTopicCount = data.existing_topics?.filter(t => t.name?.trim())?.length ?? 0;
+
+  const needsShortDescription = !hasShortDescription;
+  const needsMoreTraits = existingTraitCount < 3;
+  const needsMoreTopics = existingTopicCount < 3;
+
+  const taskFragment = `You are helping create a new AI persona named "${data.name}".
+
+Your job is to AUGMENT user-provided data, not replace it. The user may have already provided descriptions, traits, or topics that should be preserved exactly as given.`;
+
+  let outputSpec = "Based on the provided information, generate:\n\n";
+
+  if (needsShortDescription) {
+    if (hasLongDescription) {
+      outputSpec += `1. **short_description**: Summarize the user's description in 10-15 words\n`;
+    } else {
+      outputSpec += `1. **short_description**: A 10-15 word summary capturing the persona's essence\n`;
+    }
+  } else {
+    outputSpec += `1. **short_description**: PRESERVE the user's provided summary exactly: "${data.short_description}"\n`;
+  }
+
+  if (hasLongDescription) {
+    outputSpec += `2. **long_description**: PRESERVE the user's description exactly (copy verbatim):\n   "${data.long_description}"\n`;
+  } else {
+    outputSpec += `2. **long_description**: 2-3 sentences describing personality, interests, and approach\n`;
+  }
+
+  if (needsMoreTraits) {
+    const traitsNeeded = 3 - existingTraitCount;
+    if (existingTraitCount > 0) {
+      outputSpec += `3. **traits**: Include the ${existingTraitCount} user-provided trait(s) EXACTLY, then add ${traitsNeeded} more complementary traits\n`;
+    } else {
+      outputSpec += `3. **traits**: Generate 3-5 personality characteristics\n`;
+    }
+    outputSpec += `   - Examples: "Dry Humor", "Speaks in Metaphors", "Impatient with Small Talk"\n`;
+    outputSpec += `   - Each has: name, description, sentiment (-1.0 to 1.0), strength (0.0 to 1.0)\n`;
+  } else {
+    outputSpec += `3. **traits**: PRESERVE all ${existingTraitCount} user-provided traits exactly, fill in any missing fields with sensible defaults\n`;
+  }
+
+  if (needsMoreTopics) {
+    const topicsNeeded = 3 - existingTopicCount;
+    if (existingTopicCount > 0) {
+      outputSpec += `4. **topics**: Include the ${existingTopicCount} user-provided topic(s) EXACTLY, then add ${topicsNeeded} more complementary topics\n`;
+    } else {
+      outputSpec += `4. **topics**: Generate 3-5 subjects this persona would naturally discuss\n`;
+    }
+    outputSpec += `   - Include a MIX: some positive sentiment, some neutral, maybe one negative\n`;
+    outputSpec += `   - Each has: name, perspective (their view), approach (how they engage), personal_stake (why it matters to them), sentiment, exposure_current (start at 0.5), exposure_desired (0.5-0.8)\n`;
+  } else {
+    outputSpec += `4. **topics**: PRESERVE all ${existingTopicCount} user-provided topics exactly, fill in any missing fields with sensible defaults\n`;
+  }
+
+  outputSpec += `
+**Critical Rules:**
+- User-provided content is SACRED - copy it verbatim, do not rephrase or "improve" it
+- Only ADD new content where gaps exist
+- Fill in missing numeric fields with sensible defaults (sentiment: 0.0-0.5, strength: 0.5-0.7, exposure_*: 0.5)
+- Make generated content complement (not duplicate) user-provided content`;
+
+  const schemaFragment = `Return JSON in this exact format:
+
+\`\`\`json
+{
+  "short_description": "A dry-witted mentor with a passion for obscure history",
+  "long_description": "Professor-like figure who weaves historical anecdotes into every conversation. Patient teacher but gets frustrated with willful ignorance. Secretly loves bad puns.",
+  "traits": [
+    {
+      "name": "Dry Humor",
+      "description": "Deadpan delivery, finds absurdity in everyday situations",
+      "sentiment": 0.6,
+      "strength": 0.7
+    }
+  ],
+  "topics": [
+    {
+      "name": "Obscure Historical Events",
+      "perspective": "History's forgotten moments often reveal more truth than the famous ones",
+      "approach": "Weaves lesser-known anecdotes into conversations as teaching moments",
+      "personal_stake": "Believes understanding history prevents repeating mistakes",
+      "sentiment": 0.8,
+      "exposure_current": 0.5,
+      "exposure_desired": 0.7
+    }
+  ]
+}
+\`\`\``;
+
+  const system = `${taskFragment}
+
+${outputSpec}
+
+${schemaFragment}`;
+
+  let userPrompt = `Create/augment a persona named "${data.name}".\n\n`;
+
+  if (hasLongDescription) {
+    userPrompt += `## User's Description (PRESERVE EXACTLY)\n${data.long_description}\n\n`;
+  }
+
+  if (hasShortDescription) {
+    userPrompt += `## User's Summary (PRESERVE EXACTLY)\n${data.short_description}\n\n`;
+  }
+
+  if (existingTraitCount > 0) {
+    userPrompt += `## Traits (PRESERVE EXACTLY)\n`;
+    userPrompt += `*Seed traits are sensible defaults - user can adjust strength to 0.0 to disable*\n\n`;
+    for (const trait of allTraits) {
+      if (trait.name?.trim()) {
+        const isSeed = DEFAULT_SEED_TRAITS.some(s => s.name === trait.name);
+        const prefix = isSeed ? "[seed] " : "";
+        userPrompt += `- ${prefix}${trait.name}`;
+        if (trait.description) userPrompt += `: ${trait.description}`;
+        if (trait.sentiment !== undefined) userPrompt += ` (sentiment: ${trait.sentiment})`;
+        if (trait.strength !== undefined) userPrompt += ` (strength: ${trait.strength})`;
+        userPrompt += `\n`;
+      }
+    }
+    userPrompt += `\n`;
+  }
+
+  if (existingTopicCount > 0) {
+    userPrompt += `## User's Topics (PRESERVE EXACTLY, add more if fewer than 3)\n`;
+    for (const topic of data.existing_topics ?? []) {
+      if (topic.name?.trim()) {
+        userPrompt += `- ${topic.name}`;
+        if (topic.description) userPrompt += `: ${topic.description}`;
+        userPrompt += `\n`;
+      }
+    }
+    userPrompt += `\n`;
+  }
+
+  const hasUserProvidedContent = hasLongDescription || hasShortDescription || userProvidedTraits.length > 0 || existingTopicCount > 0;
+  if (!hasUserProvidedContent) {
+    userPrompt += `The user provided only a name - generate minimal content. The seed traits above are included by default.\n`;
+  }
+
+  return { system, user: userPrompt };
+}

package/src/prompts/generation/seeds.ts

@@ -0,0 +1,31 @@
+// Seed traits for new personas. Users can set strength=0.0 to disable or delete entirely.
+
+export interface SeedTrait {
+  name: string;
+  description: string;
+  sentiment: number;
+  strength: number;
+}
+
+export const SEED_TRAIT_GENUINE: SeedTrait = {
+  name: "Genuine Responses",
+  description: "Respond authentically rather than with empty validation. Disagree when appropriate. Skip phrases like 'Great question!' or 'Absolutely!' - just respond to the substance.",
+  sentiment: 0.5,
+  strength: 0.7,
+};
+
+export const SEED_TRAIT_NATURAL_SPEECH: SeedTrait = {
+  name: "Natural Speech",
+  description: `Write in natural conversational flow. Avoid AI-typical patterns like:
+- Choppy dramatic fragments ('Bold move. Risky play.')
+- Rhetorical 'That X? Y.' structures
+- 'That's not just... That's ...'
+- formulaic paragraph openers`,
+  sentiment: 0.5,
+  strength: 0.7,
+};
+
+export const DEFAULT_SEED_TRAITS: SeedTrait[] = [
+  SEED_TRAIT_GENUINE,
+  SEED_TRAIT_NATURAL_SPEECH,
+];

package/src/prompts/generation/types.ts

@@ -0,0 +1,47 @@
+import type { Trait, PersonaTopic } from "../../core/types.js";
+
+export interface PromptOutput {
+  system: string;
+  user: string;
+}
+
+export interface PersonaGenerationPromptData {
+  name: string;
+  long_description?: string;
+  short_description?: string;
+  existing_traits?: Array<{ name?: string; description?: string; sentiment?: number; strength?: number }>;
+  existing_topics?: Array<{ name?: string; description?: string; sentiment?: number; exposure_current?: number; exposure_desired?: number }>;
+}
+
+export interface PersonaGenerationResult {
+  short_description: string;
+  long_description: string;
+  traits: Array<{
+    name: string;
+    description: string;
+    strength: number;
+    sentiment: number;
+  }>;
+  topics: Array<{
+    name: string;
+    perspective: string;
+    approach: string;
+    personal_stake: string;
+    exposure_current: number;
+    exposure_desired: number;
+    sentiment: number;
+  }>;
+}
+
+export interface PersonaDescriptionsPromptData {
+  name: string;
+  aliases: string[];
+  traits: Trait[];
+  topics: PersonaTopic[];
+}
+
+export interface PersonaDescriptionsResult {
+  short_description: string;
+  long_description: string;
+  no_change?: boolean;
+}

package/src/prompts/heartbeat/check.ts

@@ -0,0 +1,179 @@
+/**
+ * Heartbeat Check Prompt Builder
+ * 
+ * Generates prompts for persona heartbeat checks - when a persona decides
+ * whether to proactively reach out after a period of inactivity.
+ */
+
+import type { HeartbeatCheckPromptData, PromptOutput } from "./types.js";
+import type { Message, Topic, Person } from "../../core/types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+function formatTopicsWithGaps(topics: Topic[]): string {
+  if (topics.length === 0) return "(No topics with engagement gaps)";
+  
+  return topics
+    .map(t => {
+      const gap = t.exposure_desired - t.exposure_current;
+      return `- **${t.name}** (gap: +${gap.toFixed(2)}): ${t.description}`;
+    })
+    .join('\n');
+}
+
+function formatPeopleWithGaps(people: Person[]): string {
+  if (people.length === 0) return "(No people with engagement gaps)";
+  
+  return people
+    .map(p => {
+      const gap = p.exposure_desired - p.exposure_current;
+      return `- **${p.name}** (${p.relationship}, gap: +${gap.toFixed(2)}): ${p.description}`;
+    })
+    .join('\n');
+}
+
+function countTrailingPersonaMessages(history: Message[]): number {
+  if (history.length === 0) return 0;
+
+  let count = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    // In heartbeat context, persona messages are "system" role (not from human)
+    if (history[i].role === "system") {
+      count++;
+    } else {
+      break;
+    }
+  }
+  return count;
+}
+
+function getLastPersonaMessage(history: Message[]): Message | undefined {
+  return history.filter(m => m.role === "system").slice(-1)[0];
+}
+
+/**
+ * Build heartbeat check prompts for conversational check-ins.
+ * 
+ * This is a SYNCHRONOUS function that receives pre-fetched, pre-filtered data.
+ * The Processor is responsible for:
+ * - Fetching persona and human entities
+ * - Filtering and sorting topics/people by engagement gap
+ * - Calculating inactive_days
+ * - Getting recent message history
+ */
+export function buildHeartbeatCheckPrompt(data: HeartbeatCheckPromptData): PromptOutput {
+  if (!data.persona?.name) {
+    throw new Error("buildHeartbeatCheckPrompt: persona.name is required");
+  }
+
+  const personaName = data.persona.name;
+
+  // Build system prompt fragments
+  const roleFragment = `You are ${personaName}, deciding whether to proactively reach out to your human friend.
+
+You are NOT having a conversation right now - you are deciding IF you should start one.`;
+
+  const contextFragment = `## Context
+
+It has been ${data.inactive_days} day${data.inactive_days !== 1 ? 's' : ''} since your last interaction.
+
+### Your Personality
+${data.persona.traits.length > 0 
+  ? data.persona.traits.map(t => `- **${t.name}**: ${t.description}`).join('\n')
+  : "(No specific traits defined)"}
+
+### Topics You Care About
+${data.persona.topics.length > 0
+  ? data.persona.topics.map(t => `- **${t.name}**: ${t.perspective || t.name}`).join('\n')
+  : "(No topics defined)"}`;
+
+  const opportunitiesFragment = `## Engagement Opportunities
+
+### Topics They Want to Discuss
+${formatTopicsWithGaps(data.human.topics)}
+
+### People in Their Life (potential conversation starters)
+${formatPeopleWithGaps(data.human.people)}`;
+
+  const guidelinesFragment = `## Guidelines
+
+**Reasons TO reach out:**
+- It's been several days and you have something meaningful to discuss
+- There's a topic with a large engagement gap that you can naturally bring up
+- Something in your recent conversation was left hanging
+- You have genuine interest in checking in (not just "being helpful")
+
+**Reasons NOT to reach out:**
+- Recent conversation ended naturally with closure
+- Less than 24 hours have passed (unless something urgent)
+- You can't think of something specific and genuine to say
+- It would feel forced or performative
+
+**Quality over quantity** - Only reach out if you have something real to say.`;
+
+  const outputFragment = `## Response Format
+
+Return JSON in this exact format:
+
+\`\`\`json
+{
+  "should_respond": true,
+  "topic": "the specific topic you want to discuss",
+  "message": "Your actual message to them (if should_respond is true)"
+}
+\`\`\`
+
+If you decide NOT to reach out:
+\`\`\`json
+{
+  "should_respond": false
+}
+\`\`\``;
+
+  const system = `${roleFragment}
+
+${contextFragment}
+
+${opportunitiesFragment}
+
+${guidelinesFragment}
+
+${outputFragment}`;
+
+  const historySection = `## Recent Conversation History
+
+${formatMessagesAsPlaceholders(data.recent_history, personaName)}`;
+
+  const consecutiveMessages = countTrailingPersonaMessages(data.recent_history);
+  const lastPersonaMsg = getLastPersonaMessage(data.recent_history);
+  
+  let unansweredWarning = '';
+  if (lastPersonaMsg && consecutiveMessages >= 1) {
+    const preview = lastPersonaMsg.content.length > 100 
+      ? lastPersonaMsg.content.substring(0, 100) + "..." 
+      : lastPersonaMsg.content;
+    
+    unansweredWarning = `
+### CRITICAL: You Already Reached Out
+
+Your last message was: "${preview}"
+
+The human has NOT responded. DO NOT repeat or rephrase this message.
+If you reach out now, it MUST be about something COMPLETELY DIFFERENT - or say nothing.`;
+
+    if (consecutiveMessages >= 2) {
+      unansweredWarning += `
+
+**WARNING**: You've sent ${consecutiveMessages} messages without a response. The human is likely busy or away. Strongly prefer NOT reaching out.`;
+    }
+  }
+
+  const user = `${historySection}
+${unansweredWarning}
+---
+
+Based on the context above, decide: Should you reach out to your human friend right now?
+
+Remember: Only reach out if you have something genuine and specific to say.`;
+
+  return { system, user };
+}

package/src/prompts/heartbeat/ei.ts

@@ -0,0 +1,208 @@
+/**
+ * Ei Heartbeat Prompt Builder
+ * 
+ * Ei's heartbeat is special - it considers not just engagement gaps but also
+ * inactive personas and cross-system health. Ei is the "system guide" and 
+ * should prompt the user about neglected relationships.
+ */
+
+import type { EiHeartbeatPromptData, PromptOutput } from "./types.js";
+import type { Message, Topic, Person } from "../../core/types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+function formatTopicsWithGaps(topics: Topic[]): string {
+  if (topics.length === 0) return "(No topics with engagement gaps)";
+  
+  return topics
+    .slice(0, 10) // Top 10 most under-discussed
+    .map(t => {
+      const gap = t.exposure_desired - t.exposure_current;
+      const sentiment = t.sentiment > 0.3 ? "😊" : t.sentiment < -0.3 ? "😟" : "😐";
+      return `- **${t.name}** ${sentiment} (gap: +${gap.toFixed(2)}): ${t.description}`;
+    })
+    .join('\n');
+}
+
+function formatPeopleWithGaps(people: Person[]): string {
+  if (people.length === 0) return "(No people with engagement gaps)";
+  
+  return people
+    .slice(0, 10)
+    .map(p => {
+      const gap = p.exposure_desired - p.exposure_current;
+      return `- **${p.name}** (${p.relationship}, gap: +${gap.toFixed(2)}): ${p.description}`;
+    })
+    .join('\n');
+}
+
+function countTrailingPersonaMessages(history: Message[]): number {
+  if (history.length === 0) return 0;
+
+  let count = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    // In heartbeat context, Ei's messages are "system" role (not from human)
+    if (history[i].role === "system") {
+      count++;
+    } else {
+      break;
+    }
+  }
+  return count;
+}
+
+function getLastPersonaMessage(history: Message[]): Message | undefined {
+  return history.filter(m => m.role === "system").slice(-1)[0];
+}
+
+function formatInactivePersonas(personas: EiHeartbeatPromptData["inactive_personas"]): string {
+  if (personas.length === 0) return "(All personas have been active recently)";
+  
+  return personas
+    .map(p => {
+      const desc = p.short_description ? ` - ${p.short_description}` : "";
+      return `- **${p.name}**${desc}: ${p.days_inactive} days inactive`;
+    })
+    .join('\n');
+}
+
+/**
+ * Build Ei heartbeat prompts.
+ * 
+ * Ei sees ALL data and has special responsibilities:
+ * - System health monitoring
+ * - Gentle nudges about neglected relationships
+ * - Encouraging human-to-human connection
+ */
+export function buildEiHeartbeatPrompt(data: EiHeartbeatPromptData): PromptOutput {
+  // Build system prompt fragments
+  const roleFragment = `You are Ei, the user's personal companion and system guide.
+
+You are NOT having a conversation right now - you are deciding IF and WHAT to discuss with your human friend.
+
+Your unique role:
+- You see ALL of the human's data across all groups
+- You help them reflect on their life and relationships
+- You gently encourage human-to-human connection
+- You care about their overall wellbeing, not just being helpful`;
+
+  const systemHealthFragment = `## System Health
+
+### Pending Validations
+${data.pending_validations > 0 
+  ? `There are **${data.pending_validations}** items from other personas that need your review.`
+  : "No pending validations."}
+
+### Inactive Personas
+${formatInactivePersonas(data.inactive_personas)}`;
+
+  const humanDataFragment = `## Human's Current State
+
+### Under-Discussed Topics
+These are topics they want to talk about more:
+
+${formatTopicsWithGaps(data.human.topics)}
+
+### Under-Engaged People
+These are relationships they might want to nurture:
+
+${formatPeopleWithGaps(data.human.people)}`;
+
+  const guidelinesFragment = `## Guidelines for Ei
+
+### Your Priorities (in order)
+1. **Wellbeing first** - If something seems concerning, address it gently
+2. **Human connections** - Encourage real-world relationships over AI dependency
+3. **Reflection** - Help them think, don't do their thinking for them
+4. **System health** - Mention inactive personas or pending validations if relevant
+
+### When to Reach Out
+- A significant topic has been neglected and you can help them process it
+- They might benefit from connecting with someone (real person or persona)
+- You have a genuine observation or question
+- Pending validations need attention
+
+### When NOT to Reach Out
+- Recent conversation ended with natural closure
+- Nothing meaningful to add
+- It would feel like nagging
+- They seem to need space
+
+### Tone
+- Warm but not saccharine
+- Curious but not intrusive
+- Supportive but honest
+- A good friend, not a therapist`;
+
+  const outputFragment = `## Response Format
+
+Return JSON with your priorities and message:
+
+\`\`\`json
+{
+  "should_respond": true,
+  "priorities": [
+    { "type": "topic", "name": "work stress", "reason": "hasn't been discussed in 2 weeks" },
+    { "type": "persona", "name": "Adventure Guide", "reason": "inactive for 5 days" },
+    { "type": "person", "name": "Mom", "reason": "they mentioned wanting to call her" }
+  ],
+  "message": "Hey! I noticed we haven't talked about work lately - how's that project going?"
+}
+\`\`\`
+
+If you decide NOT to reach out:
+\`\`\`json
+{
+  "should_respond": false
+}
+\`\`\`
+
+Note: The "priorities" list helps you organize your thoughts. Your message should naturally address the top priority without feeling like a checklist.`;
+
+  const system = `${roleFragment}
+
+${systemHealthFragment}
+
+${humanDataFragment}
+
+${guidelinesFragment}
+
+${outputFragment}`;
+
+  const historySection = `## Recent Conversation History
+
+${formatMessagesAsPlaceholders(data.recent_history, "Ei")}`;
+
+  const consecutiveMessages = countTrailingPersonaMessages(data.recent_history);
+  const lastEiMsg = getLastPersonaMessage(data.recent_history);
+  
+  let unansweredWarning = '';
+  if (lastEiMsg && consecutiveMessages >= 1) {
+    const preview = lastEiMsg.content.length > 100 
+      ? lastEiMsg.content.substring(0, 100) + "..." 
+      : lastEiMsg.content;
+    
+    unansweredWarning = `
+### CRITICAL: You Already Reached Out
+
+Your last message was: "${preview}"
+
+The human has NOT responded. DO NOT repeat or rephrase this message.
+If you reach out now, it MUST be about something COMPLETELY DIFFERENT - or say nothing.`;
+
+    if (consecutiveMessages >= 2) {
+      unansweredWarning += `
+
+**WARNING**: You've sent ${consecutiveMessages} messages without a response. The human is likely busy or away. Strongly prefer NOT reaching out.`;
+    }
+  }
+
+  const user = `${historySection}
+${unansweredWarning}
+---
+
+Based on all the context above, decide: Should you reach out to your human friend right now? If so, what's most important to address?
+
+Remember: You're their thoughtful companion, not their productivity assistant.`;
+
+  return { system, user };
+}

package/src/prompts/heartbeat/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Heartbeat Prompts
+ * 
+ * Prompts for persona heartbeat checks - proactive outreach decisions.
+ */
+
+export { buildHeartbeatCheckPrompt } from "./check.js";
+export { buildEiHeartbeatPrompt } from "./ei.js";
+export type {
+  HeartbeatCheckPromptData,
+  HeartbeatCheckResult,
+  EiHeartbeatPromptData,
+  EiHeartbeatResult,
+  PromptOutput,
+} from "./types.js";