mia-code 0.2.0

package/src/narrative/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Narrative Intelligence Integration for mia-code
+ * 
+ * Exports the core narrative intelligence components:
+ * - NarrativeRouter: Routes events to miaco/miatel/miawa based on three-universe analysis
+ * - MiaCodeTracer: Observability for mia-code operations
+ */
+
+// Router exports
+export {
+  NarrativeRouter,
+  getNarrativeRouter,
+  MiaCodeEvent,
+  RoutingResult,
+  UNIVERSE_TO_CLI,
+  CLI_TO_UNIVERSE,
+  Universe,
+  ThreeUniverseAnalysis,
+  StoryBeat,
+  NarrativeFunction,
+  EmotionalTone,
+  CoherenceResult,
+} from "./router.js";
+
+// Tracer exports
+export {
+  MiaCodeTracer,
+  getTracer,
+  removeTracer,
+  MiaCodeOperation,
+  NarrativeEventType,
+  NarrativeMetrics,
+} from "./tracer.js";

package/src/narrative/router.ts

@@ -0,0 +1,260 @@
+/**
+ * Narrative Intelligence Integration for mia-code
+ * 
+ * Bridges the three-universe model from @langchain/langgraph-narrative-intelligence (that I publish as : ava-langchain-narrative-tracing and not @langchain/langgraph-narrative-intelligence)
+ * to mia-code's miaco/miatel/miawa architecture.
+ * 
+ * Universe Mapping:
+ * - ENGINEER (Mia) → miaco (charts, technical precision)
+ * - CEREMONY (Ava8) → miawa (ceremonies, relational protocols)
+ * - STORY_ENGINE (Miette) → miatel (beats, narrative patterns)
+ */
+
+import {
+  ThreeUniverseProcessor,
+  NarrativeCoherenceEngine,
+  Universe,
+  ThreeUniverseAnalysis,
+  StoryBeat,
+  createStoryBeat,
+  NarrativeFunction,
+  CoherenceResult,
+  EmotionalTone,
+  classifyEmotionalTone,
+} from "ava-langgraph-narrative-intelligence";
+
+/**
+ * Maps universe to mia-code CLI
+ */
+export const UNIVERSE_TO_CLI: Record<Universe, string> = {
+  [Universe.ENGINEER]: "miaco",
+  [Universe.CEREMONY]: "miawa", 
+  [Universe.STORY_ENGINE]: "miatel",
+};
+
+/**
+ * Maps CLI to universe
+ */
+export const CLI_TO_UNIVERSE: Record<string, Universe> = {
+  miaco: Universe.ENGINEER,
+  miawa: Universe.CEREMONY,
+  miatel: Universe.STORY_ENGINE,
+};
+
+/**
+ * Mia-code event that can be analyzed through three universes
+ */
+export interface MiaCodeEvent {
+  id: string;
+  type: "user_input" | "agent_action" | "chart_update" | "beat_created" | "ceremony_action";
+  content: string;
+  source?: "miaco" | "miatel" | "miawa";
+  metadata?: Record<string, unknown>;
+  timestamp?: Date;
+}
+
+/**
+ * Result of routing decision
+ */
+export interface RoutingResult {
+  leadCli: "miaco" | "miatel" | "miawa";
+  leadUniverse: Universe;
+  analysis: ThreeUniverseAnalysis;
+  suggestedAction: string;
+  coherence: number;
+}
+
+/**
+ * NarrativeRouter - Routes events to the appropriate mia-code CLI
+ * based on three-universe analysis
+ */
+export class NarrativeRouter {
+  private processor: ThreeUniverseProcessor;
+  private coherenceEngine: NarrativeCoherenceEngine;
+  private beatHistory: StoryBeat[] = [];
+  private beatSequence: number = 0;
+
+  constructor() {
+    this.processor = new ThreeUniverseProcessor();
+    this.coherenceEngine = new NarrativeCoherenceEngine();
+  }
+
+  /**
+   * Analyze an event and determine the best CLI to handle it
+   */
+  route(event: MiaCodeEvent): RoutingResult {
+    // Convert to format expected by processor
+    const processedEvent = {
+      content: event.content,
+      type: event.type,
+      source: event.source,
+      ...event.metadata,
+    };
+
+    // Run three-universe analysis
+    const analysis = this.processor.process(processedEvent, this.mapEventType(event.type));
+
+    // Map lead universe to CLI
+    const leadCli = UNIVERSE_TO_CLI[analysis.leadUniverse] as "miaco" | "miatel" | "miawa";
+
+    // Determine suggested action based on analysis
+    const suggestedAction = this.deriveSuggestedAction(analysis);
+
+    return {
+      leadCli,
+      leadUniverse: analysis.leadUniverse,
+      analysis,
+      suggestedAction,
+      coherence: analysis.coherenceScore,
+    };
+  }
+
+  /**
+   * Record a story beat and update coherence tracking
+   */
+  recordBeat(content: string, cli: "miaco" | "miatel" | "miawa"): StoryBeat {
+    this.beatSequence++;
+    
+    // Classify emotional tone
+    const toneResult = classifyEmotionalTone(content);
+    
+    // Determine narrative function from content
+    const narrativeFunction = this.inferNarrativeFunction(content);
+    
+    // Map CLI to universe
+    const leadUniverse = CLI_TO_UNIVERSE[cli];
+
+    // Create the beat
+    const beat = createStoryBeat(
+      `beat_${this.beatSequence}`,
+      this.beatSequence,
+      content,
+      narrativeFunction,
+      Math.ceil(this.beatSequence / 10), // Rough act calculation
+      {
+        emotionalTone: toneResult.classification,
+        leadUniverse,
+      }
+    );
+
+    this.beatHistory.push(beat);
+    return beat;
+  }
+
+  /**
+   * Analyze coherence of accumulated beats
+   */
+  analyzeCoherence(): CoherenceResult | null {
+    if (this.beatHistory.length === 0) {
+      return null;
+    }
+    const result = this.coherenceEngine.analyze(this.beatHistory);
+    // Handle case where result is CoherenceEngineState
+    if ('coherenceScore' in result && result.coherenceScore) {
+      return result as CoherenceResult;
+    }
+    return null;
+  }
+
+  /**
+   * Get trinity assessment (Mia/Miette/Ava8 perspectives on quality)
+   */
+  getTrinityAssessment(): { mia: string; miette: string; ava8: string } | null {
+    const result = this.analyzeCoherence();
+    if (!result) return null;
+    return {
+      mia: result.trinityAssessment.mia,
+      miette: result.trinityAssessment.miette,
+      ava8: result.trinityAssessment.ava8,
+    };
+  }
+
+  /**
+   * Get gaps that need addressing
+   */
+  getGaps(): Array<{ type: string; severity: string; description: string }> {
+    const result = this.analyzeCoherence();
+    if (!result) return [];
+    return result.gaps.map(gap => ({
+      type: gap.gapType,
+      severity: gap.severity,
+      description: gap.description,
+    }));
+  }
+
+  /**
+   * Reset the router (clear beat history)
+   */
+  reset(): void {
+    this.beatHistory = [];
+    this.beatSequence = 0;
+  }
+
+  private mapEventType(type: MiaCodeEvent["type"]): string {
+    const mapping: Record<string, string> = {
+      user_input: "user.input",
+      agent_action: "agent.action",
+      chart_update: "github.push",
+      beat_created: "agent.action",
+      ceremony_action: "system.event",
+    };
+    return mapping[type] || "system.event";
+  }
+
+  private inferNarrativeFunction(content: string): NarrativeFunction {
+    const lower = content.toLowerCase();
+    
+    if (lower.includes("begin") || lower.includes("start") || lower.includes("init")) {
+      return NarrativeFunction.INCITING_INCIDENT;
+    }
+    if (lower.includes("complete") || lower.includes("finish") || lower.includes("done")) {
+      return NarrativeFunction.RESOLUTION;
+    }
+    if (lower.includes("problem") || lower.includes("issue") || lower.includes("bug")) {
+      return NarrativeFunction.COMPLICATION;
+    }
+    if (lower.includes("fix") || lower.includes("resolve") || lower.includes("solved")) {
+      return NarrativeFunction.RESOLUTION;
+    }
+    if (lower.includes("major") || lower.includes("significant") || lower.includes("breakthrough")) {
+      return NarrativeFunction.TURNING_POINT;
+    }
+    
+    return NarrativeFunction.RISING_ACTION;
+  }
+
+  private deriveSuggestedAction(analysis: ThreeUniverseAnalysis): string {
+    const engineer = analysis.engineer;
+    const ceremony = analysis.ceremony;
+    const storyEngine = analysis.storyEngine;
+
+    // Use highest confidence perspective's suggestion
+    if (engineer.confidence >= ceremony.confidence && engineer.confidence >= storyEngine.confidence) {
+      return engineer.suggestedFlows[0] || "analyze";
+    }
+    if (ceremony.confidence >= storyEngine.confidence) {
+      return ceremony.suggestedFlows[0] || "witness";
+    }
+    return storyEngine.suggestedFlows[0] || "narrate";
+  }
+}
+
+// Re-export useful types
+export {
+  Universe,
+  ThreeUniverseAnalysis,
+  StoryBeat,
+  NarrativeFunction,
+  EmotionalTone,
+  CoherenceResult,
+};
+
+// Export singleton for easy use
+let routerInstance: NarrativeRouter | null = null;
+
+export function getNarrativeRouter(): NarrativeRouter {
+  if (!routerInstance) {
+    routerInstance = new NarrativeRouter();
+  }
+  return routerInstance;
+}

package/src/narrative/tracer.ts

@@ -0,0 +1,249 @@
+/**
+ * Narrative Tracing Integration for mia-code
+ * 
+ * Integrates @langchain/narrative-tracing for observability that I published as : ava-langchain-narrative-tracing and not @langchain/narrative-tracing
+ * across mia-code operations.
+ */
+
+import {
+  NarrativeTracingHandler,
+  NarrativeEventType,
+  NarrativeMetrics,
+  createNarrativeMetrics,
+} from "ava-langchain-narrative-tracing";
+
+import { Universe, ThreeUniverseAnalysis } from "./router.js";
+
+/**
+ * mia-code operation types
+ */
+export type MiaCodeOperation =
+  | "chart_create"
+  | "chart_update"
+  | "chart_complete"
+  | "beat_create"
+  | "beat_analyze"
+  | "ceremony_init"
+  | "ceremony_advance"
+  | "user_input"
+  | "agent_response"
+  | "routing_decision";
+
+/**
+ * MiaCodeTracer - Wraps NarrativeTracingHandler for mia-code specific operations
+ */
+export class MiaCodeTracer {
+  private handler: NarrativeTracingHandler;
+  private metrics: NarrativeMetrics;
+  private sessionId: string;
+  private startTime: number;
+
+  constructor(options: {
+    sessionId: string;
+    storyId?: string;
+    publicKey?: string;
+    secretKey?: string;
+  }) {
+    this.sessionId = options.sessionId;
+    this.startTime = Date.now();
+    
+    this.handler = new NarrativeTracingHandler({
+      storyId: options.storyId || `mia_${options.sessionId}`,
+      sessionId: options.sessionId,
+      publicKey: options.publicKey || process.env.LANGFUSE_PUBLIC_KEY,
+      secretKey: options.secretKey || process.env.LANGFUSE_SECRET_KEY,
+    });
+
+    this.metrics = createNarrativeMetrics();
+  }
+
+  /**
+   * Start tracing a session
+   */
+  startSession(): string {
+    const traceId = this.handler.startStoryGeneration();
+    return traceId;
+  }
+
+  /**
+   * Log a chart operation (miaco)
+   */
+  logChartOperation(
+    chartId: string,
+    operation: "create" | "update" | "complete" | "add_step",
+    data: Record<string, unknown>
+  ): void {
+    this.handler.logEvent({
+      eventType: NarrativeEventType.BEAT_CREATED,
+      beatId: chartId,
+      metadata: {
+        cli: "miaco",
+        operation,
+        ...data,
+      },
+    });
+    this.metrics.beatsGenerated++;
+  }
+
+  /**
+   * Log a beat operation (miatel)
+   */
+  logBeatOperation(
+    beatId: string,
+    content: string,
+    sequence: number,
+    narrativeFunction: string
+  ): void {
+    this.handler.logBeatCreation(
+      beatId,
+      content,
+      sequence,
+      narrativeFunction
+    );
+    this.metrics.beatsGenerated++;
+  }
+
+  /**
+   * Log a ceremony operation (miawa)
+   */
+  logCeremonyOperation(
+    ceremonyId: string,
+    operation: "init" | "advance" | "close",
+    movement?: string,
+    data?: Record<string, unknown>
+  ): void {
+    this.handler.logEvent({
+      eventType: NarrativeEventType.CHARACTER_ARC_UPDATED,
+      metadata: {
+        cli: "miawa",
+        operation,
+        movement,
+        ceremonyId,
+        ...data,
+      },
+    });
+  }
+
+  /**
+   * Log a three-universe routing decision
+   */
+  logRoutingDecision(analysis: ThreeUniverseAnalysis, targetCli: string): void {
+    this.handler.logThreeUniverseAnalysis({
+      eventId: `route_${Date.now()}`,
+      engineerIntent: analysis.engineer.intent,
+      engineerConfidence: analysis.engineer.confidence,
+      ceremonyIntent: analysis.ceremony.intent,
+      ceremonyConfidence: analysis.ceremony.confidence,
+      storyEngineIntent: analysis.storyEngine.intent,
+      storyEngineConfidence: analysis.storyEngine.confidence,
+      leadUniverse: this.universeToString(analysis.leadUniverse),
+      coherenceScore: analysis.coherenceScore,
+    });
+
+    this.handler.logRoutingDecision({
+      decisionId: `decision_${Date.now()}`,
+      backend: targetCli,
+      flow: analysis.engineer.suggestedFlows[0] || "default",
+      score: analysis.coherenceScore,
+      leadUniverse: this.universeToString(analysis.leadUniverse),
+    });
+
+    this.metrics.routingDecisions++;
+    
+    // Update alignment metrics
+    this.metrics.engineerAlignment = 
+      (this.metrics.engineerAlignment + analysis.engineer.confidence) / 2;
+    this.metrics.ceremonyAlignment = 
+      (this.metrics.ceremonyAlignment + analysis.ceremony.confidence) / 2;
+    this.metrics.storyEngineAlignment = 
+      (this.metrics.storyEngineAlignment + analysis.storyEngine.confidence) / 2;
+    this.metrics.crossUniverseCoherence = 
+      (this.metrics.crossUniverseCoherence + analysis.coherenceScore) / 2;
+  }
+
+  /**
+   * Log a gap identified in the narrative
+   */
+  logGap(type: string, severity: number, description: string): void {
+    this.handler.logGapIdentified(type, description, severity);
+  }
+
+  /**
+   * Log user input
+   */
+  logUserInput(content: string): void {
+    this.handler.logEvent({
+      eventType: NarrativeEventType.BEAT_CREATED,
+      beatId: `input_${Date.now()}`,
+      metadata: { type: "user_input", content: content.slice(0, 200) },
+    });
+  }
+
+  /**
+   * Log agent response
+   */
+  logAgentResponse(content: string, cli: string): void {
+    this.handler.logEvent({
+      eventType: NarrativeEventType.BEAT_ENRICHED,
+      beatId: `response_${Date.now()}`,
+      metadata: { type: "agent_response", cli, content: content.slice(0, 200) },
+    });
+    this.metrics.enrichmentsApplied++;
+  }
+
+  /**
+   * Get correlation headers for external calls
+   */
+  getCorrelationHeaders(): Record<string, string> {
+    return {
+      "X-Mia-Session-Id": this.sessionId,
+      "X-Mia-Trace-Start": this.startTime.toString(),
+    };
+  }
+
+  /**
+   * Get current metrics
+   */
+  getMetrics(): NarrativeMetrics {
+    this.metrics.totalGenerationTimeMs = Date.now() - this.startTime;
+    if (this.metrics.beatsGenerated > 0) {
+      this.metrics.averageBeatTimeMs = 
+        this.metrics.totalGenerationTimeMs / this.metrics.beatsGenerated;
+    }
+    return { ...this.metrics };
+  }
+
+  /**
+   * End session and flush traces
+   */
+  async endSession(): Promise<void> {
+    this.handler.endStoryGeneration(Date.now() - this.startTime);
+    await this.handler.flush();
+  }
+
+  private universeToString(universe: Universe): string {
+    const mapping: Record<Universe, string> = {
+      [Universe.ENGINEER]: "engineer",
+      [Universe.CEREMONY]: "ceremony",
+      [Universe.STORY_ENGINE]: "story_engine",
+    };
+    return mapping[universe] || "unknown";
+  }
+}
+
+// Export types
+export { NarrativeEventType, NarrativeMetrics };
+
+// Singleton tracer instance per session
+const tracers: Map<string, MiaCodeTracer> = new Map();
+
+export function getTracer(sessionId: string): MiaCodeTracer {
+  if (!tracers.has(sessionId)) {
+    tracers.set(sessionId, new MiaCodeTracer({ sessionId }));
+  }
+  return tracers.get(sessionId)!;
+}
+
+export function removeTracer(sessionId: string): void {
+  tracers.delete(sessionId);
+}

package/src/sessionStore.ts

@@ -0,0 +1,111 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { MiaCodeSessionMeta, ChatMessage } from "./types.js";
+
+const SESSIONS_FILE = path.join(os.homedir(), ".mia-code-sessions.json");
+const HISTORY_DIR = path.join(os.homedir(), ".mia-code-history");
+
+interface SessionIndex {
+  byProjectRoot: Record<string, MiaCodeSessionMeta>;
+  byId: Record<string, MiaCodeSessionMeta>;
+}
+
+function loadIndex(): SessionIndex {
+  if (!fs.existsSync(SESSIONS_FILE)) {
+    return { byProjectRoot: {}, byId: {} };
+  }
+  try {
+    const raw = fs.readFileSync(SESSIONS_FILE, "utf8");
+    const parsed = JSON.parse(raw) as SessionIndex;
+    return {
+      byProjectRoot: parsed.byProjectRoot || {},
+      byId: parsed.byId || {}
+    };
+  } catch {
+    return { byProjectRoot: {}, byId: {} };
+  }
+}
+
+function saveIndex(index: SessionIndex): void {
+  fs.writeFileSync(SESSIONS_FILE, JSON.stringify(index, null, 2), "utf8");
+}
+
+export function rememberSession(meta: MiaCodeSessionMeta): void {
+  const idx = loadIndex();
+  if (meta.projectRoot) {
+    idx.byProjectRoot[meta.projectRoot] = meta;
+  }
+  idx.byId[meta.id] = meta;
+  saveIndex(idx);
+}
+
+export function markSessionInitialized(id: string): void {
+  const idx = loadIndex();
+  const session = idx.byId[id];
+  if (session) {
+    session.initialized = true;
+    if (session.projectRoot) {
+      idx.byProjectRoot[session.projectRoot] = session;
+    }
+    saveIndex(idx);
+  }
+}
+
+export function isSessionInitialized(id: string): boolean {
+  const idx = loadIndex();
+  return idx.byId[id]?.initialized ?? false;
+}
+
+export function getLastSessionForProject(projectRoot: string): MiaCodeSessionMeta | null {
+  const idx = loadIndex();
+  return idx.byProjectRoot[projectRoot] ?? null;
+}
+
+export function getSessionById(id: string): MiaCodeSessionMeta | null {
+  const idx = loadIndex();
+  return idx.byId[id] ?? null;
+}
+
+export function listSessions(): MiaCodeSessionMeta[] {
+  const idx = loadIndex();
+  return Object.values(idx.byId);
+}
+
+export function clearSessions(): void {
+  saveIndex({ byProjectRoot: {}, byId: {} });
+}
+
+// ── Chat history persistence ────────────────────────────────────────
+
+function ensureHistoryDir(): void {
+  if (!fs.existsSync(HISTORY_DIR)) {
+    fs.mkdirSync(HISTORY_DIR, { recursive: true });
+  }
+}
+
+function historyFile(sessionId: string): string {
+  // Sanitize session ID for safe filenames
+  const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(HISTORY_DIR, `${safe}.jsonl`);
+}
+
+export function saveChatMessage(sessionId: string, msg: ChatMessage): void {
+  ensureHistoryDir();
+  const line = JSON.stringify(msg) + "\n";
+  fs.appendFileSync(historyFile(sessionId), line, "utf8");
+}
+
+export function loadChatHistory(sessionId: string): ChatMessage[] {
+  const file = historyFile(sessionId);
+  if (!fs.existsSync(file)) return [];
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    return raw
+      .split("\n")
+      .filter(l => l.trim())
+      .map(l => JSON.parse(l) as ChatMessage);
+  } catch {
+    return [];
+  }
+}

package/src/types.ts

@@ -0,0 +1,49 @@
+export type Role = "user" | "assistant" | "system";
+
+export type Engine = "gemini" | "claude" | "copilot";
+
+export interface MiaCodeConfig {
+  engine: Engine;
+  geminiBinary: string;
+  claudeBinary: string;
+  copilotBinary: string;
+  model: string;
+  headlessOutputFormat: "json" | "stream-json";
+  defaultMode: "code" | "chat";
+  defaultProjectRoot: string | null;
+  yoloMode: boolean;
+}
+
+export interface MiaCodeSessionMeta {
+  id: string;
+  startedAt: string;
+  model: string;
+  projectRoot: string | null;
+  initialized?: boolean;  // Has engine acknowledged this session?
+}
+
+export interface ChatMessage {
+  role: "user" | "assistant";
+  text: string;
+  timestamp: string;
+}
+
+export interface GeminiJsonEvent {
+  type: "init" | "message" | "tool_use" | "tool_result" | "error" | "result" | string;
+  session_id?: string;
+  timestamp?: string;
+  role?: Role;
+  text?: string;
+  content?: string;
+  tool?: {
+    name: string;
+    input: unknown;
+  };
+  result?: unknown;
+  error?: {
+    code: string;
+    message: string;
+  };
+  raw?: unknown;
+  [key: string]: unknown;
+}