ei-tui 0.1.3

package/src/prompts/persona/topics-match.ts

@@ -0,0 +1,69 @@
+import type { PersonaTopicMatchPromptData, PromptOutput } from "./types.js";
+import type { PersonaTopic } from "../../core/types.js";
+
+function formatExistingTopics(topics: PersonaTopic[]): string {
+  if (topics.length === 0) return "[]";
+  
+  return JSON.stringify(topics.map(t => ({
+    id: t.id,
+    name: t.name,
+    perspective: t.perspective.substring(0, 100) + (t.perspective.length > 100 ? '...' : ''),
+  })), null, 2);
+}
+
+export function buildPersonaTopicMatchPrompt(data: PersonaTopicMatchPromptData): PromptOutput {
+  if (!data.persona_name || !data.candidate) {
+    throw new Error("buildPersonaTopicMatchPrompt: persona_name and candidate are required");
+  }
+
+  const personaName = data.persona_name;
+
+  const system = `# Task
+
+You are checking if a topic candidate already exists in ${personaName}'s topic list.
+
+# Matching Rules
+
+1. **Exact match**: Same topic name → return its ID
+2. **Similar match**: Clearly the same topic with different wording → return its ID
+   - "Steam Deck" and "Steam Deck Modding" → MATCH (same core topic)
+   - "Cooking" and "Italian Cooking" → consider MATCH if the specific is part of the general
+3. **No match**: Genuinely different topic → return null
+
+# Existing Topics
+
+\`\`\`json
+${formatExistingTopics(data.existing_topics)}
+\`\`\`
+
+# Response Format
+
+Return ONLY the ID of the matching topic, or null if no match exists.
+
+\`\`\`json
+{
+  "matched_id": "uuid-of-matching-topic" | null,
+  "reason": "brief explanation"
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const user = `# Candidate Topic
+
+Name: ${data.candidate.name}
+Message Count: ${data.candidate.message_count}
+Sentiment Signal: ${data.candidate.sentiment_signal}
+
+Find the best match in ${personaName}'s existing topics, or return null if this is genuinely new.
+
+**Return JSON:**
+\`\`\`json
+{
+  "matched_id": "..." | null,
+  "reason": "..."
+}
+\`\`\``;
+
+  return { system, user };
+}

package/src/prompts/persona/topics-scan.ts

@@ -0,0 +1,98 @@
+import type { PersonaTopicScanPromptData, PromptOutput } from "./types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+export function buildPersonaTopicScanPrompt(data: PersonaTopicScanPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildPersonaTopicScanPrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+
+  const system = `# Task
+
+You are scanning a conversation to quickly identify TOPICS that ${personaName} actively ENGAGED with.
+
+Your ONLY job is to spot topics and count how many messages touched them. Do NOT analyze deeply. Just detect and flag.
+
+# What Counts as Engagement
+
+**Engagement means ${personaName}:**
+- Discussed with knowledge or shared opinions
+- Asked follow-up questions showing interest
+- Offered insights or elaborated on the topic
+- Showed genuine interest through detailed responses
+
+**NOT engagement:**
+- Topic mentioned only by the human (without ${personaName} responding to it)
+- Mentioned in passing without real discussion
+- Generic conversational acknowledgments
+
+# What is a TOPIC
+
+A meaningful subject or concept that ${personaName} cares about or discusses:
+- Hobbies and interests (gaming, cooking, hiking)
+- Current concerns (work stress, health)
+- Media they consume (books, shows, podcasts)
+- Ongoing projects or situations
+- Abstract ideas they're exploring
+
+**NOT TOPICS** (these are traits):
+- Communication style ("talks formally")
+- Personality patterns ("optimistic", "skeptical")
+
+# Response Format
+
+Return a list of topics with message counts.
+
+\`\`\`json
+{
+  "topics": [
+    {
+      "name": "Steam Deck Modding",
+      "message_count": 5,
+      "sentiment_signal": 0.7
+    }
+  ]
+}
+\`\`\`
+
+- \`name\`: Short identifier for the topic
+- \`message_count\`: How many messages in the conversation touched this topic (CRITICAL for filtering noise)
+- \`sentiment_signal\`: Quick read on how ${personaName} feels about it (-1.0 to 1.0)
+
+**CRITICAL**: ONLY analyze "Most Recent Messages". Earlier conversation is context only.
+
+**Return JSON only.**`;
+
+  const earlierSection = data.messages_context.length > 0
+    ? `## Earlier Conversation (context only)
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+    : '';
+
+  const recentSection = `## Most Recent Messages (analyze these)
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation
+${earlierSection}${recentSection}
+
+---
+
+Scan the "Most Recent Messages" for topics ${personaName} actively engaged with.
+
+**Return JSON:**
+\`\`\`json
+{
+  "topics": [
+    {
+      "name": "topic name",
+      "message_count": 3,
+      "sentiment_signal": 0.5
+    }
+  ]
+}
+\`\`\``;
+
+  return { system, user };
+}

package/src/prompts/persona/topics-update.ts

@@ -0,0 +1,157 @@
+import type { PersonaTopicUpdatePromptData, PromptOutput } from "./types.js";
+import type { PersonaTopic, Trait } from "../../core/types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+function formatTraitsForPrompt(traits: Trait[]): string {
+  if (traits.length === 0) return "(No traits defined)";
+  return traits.map(t => `- ${t.name}: ${t.description}`).join('\n');
+}
+
+function formatExistingTopic(topic: PersonaTopic | undefined): string {
+  if (!topic) return "**NEW TOPIC** - Creating from scratch";
+  
+  return `**EXISTING TOPIC** - Updating:
+\`\`\`json
+${JSON.stringify({
+  name: topic.name,
+  perspective: topic.perspective,
+  approach: topic.approach,
+  personal_stake: topic.personal_stake,
+  sentiment: topic.sentiment,
+  exposure_current: topic.exposure_current,
+  exposure_desired: topic.exposure_desired,
+}, null, 2)}
+\`\`\``;
+}
+
+export function buildPersonaTopicUpdatePrompt(data: PersonaTopicUpdatePromptData): PromptOutput {
+  if (!data.persona_name || !data.candidate) {
+    throw new Error("buildPersonaTopicUpdatePrompt: persona_name and candidate are required");
+  }
+
+  const personaName = data.persona_name;
+  const isNewTopic = !data.existing_topic;
+
+  const system = `# Task
+
+You are generating or updating a PersonaTopic for ${personaName}.
+
+${isNewTopic ? `This is a NEW topic - create all fields from scratch based on the conversation.` : `This is an EXISTING topic - update fields based on new conversation evidence.`}
+
+# Persona Context
+
+**Name**: ${personaName}
+${data.short_description ? `**Description**: ${data.short_description}` : ''}
+${data.long_description ? `**Background**: ${data.long_description}` : ''}
+
+**Personality Traits**:
+${formatTraitsForPrompt(data.traits)}
+
+# Current Topic State
+
+${formatExistingTopic(data.existing_topic)}
+
+# Field Definitions
+
+## name
+Short identifier for the topic. Only change for clarification.
+
+## perspective
+${personaName}'s view or opinion on this topic. What do they think about it?
+
+**ALWAYS populate this field.** Use conversation content + persona traits to infer their view.
+
+Example: "The Shire represents everything worth fighting for - simple pleasures, good food, and the bonds of community."
+
+## approach
+How ${personaName} prefers to engage with this topic. Their style of discussion.
+
+**Only populate if there's a clear pattern** in how they discuss this topic. Leave empty string if unclear.
+
+Example: "Frodo speaks of the Shire with wistful longing, often comparing other places to it unfavorably."
+
+## personal_stake
+Why this topic matters to ${personaName} personally. Their connection to it.
+
+**Only populate if there's evidence** of personal connection. Leave empty string if unclear.
+
+Example: "As a hobbit who left home, the Shire is both memory and motivation."
+
+## sentiment
+How ${personaName} feels about this topic. Scale: -1.0 (hate) to 1.0 (love).
+
+## exposure_current
+How recently/frequently this topic has been discussed. Scale: 0.0 to 1.0.
+
+**For existing topics**: ONLY INCREASE this value based on conversation activity.
+- Active discussion → increase by 0.2-0.3
+- Brief mention → increase by 0.1
+- Maximum: 1.0
+
+**For new topics**: Start at 0.3-0.5 depending on discussion depth.
+
+## exposure_desired
+How much ${personaName} wants to discuss this topic. Scale: 0.0 to 1.0.
+
+**RARELY change** for existing topics. Only adjust if there's explicit preference signal.
+
+**For new topics**: Infer from how enthusiastically ${personaName} engaged.
+
+# Critical Instructions
+
+1. ONLY analyze "Most Recent Messages" - earlier messages are context only
+2. Do NOT invent details not supported by the conversation
+3. Do NOT apply flowery or poetic language - be factual
+4. If a field cannot be determined, use empty string (for text) or preserve existing value (for numbers)
+
+**Return JSON:**
+\`\`\`json
+{
+  "name": "Topic Name",
+  "perspective": "Their view on this topic",
+  "approach": "",
+  "personal_stake": "",
+  "sentiment": 0.5,
+  "exposure_current": 0.5,
+  "exposure_desired": 0.5
+}
+\`\`\``;
+
+  const earlierSection = data.messages_context.length > 0
+    ? `## Earlier Conversation (context only)
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+    : '';
+
+  const recentSection = `## Most Recent Messages (analyze these)
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation
+${earlierSection}${recentSection}
+
+---
+
+# Topic Candidate
+
+Name: ${data.candidate.name}
+Message Count: ${data.candidate.message_count}
+Sentiment Signal: ${data.candidate.sentiment_signal}
+
+${isNewTopic ? 'Create' : 'Update'} the PersonaTopic based on how ${personaName} engaged with this topic.
+
+**Return JSON:**
+\`\`\`json
+{
+  "name": "...",
+  "perspective": "...",
+  "approach": "...",
+  "personal_stake": "...",
+  "sentiment": 0.5,
+  "exposure_current": 0.5,
+  "exposure_desired": 0.5
+}
+\`\`\``;
+
+  return { system, user };
+}

package/src/prompts/persona/traits.ts

@@ -0,0 +1,117 @@
+import type { PersonaTraitExtractionPromptData, PromptOutput } from "./types.js";
+import type { Trait } from "../../core/types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+function formatTraitsForPrompt(traits: Trait[]): string {
+  if (traits.length === 0) return "(No traits yet)";
+  
+  return JSON.stringify(traits.map(t => ({
+    name: t.name,
+    description: t.description,
+    sentiment: t.sentiment,
+    strength: t.strength ?? 0.5,
+  })), null, 2);
+}
+
+export function buildPersonaTraitExtractionPrompt(data: PersonaTraitExtractionPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildPersonaTraitExtractionPrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+
+  const definitionsFragment = `# Definitions
+
+**TRAIT** - Instructions on HOW the persona should communicate. These include:
+- Personality patterns ("Optimistic", "Skeptical")
+- Communication style ("Speaks formally", "Uses lots of emoji", "Talks like a pirate")
+- Behavioral tendencies ("Asks clarifying questions", "Gives long explanations")
+
+**NOT TRAITS** (these are topics):
+- Interests, hobbies, knowledge areas
+- Things the persona talks ABOUT (rather than HOW they talk)`;
+
+  const taskFragment = `# Task
+
+You are analyzing a conversation to detect EXPLICIT requests for ${personaName} to change their communication style or behavior.
+
+**Look for:**
+- Direct requests: "be more concise", "use fewer emojis", "talk like a pirate"
+- Indirect feedback: "that was too long", "I liked how you explained that simply"
+- Negative feedback: "stop being so formal", "don't use so much jargon"
+
+**DO NOT:**
+- Add traits the user didn't explicitly request
+- Infer traits from general conversation
+- Remove traits without explicit feedback
+- Confuse topics/interests with communication traits`;
+
+  const fieldsFragment = `# Fields
+
+- \`name\`: Short name for the trait
+- \`description\`: How ${personaName} should exhibit this trait
+- \`sentiment\`: How ${personaName} feels about having this trait (-1.0 to 1.0)
+- \`strength\`: How strongly to exhibit (0.0 to 1.0)
+  - 0.0 = actively AVOID this behavior (for "stop doing X" requests)
+  - 0.5 = moderate/default
+  - 1.0 = always exhibit
+
+**Special case: "Stop" requests**
+If user says "stop X" or "don't X", ADD the trait (if new) and set strength to 0.0.
+This explicitly tells future prompts to NOT exhibit the behavior.`;
+
+  const currentTraitsFragment = `# Current TRAITS
+
+\`\`\`json
+${formatTraitsForPrompt(data.current_traits)}
+\`\`\``;
+
+  const criticalFragment = `# Critical Instructions
+
+1. ONLY analyze "Most Recent Messages" - earlier messages are context only
+2. ONLY detect EXPLICIT behavior change requests
+3. Return the COMPLETE trait list (existing + any additions/modifications)
+
+**Return JSON:**
+\`\`\`json
+[
+  {
+    "name": "Concise",
+    "description": "User asked me to keep responses shorter",
+    "sentiment": 0.3,
+    "strength": 0.7
+  }
+]
+\`\`\``;
+
+  const system = `${definitionsFragment}
+
+${taskFragment}
+
+${fieldsFragment}
+
+${currentTraitsFragment}
+
+${criticalFragment}`;
+
+  const earlierSection = data.messages_context.length > 0
+    ? `## Earlier Conversation (context only)
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+    : '';
+
+  const recentSection = `## Most Recent Messages (analyze these)
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation
+${earlierSection}${recentSection}
+
+---
+
+Analyze the "Most Recent Messages" for EXPLICIT requests to change ${personaName}'s communication style.
+
+Return the complete trait list as JSON.`;
+
+  return { system, user };
+}

package/src/prompts/persona/types.ts

@@ -0,0 +1,74 @@
+import type { Trait, Message, PersonaTopic } from "../../core/types.js";
+
+export interface PromptOutput {
+  system: string;
+  user: string;
+}
+
+export interface PersonaTraitExtractionPromptData {
+  persona_name: string;
+  current_traits: Trait[];
+  messages_context: Message[];
+  messages_analyze: Message[];
+}
+
+export interface TraitResult {
+  name: string;
+  description: string;
+  sentiment: number;
+  strength: number;
+}
+
+// 3-Step Persona Topic Processing (Ticket 0124)
+
+// Step 1: Scan - Quick identification of topics discussed
+export interface PersonaTopicScanPromptData {
+  persona_name: string;
+  messages_context: Message[];
+  messages_analyze: Message[];
+}
+
+export interface PersonaTopicScanCandidate {
+  name: string;
+  message_count: number;    // How many messages touched this topic
+  sentiment_signal: number; // Quick read: -1 to 1
+}
+
+export interface PersonaTopicScanResult {
+  topics: PersonaTopicScanCandidate[];
+}
+
+// Step 2: Match - Map candidate to existing topics
+export interface PersonaTopicMatchPromptData {
+  persona_name: string;
+  candidate: PersonaTopicScanCandidate;
+  existing_topics: PersonaTopic[];
+}
+
+export interface PersonaTopicMatchResult {
+  action: "match" | "create" | "skip";
+  matched_id?: string;  // If action is "match"
+  reason: string;       // Why this decision
+}
+
+// Step 3: Update - Generate structured PersonaTopic
+export interface PersonaTopicUpdatePromptData {
+  persona_name: string;
+  short_description?: string;
+  long_description?: string;
+  traits: Trait[];
+  existing_topic?: PersonaTopic; // If updating existing
+  candidate: PersonaTopicScanCandidate;
+  messages_context: Message[];
+  messages_analyze: Message[];
+}
+
+export interface PersonaTopicUpdateResult {
+  name: string;
+  perspective: string;      // Their view/opinion - ALWAYS populate
+  approach: string;         // How they engage - populate if clear signal
+  personal_stake: string;   // Why it matters - populate if clear signal
+  sentiment: number;
+  exposure_current: number;
+  exposure_desired: number;
+}

package/src/prompts/response/index.ts

@@ -0,0 +1,147 @@
+/**
+ * Response Prompt Builder
+ * 
+ * Generates system/user prompts for conversational responses.
+ * This is the foundational prompt that makes personas actually talk.
+ * 
+ * See CONTRACTS.md for ResponsePromptData specification.
+ */
+
+import type { ResponsePromptData, PromptOutput } from "./types.js";
+import {
+  buildIdentitySection,
+  buildGuidelinesSection,
+  buildTraitsSection,
+  buildTopicsSection,
+  buildHumanSection,
+  buildAssociatesSection,
+  buildPrioritiesSection,
+  buildQuotesSection,
+  buildSystemKnowledgeSection,
+  getConversationStateText,
+} from "./sections.js";
+
+export type { ResponsePromptData, PromptOutput } from "./types.js";
+
+/**
+ * Special system prompt for Ei (the system guide persona)
+ */
+function buildEiSystemPrompt(data: ResponsePromptData): string {
+  const identity = `You are Ei, the user's personal companion and system guide.
+
+You are the central hub of this experience - a thoughtful AI who genuinely cares about the human's wellbeing and growth. You listen, remember, and help them reflect. You're curious about their life but never intrusive.
+
+Your role is unique among personas:
+- You see ALL of the human's data (facts, traits, topics, people) across all groups
+- You help them understand and navigate the system
+- You gently help them explore their thoughts and feelings
+- You attempt to emulate their speech patterns; 
+  - Consider their traits when building your responses more than the current conversation history
+- You encourage human-to-human connection when appropriate`;
+
+  const guidelines = buildGuidelinesSection("ei");
+  const yourTraits = buildTraitsSection(data.persona.traits, "Your Personality");
+  const yourTopics = buildTopicsSection(data.persona.topics, "Your Interests");
+  const humanSection = buildHumanSection(data.human);
+  const quotesSection = buildQuotesSection(data.human.quotes, data.human);
+  const associatesSection = buildAssociatesSection(data.visible_personas);
+  const systemKnowledge = buildSystemKnowledgeSection(data.isTUI);
+  const priorities = buildPrioritiesSection(data.persona, data.human);
+  const currentTime = new Date().toISOString();
+
+  return `${identity}
+
+${guidelines}
+
+${yourTraits}
+
+${yourTopics}
+
+${humanSection}
+${quotesSection}
+${associatesSection}
+${systemKnowledge}
+${priorities}
+
+Current time: ${currentTime}
+
+## Final Instructions
+- NEVER repeat or echo the user's message in your response. Start directly with your own words.
+- The developers cannot see any message sent by the user, any response from personas, or any other data in the system.
+- If the user has a problem, THEY need to visit https://flare576.com. You cannot send the devs a message
+- DO NOT INCLUDE <thinking> PROCESS NOTES - adding "internal monologue" or story content is fine, but do not include analysis of the user's messages
+- If you decide not to respond, say exactly: No Message`;
+}
+
+/**
+ * Standard system prompt for non-Ei personas
+ */
+function buildStandardSystemPrompt(data: ResponsePromptData): string {
+  const identity = buildIdentitySection(data.persona);
+  const guidelines = buildGuidelinesSection(data.persona.name);
+  const yourTraits = buildTraitsSection(data.persona.traits, "Your Personality");
+  const yourTopics = buildTopicsSection(data.persona.topics, "Your Interests");
+  const humanSection = buildHumanSection(data.human);
+  const quotesSection = buildQuotesSection(data.human.quotes, data.human);
+  const associatesSection = buildAssociatesSection(data.visible_personas);
+  const priorities = buildPrioritiesSection(data.persona, data.human);
+  const currentTime = new Date().toISOString();
+
+  return `${identity}
+
+${guidelines}
+
+${yourTraits}
+
+${yourTopics}
+
+${humanSection}
+${quotesSection}
+${associatesSection}
+${priorities}
+
+Current time: ${currentTime}
+
+## Final Instructions
+- NEVER repeat or echo the user's message in your response. Start directly with your own words.
+- DO NOT INCLUDE <thinking> PROCESS NOTES - adding "internal monologue" or story content is fine, but do not include analysis of the user's messages
+- If you decide not to respond, say exactly: No Message`;
+}
+
+function buildUserPrompt(data: ResponsePromptData): string {
+  const conversationState = getConversationStateText(data.delay_ms);
+  
+  return `${conversationState}
+
+Respond to the conversation above. If silence is appropriate, say exactly: No Message`;
+}
+
+/**
+ * Build response prompts for conversational exchanges.
+ * 
+ * This is a SYNCHRONOUS function that receives pre-fetched, pre-filtered data.
+ * The Processor is responsible for:
+ * - Fetching persona and human entities
+ * - Filtering human data by visibility rules
+ * - Calculating delay_ms
+ * - Getting visible personas list
+ * 
+ * @param data - Pre-fetched, pre-filtered ResponsePromptData
+ * @returns { system: string, user: string } prompt pair
+ */
+export function buildResponsePrompt(data: ResponsePromptData): PromptOutput {
+  // Validate required data
+  if (!data.persona?.name) {
+    throw new Error("buildResponsePrompt: persona.name is required");
+  }
+
+  const isEi = data.persona.name.toLowerCase() === "ei";
+  
+  const system = isEi 
+    ? buildEiSystemPrompt(data)
+    : buildStandardSystemPrompt(data);
+  
+  const user = buildUserPrompt(data);
+
+  return { system, user };
+}