ei-tui 0.1.3

package/src/integrations/opencode/types.ts

@@ -0,0 +1,244 @@
+/**
+ * OpenCode Integration Types
+ *
+ * These types represent the data structures read from OpenCode's storage.
+ * They are based on the actual file format in ~/.local/share/opencode/storage/
+ * and the SQLite database in ~/.local/share/opencode/opencode.db (1.2+)
+ */
+
+// ============================================================================
+// Reader Interface
+// ============================================================================
+
+/**
+ * Common interface for reading OpenCode data.
+ * Implemented by both JsonReader (legacy) and SqliteReader (1.2+).
+ */
+export interface IOpenCodeReader {
+  getSessionsUpdatedSince(since: Date): Promise<OpenCodeSession[]>;
+  getSessionsInRange(from: Date, to: Date): Promise<OpenCodeSession[]>;
+  getMessagesForSession(sessionId: string, since?: Date): Promise<OpenCodeMessage[]>;
+  getAgentInfo(agentName: string): Promise<OpenCodeAgent | null>;
+  getAllUniqueAgents(sessionId: string): Promise<string[]>;
+  getFirstAgent(sessionId: string): Promise<string | null>;
+}
+
+// ============================================================================
+// Session Types (storage/session/{project_hash}/ses_xxx.json)
+// ============================================================================
+
+/**
+ * Raw session data as stored by OpenCode
+ */
+export interface OpenCodeSessionRaw {
+  id: string; // ses_xxx
+  slug: string;
+  version: string;
+  projectID: string; // git root commit hash or "global"
+  directory: string; // Full path to project
+  parentID?: string; // Parent session ID if this is a subagent session
+  title: string;
+  time: {
+    created: number; // Unix timestamp ms
+    updated: number; // Unix timestamp ms
+    archived?: number; // Only set by web app
+  };
+  summary?: {
+    additions: number;
+    deletions: number;
+    files: number;
+  };
+}
+
+/**
+ * Cleaned session data for Ei consumption
+ */
+export interface OpenCodeSession {
+  id: string; // ses_xxx
+  title: string;
+  directory: string;
+  projectId: string;
+  parentId?: string;
+  time: {
+    created: number;
+    updated: number;
+  };
+}
+
+// ============================================================================
+// Message Types (storage/message/{session_id}/msg_xxx.json)
+// ============================================================================
+
+/**
+ * Raw message data as stored by OpenCode
+ */
+export interface OpenCodeMessageRaw {
+  id: string; // msg_xxx
+  sessionID: string;
+  role: "user" | "assistant";
+  time: {
+    created: number;
+    completed?: number;
+  };
+  agent: string; // "build", "sisyphus", "librarian", etc.
+  parentID?: string;
+  model?: {
+    providerID: string;
+    modelID: string;
+  };
+  modelID?: string;
+  providerID?: string;
+  mode?: string;
+  cost?: number;
+  tokens?: {
+    input: number;
+    output: number;
+    reasoning: number;
+    cache?: {
+      read: number;
+      write: number;
+    };
+  };
+  finish?: string;
+}
+
+/**
+ * Cleaned message data for Ei consumption
+ */
+export interface OpenCodeMessage {
+  id: string; // msg_xxx
+  sessionId: string;
+  role: "user" | "assistant";
+  agent: string;
+  content: string; // Filtered, concatenated text parts
+  timestamp: string; // ISO string from time.created
+}
+
+// ============================================================================
+// Part Types (storage/part/{msg_id}/prt_xxx.json)
+// ============================================================================
+
+/**
+ * Raw part data as stored by OpenCode
+ * Parts can be of various types, but we only care about text parts
+ */
+export interface OpenCodePartRaw {
+  id: string; // prt_xxx
+  sessionID: string;
+  messageID: string;
+  type: "text" | "tool" | "file" | "step-start" | "step-finish" | string;
+  text?: string; // Only present for type="text"
+  synthetic?: boolean; // true = tool call summary, skip
+  time?: {
+    start: number;
+    end: number;
+  };
+}
+
+// ============================================================================
+// Agent Types
+// ============================================================================
+
+/**
+ * Agent info for persona creation
+ */
+export interface OpenCodeAgent {
+  name: string;
+  description?: string;
+}
+
+/**
+ * Utility agents that should not have personas created for them.
+ * These are internal agents that do housekeeping tasks.
+ */
+export const UTILITY_AGENTS = ["compaction", "title", "summary"] as const;
+
+/**
+ * Message content prefixes that indicate agent-to-agent communication.
+ * Messages starting with these should be filtered out during import.
+ */
+export const AGENT_TO_AGENT_PREFIXES = [
+  "[search-mode]",
+  "[analyze-mode]",
+  "[CONTEXT]",
+  "<analysis>",
+  "<results>",
+] as const;
+
+/**
+ * Agent name aliases for consolidating variants into a single persona.
+ * OpenCode's plugin ecosystem results in the same logical agent having
+ * different names across versions/configs (e.g., "sisyphus", "Sisyphus",
+ * "Sisyphus (Ultraworker)", "Planner-Sisyphus" are all the same agent).
+ * 
+ * Key = canonical name (used for display_name, Title Case)
+ * Value = array of variants that should resolve to this persona
+ */
+export const AGENT_ALIASES: Record<string, string[]> = {
+  Sisyphus: [
+    "sisyphus",
+    "Sisyphus",
+    "Sisyphus (Ultraworker)",
+    "Planner-Sisyphus",
+    "planner-sisyphus",
+  ],
+};
+
+/**
+ * Built-in agent definitions (fallback when config unavailable)
+ */
+export const BUILTIN_AGENTS: Record<string, OpenCodeAgent> = {
+  build: {
+    name: "build",
+    description: "The main coding agent that implements features and fixes bugs",
+  },
+  sisyphus: {
+    name: "sisyphus",
+    description: "Powerful AI Agent with orchestration capabilities",
+  },
+  plan: {
+    name: "plan",
+    description: "Creates implementation plans for complex features",
+  },
+  general: {
+    name: "general",
+    description: "General purpose assistant for non-coding tasks",
+  },
+  explore: {
+    name: "explore",
+    description: "Explores codebases to understand structure and patterns",
+  },
+  librarian: {
+    name: "librarian",
+    description:
+      "Searches external references including documentation and open source examples",
+  },
+  compaction: {
+    name: "compaction",
+    description: "Compacts conversation history to save context",
+  },
+  title: {
+    name: "title",
+    description: "Generates session titles",
+  },
+  summary: {
+    name: "summary",
+    description: "Generates session summaries",
+  },
+  oracle: {
+    name: "oracle",
+    description: "High-IQ read-only consultant for architecture and debugging",
+  },
+  atlas: {
+    name: "atlas",
+    description: "Task execution agent for delegated work",
+  },
+  metis: {
+    name: "metis",
+    description: "Pre-planning consultant for scope clarification",
+  },
+  momus: {
+    name: "momus",
+    description: "Expert reviewer for evaluating work plans",
+  },
+};

package/src/prompts/AGENTS.md

@@ -0,0 +1,62 @@
+# Prompts Module
+
+LLM prompt builders. All prompts are **synchronous** and **pure**.
+
+## Structure
+
+```
+prompts/
+├── index.ts           # Re-exports all builders
+├── message-utils.ts   # Format messages for context
+├── ceremony/          # Exposure decay, persona enrichment
+├── generation/        # New persona creation
+├── heartbeat/         # Periodic check-ins
+├── human/             # Fact/trait/topic/person extraction
+├── persona/           # Persona trait extraction, topic matching
+├── response/          # Main conversation responses
+└── validation/        # Data validation prompts
+```
+
+## Pattern
+
+Every prompt builder follows this contract:
+
+```typescript
+interface PromptBuilder<T> {
+  (data: T): { system: string; user: string }
+}
+```
+
+**Rules**:
+1. **Synchronous** - No async, no fetching
+2. **Pure** - Same input → same output
+3. **Pre-processed data** - Processor fetches/filters before calling
+4. **Minimal logic** - String interpolation, not computation
+
+## Adding New Prompts
+
+1. Create directory: `prompts/[purpose]/`
+2. Create files:
+   - `types.ts` - Input data interface
+   - `sections.ts` - Reusable prompt fragments
+   - `index.ts` - Builder function + exports
+3. Export from `prompts/index.ts`
+4. Call from Processor with pre-fetched data
+
+## Subdirectories
+
+| Directory | Purpose | Key Output |
+|-----------|---------|------------|
+| `response/` | Generate persona replies | Conversational text |
+| `human/` | Extract facts/traits/topics/people | JSON arrays |
+| `persona/` | Extract persona traits, match topics | JSON |
+| `generation/` | Create new personas | PersonaEntity JSON |
+| `ceremony/` | Exposure decay prompts | Updated values |
+| `heartbeat/` | Check if persona should speak | Boolean-ish |
+| `validation/` | Verify extracted data | Confirmation |
+
+## Key Insight
+
+**Prompt engineering lives here. Code logic lives in Processor.**
+
+When modifying persona behavior, check prompts first—the "personality" is in the English, not the TypeScript.

package/src/prompts/ceremony/description-check.ts

@@ -0,0 +1,47 @@
+import type { DescriptionCheckPromptData } from "./types.js";
+
+export function buildDescriptionCheckPrompt(data: DescriptionCheckPromptData): { system: string; user: string } {
+  const traitList = data.traits.length > 0
+    ? data.traits.map(t => `- ${t.name}: ${t.description}`).join("\n")
+    : "No traits defined";
+
+  const topicList = data.topics.length > 0
+    ? data.topics.map(t => `- ${t.name}: ${t.perspective} (exposure: ${t.exposure_current.toFixed(2)})`).join("\n")
+    : "No topics defined";
+
+  const system = `You are evaluating whether a persona's description needs updating.
+
+A description should ONLY be updated if there is a SIGNIFICANT mismatch between:
+- The current description
+- The persona's current traits and topics
+
+Be VERY conservative. Only recommend updating if:
+- The description mentions interests/traits that are completely absent from current data
+- The persona has developed major new interests not reflected in the description
+- The description actively contradicts the current personality
+
+Do NOT recommend updating for:
+- Minor differences or evolution
+- Natural topic drift over time
+- Missing details that aren't contradictions
+
+Return JSON: { "should_update": true/false, "reason": "explanation" }`;
+
+  const user = `Persona: ${data.persona_name}
+
+Current short description:
+${data.current_short_description ?? "(none)"}
+
+Current long description:
+${data.current_long_description ?? "(none)"}
+
+Current personality traits:
+${traitList}
+
+Current topics of interest:
+${topicList}
+
+Does this persona's description need updating based on their current traits and topics?`;
+
+  return { system, user };
+}

package/src/prompts/ceremony/expire.ts

@@ -0,0 +1,30 @@
+import type { PersonaExpirePromptData } from "./types.js";
+
+export function buildPersonaExpirePrompt(data: PersonaExpirePromptData): { system: string; user: string } {
+  const topicList = data.topics.map(t => {
+    const display = t.perspective || t.name;
+    return `- "${t.name}" (exposure: ${t.exposure_current.toFixed(2)}, sentiment: ${t.sentiment.toFixed(2)})\n  Perspective: ${display}`;
+  }).join("\n");
+
+  const system = `You are evaluating which topics a persona should stop caring about.
+
+A topic should be removed if:
+- Its exposure_current is very low (< 0.15) indicating prolonged disinterest
+- It no longer aligns with the persona's current interests
+- It was a temporary interest that has faded
+
+Be conservative - only suggest removing topics that are clearly irrelevant.
+If unsure, keep the topic.
+
+Return JSON: { "topic_ids_to_remove": ["id1", "id2"] }
+Return empty array if no topics should be removed.`;
+
+  const user = `Persona: ${data.persona_name}
+
+Current topics:
+${topicList}
+
+Which topics, if any, should this persona stop caring about?`;
+
+  return { system, user };
+}

package/src/prompts/ceremony/explore.ts

@@ -0,0 +1,60 @@
+import type { PersonaExplorePromptData } from "./types.js";
+
+export function buildPersonaExplorePrompt(data: PersonaExplorePromptData): { system: string; user: string } {
+  const traitList = data.traits.map(t => 
+    `- ${t.name}: ${t.description} (strength: ${t.strength?.toFixed(2) ?? "N/A"})`
+  ).join("\n");
+
+  const topicList = data.remaining_topics.map(t => 
+    `- ${t.name}: ${t.perspective || t.name}`
+  ).join("\n");
+
+  const themeList = data.recent_conversation_themes.length > 0
+    ? data.recent_conversation_themes.map(t => `- ${t}`).join("\n")
+    : "No recent themes identified";
+
+  const system = `You are generating new conversation topics for a persona.
+
+Topics should:
+- Align with the persona's traits and personality
+- Complement (not duplicate) existing topics
+- Be natural extensions of recent conversation themes
+- Be specific enough to drive interesting conversations
+
+Generate 1-3 new topics that this persona would genuinely care about.
+
+Return JSON:
+{
+  "new_topics": [{
+    "name": "Topic Name",
+    "perspective": "The persona's view or opinion on this topic",
+    "approach": "How they prefer to engage with this topic",
+    "personal_stake": "Why this topic matters to them personally",
+    "sentiment": 0.5,
+    "exposure_current": 0.2,
+    "exposure_desired": 0.6
+  }]
+}
+
+**Field guidance:**
+- perspective: REQUIRED - their actual view/opinion
+- approach: Optional if unclear - how they discuss this topic
+- personal_stake: Optional if unclear - why it matters to them
+- exposure_current: Low (0.2) since these are new topics
+- exposure_desired: How much the persona would want to discuss this`;
+
+  const user = `Persona: ${data.persona_name}
+
+Personality traits:
+${traitList}
+
+Current topics (do not duplicate):
+${topicList}
+
+Recent conversation themes:
+${themeList}
+
+Generate new topics this persona would care about.`;
+
+  return { system, user };
+}

package/src/prompts/ceremony/index.ts

@@ -0,0 +1,11 @@
+export { buildPersonaExpirePrompt } from "./expire.js";
+export { buildPersonaExplorePrompt } from "./explore.js";
+export { buildDescriptionCheckPrompt } from "./description-check.js";
+export type {
+  PersonaExpirePromptData,
+  PersonaExpireResult,
+  PersonaExplorePromptData,
+  PersonaExploreResult,
+  DescriptionCheckPromptData,
+  DescriptionCheckResult,
+} from "./types.js";

package/src/prompts/ceremony/types.ts

@@ -0,0 +1,42 @@
+import type { Trait, PersonaTopic } from "../../core/types.js";
+
+export interface PersonaExpirePromptData {
+  persona_name: string;
+  topics: PersonaTopic[];
+}
+
+export interface PersonaExpireResult {
+  topic_ids_to_remove: string[];
+}
+
+export interface PersonaExplorePromptData {
+  persona_name: string;
+  traits: Trait[];
+  remaining_topics: PersonaTopic[];
+  recent_conversation_themes: string[];
+}
+
+export interface PersonaExploreResult {
+  new_topics: Array<{
+    name: string;
+    perspective: string;
+    approach: string;
+    personal_stake: string;
+    sentiment: number;
+    exposure_current: number;
+    exposure_desired: number;
+  }>;
+}
+
+export interface DescriptionCheckPromptData {
+  persona_name: string;
+  current_short_description?: string;
+  current_long_description?: string;
+  traits: Trait[];
+  topics: PersonaTopic[];
+}
+
+export interface DescriptionCheckResult {
+  should_update: boolean;
+  reason?: string;
+}

package/src/prompts/generation/descriptions.ts

@@ -0,0 +1,91 @@
+import type { PersonaDescriptionsPromptData, PromptOutput } from "./types.js";
+import type { Trait, PersonaTopic } from "../../core/types.js";
+
+function formatTraitsForPrompt(traits: Trait[]): string {
+  if (traits.length === 0) return "(No traits defined)";
+  
+  return traits.map(t => {
+    const strength = t.strength !== undefined ? ` (strength: ${t.strength.toFixed(1)})` : "";
+    return `- **${t.name}**${strength}: ${t.description}`;
+  }).join('\n');
+}
+
+function formatTopicsForPrompt(topics: PersonaTopic[]): string {
+  if (topics.length === 0) return "(No topics defined)";
+  
+  return topics.map(t => {
+    const sentiment = t.sentiment > 0.3 ? "enjoys" : t.sentiment < -0.3 ? "dislikes" : "neutral";
+    return `- **${t.name}** (${sentiment}): ${t.perspective || t.name}`;
+  }).join('\n');
+}
+
+export function buildPersonaDescriptionsPrompt(data: PersonaDescriptionsPromptData): PromptOutput {
+  if (!data.name) {
+    throw new Error("buildPersonaDescriptionsPrompt: name is required");
+  }
+
+  const taskFragment = `You are regenerating descriptions for an existing AI persona named "${data.name}".
+
+Their traits and topics have evolved, and the descriptions may no longer accurately represent who they are.
+
+**Important**: Only change descriptions if there's a significant mismatch. If the current descriptions still fit, return \`{ "no_change": true }\`.`;
+
+  const currentStateFragment = `## Current State
+
+### Aliases
+${data.aliases.length > 0 ? data.aliases.join(", ") : "(None)"}
+
+### Traits
+${formatTraitsForPrompt(data.traits)}
+
+### Topics
+${formatTopicsForPrompt(data.topics)}`;
+
+  const guidelinesFragment = `## Guidelines
+
+**When to change:**
+- Traits/topics have shifted significantly from the original concept
+- Current descriptions mention things that are no longer true
+- The persona's core identity has evolved
+
+**When NOT to change:**
+- Descriptions are still accurate even if incomplete
+- Changes are minor refinements
+- Original descriptions capture the essence well
+
+**If changing:**
+- short_description: 10-15 words capturing the essence
+- long_description: 2-3 sentences describing personality, interests, approach
+- Preserve the persona's core identity while reflecting evolution`;
+
+  const schemaFragment = `## Response Format
+
+If descriptions should change:
+\`\`\`json
+{
+  "short_description": "New short description here",
+  "long_description": "New long description here."
+}
+\`\`\`
+
+If descriptions are still accurate:
+\`\`\`json
+{
+  "no_change": true
+}
+\`\`\``;
+
+  const system = `${taskFragment}
+
+${currentStateFragment}
+
+${guidelinesFragment}
+
+${schemaFragment}`;
+
+  const user = `Based on the traits and topics above, should ${data.name}'s descriptions be updated?
+
+Remember: Only change if there's a significant mismatch. Stability is preferred.`;
+
+  return { system, user };
+}

package/src/prompts/generation/index.ts

@@ -0,0 +1,15 @@
+export { buildPersonaGenerationPrompt } from "./persona.js";
+export { buildPersonaDescriptionsPrompt } from "./descriptions.js";
+export {
+  DEFAULT_SEED_TRAITS,
+  SEED_TRAIT_GENUINE,
+  SEED_TRAIT_NATURAL_SPEECH,
+  type SeedTrait,
+} from "./seeds.js";
+export type {
+  PersonaGenerationPromptData,
+  PersonaGenerationResult,
+  PersonaDescriptionsPromptData,
+  PersonaDescriptionsResult,
+  PromptOutput,
+} from "./types.js";