mia-code 0.2.0

package/dist/narrative/router.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 { Universe, ThreeUniverseAnalysis, StoryBeat, NarrativeFunction, CoherenceResult, EmotionalTone } from "ava-langgraph-narrative-intelligence";
+/**
+ * Maps universe to mia-code CLI
+ */
+export declare const UNIVERSE_TO_CLI: Record<Universe, string>;
+/**
+ * Maps CLI to universe
+ */
+export declare const CLI_TO_UNIVERSE: Record<string, Universe>;
+/**
+ * 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 declare class NarrativeRouter {
+    private processor;
+    private coherenceEngine;
+    private beatHistory;
+    private beatSequence;
+    constructor();
+    /**
+     * Analyze an event and determine the best CLI to handle it
+     */
+    route(event: MiaCodeEvent): RoutingResult;
+    /**
+     * Record a story beat and update coherence tracking
+     */
+    recordBeat(content: string, cli: "miaco" | "miatel" | "miawa"): StoryBeat;
+    /**
+     * Analyze coherence of accumulated beats
+     */
+    analyzeCoherence(): CoherenceResult | null;
+    /**
+     * Get trinity assessment (Mia/Miette/Ava8 perspectives on quality)
+     */
+    getTrinityAssessment(): {
+        mia: string;
+        miette: string;
+        ava8: string;
+    } | null;
+    /**
+     * Get gaps that need addressing
+     */
+    getGaps(): Array<{
+        type: string;
+        severity: string;
+        description: string;
+    }>;
+    /**
+     * Reset the router (clear beat history)
+     */
+    reset(): void;
+    private mapEventType;
+    private inferNarrativeFunction;
+    private deriveSuggestedAction;
+}
+export { Universe, ThreeUniverseAnalysis, StoryBeat, NarrativeFunction, EmotionalTone, CoherenceResult, };
+export declare function getNarrativeRouter(): NarrativeRouter;

package/dist/narrative/router.js

@@ -0,0 +1,186 @@
+/**
+ * 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, createStoryBeat, NarrativeFunction, EmotionalTone, classifyEmotionalTone, } from "ava-langgraph-narrative-intelligence";
+/**
+ * Maps universe to mia-code CLI
+ */
+export const UNIVERSE_TO_CLI = {
+    [Universe.ENGINEER]: "miaco",
+    [Universe.CEREMONY]: "miawa",
+    [Universe.STORY_ENGINE]: "miatel",
+};
+/**
+ * Maps CLI to universe
+ */
+export const CLI_TO_UNIVERSE = {
+    miaco: Universe.ENGINEER,
+    miawa: Universe.CEREMONY,
+    miatel: Universe.STORY_ENGINE,
+};
+/**
+ * NarrativeRouter - Routes events to the appropriate mia-code CLI
+ * based on three-universe analysis
+ */
+export class NarrativeRouter {
+    processor;
+    coherenceEngine;
+    beatHistory = [];
+    beatSequence = 0;
+    constructor() {
+        this.processor = new ThreeUniverseProcessor();
+        this.coherenceEngine = new NarrativeCoherenceEngine();
+    }
+    /**
+     * Analyze an event and determine the best CLI to handle it
+     */
+    route(event) {
+        // 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];
+        // 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, cli) {
+        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() {
+        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;
+        }
+        return null;
+    }
+    /**
+     * Get trinity assessment (Mia/Miette/Ava8 perspectives on quality)
+     */
+    getTrinityAssessment() {
+        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() {
+        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() {
+        this.beatHistory = [];
+        this.beatSequence = 0;
+    }
+    mapEventType(type) {
+        const mapping = {
+            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";
+    }
+    inferNarrativeFunction(content) {
+        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;
+    }
+    deriveSuggestedAction(analysis) {
+        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, NarrativeFunction, EmotionalTone, };
+// Export singleton for easy use
+let routerInstance = null;
+export function getNarrativeRouter() {
+    if (!routerInstance) {
+        routerInstance = new NarrativeRouter();
+    }
+    return routerInstance;
+}

package/dist/narrative/tracer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 { NarrativeEventType, NarrativeMetrics } from "ava-langchain-narrative-tracing";
+import { 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 declare class MiaCodeTracer {
+    private handler;
+    private metrics;
+    private sessionId;
+    private startTime;
+    constructor(options: {
+        sessionId: string;
+        storyId?: string;
+        publicKey?: string;
+        secretKey?: string;
+    });
+    /**
+     * Start tracing a session
+     */
+    startSession(): string;
+    /**
+     * Log a chart operation (miaco)
+     */
+    logChartOperation(chartId: string, operation: "create" | "update" | "complete" | "add_step", data: Record<string, unknown>): void;
+    /**
+     * Log a beat operation (miatel)
+     */
+    logBeatOperation(beatId: string, content: string, sequence: number, narrativeFunction: string): void;
+    /**
+     * Log a ceremony operation (miawa)
+     */
+    logCeremonyOperation(ceremonyId: string, operation: "init" | "advance" | "close", movement?: string, data?: Record<string, unknown>): void;
+    /**
+     * Log a three-universe routing decision
+     */
+    logRoutingDecision(analysis: ThreeUniverseAnalysis, targetCli: string): void;
+    /**
+     * Log a gap identified in the narrative
+     */
+    logGap(type: string, severity: number, description: string): void;
+    /**
+     * Log user input
+     */
+    logUserInput(content: string): void;
+    /**
+     * Log agent response
+     */
+    logAgentResponse(content: string, cli: string): void;
+    /**
+     * Get correlation headers for external calls
+     */
+    getCorrelationHeaders(): Record<string, string>;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): NarrativeMetrics;
+    /**
+     * End session and flush traces
+     */
+    endSession(): Promise<void>;
+    private universeToString;
+}
+export { NarrativeEventType, NarrativeMetrics };
+export declare function getTracer(sessionId: string): MiaCodeTracer;
+export declare function removeTracer(sessionId: string): void;

package/dist/narrative/tracer.js

@@ -0,0 +1,180 @@
+/**
+ * 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, createNarrativeMetrics, } from "ava-langchain-narrative-tracing";
+import { Universe } from "./router.js";
+/**
+ * MiaCodeTracer - Wraps NarrativeTracingHandler for mia-code specific operations
+ */
+export class MiaCodeTracer {
+    handler;
+    metrics;
+    sessionId;
+    startTime;
+    constructor(options) {
+        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() {
+        const traceId = this.handler.startStoryGeneration();
+        return traceId;
+    }
+    /**
+     * Log a chart operation (miaco)
+     */
+    logChartOperation(chartId, operation, data) {
+        this.handler.logEvent({
+            eventType: NarrativeEventType.BEAT_CREATED,
+            beatId: chartId,
+            metadata: {
+                cli: "miaco",
+                operation,
+                ...data,
+            },
+        });
+        this.metrics.beatsGenerated++;
+    }
+    /**
+     * Log a beat operation (miatel)
+     */
+    logBeatOperation(beatId, content, sequence, narrativeFunction) {
+        this.handler.logBeatCreation(beatId, content, sequence, narrativeFunction);
+        this.metrics.beatsGenerated++;
+    }
+    /**
+     * Log a ceremony operation (miawa)
+     */
+    logCeremonyOperation(ceremonyId, operation, movement, data) {
+        this.handler.logEvent({
+            eventType: NarrativeEventType.CHARACTER_ARC_UPDATED,
+            metadata: {
+                cli: "miawa",
+                operation,
+                movement,
+                ceremonyId,
+                ...data,
+            },
+        });
+    }
+    /**
+     * Log a three-universe routing decision
+     */
+    logRoutingDecision(analysis, targetCli) {
+        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, severity, description) {
+        this.handler.logGapIdentified(type, description, severity);
+    }
+    /**
+     * Log user input
+     */
+    logUserInput(content) {
+        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, cli) {
+        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() {
+        return {
+            "X-Mia-Session-Id": this.sessionId,
+            "X-Mia-Trace-Start": this.startTime.toString(),
+        };
+    }
+    /**
+     * Get current metrics
+     */
+    getMetrics() {
+        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() {
+        this.handler.endStoryGeneration(Date.now() - this.startTime);
+        await this.handler.flush();
+    }
+    universeToString(universe) {
+        const mapping = {
+            [Universe.ENGINEER]: "engineer",
+            [Universe.CEREMONY]: "ceremony",
+            [Universe.STORY_ENGINE]: "story_engine",
+        };
+        return mapping[universe] || "unknown";
+    }
+}
+// Export types
+export { NarrativeEventType };
+// Singleton tracer instance per session
+const tracers = new Map();
+export function getTracer(sessionId) {
+    if (!tracers.has(sessionId)) {
+        tracers.set(sessionId, new MiaCodeTracer({ sessionId }));
+    }
+    return tracers.get(sessionId);
+}
+export function removeTracer(sessionId) {
+    tracers.delete(sessionId);
+}

package/dist/sessionStore.d.ts

@@ -0,0 +1,10 @@
+import { MiaCodeSessionMeta, ChatMessage } from "./types.js";
+export declare function rememberSession(meta: MiaCodeSessionMeta): void;
+export declare function markSessionInitialized(id: string): void;
+export declare function isSessionInitialized(id: string): boolean;
+export declare function getLastSessionForProject(projectRoot: string): MiaCodeSessionMeta | null;
+export declare function getSessionById(id: string): MiaCodeSessionMeta | null;
+export declare function listSessions(): MiaCodeSessionMeta[];
+export declare function clearSessions(): void;
+export declare function saveChatMessage(sessionId: string, msg: ChatMessage): void;
+export declare function loadChatHistory(sessionId: string): ChatMessage[];

package/dist/sessionStore.js

@@ -0,0 +1,93 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+const SESSIONS_FILE = path.join(os.homedir(), ".mia-code-sessions.json");
+const HISTORY_DIR = path.join(os.homedir(), ".mia-code-history");
+function loadIndex() {
+    if (!fs.existsSync(SESSIONS_FILE)) {
+        return { byProjectRoot: {}, byId: {} };
+    }
+    try {
+        const raw = fs.readFileSync(SESSIONS_FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            byProjectRoot: parsed.byProjectRoot || {},
+            byId: parsed.byId || {}
+        };
+    }
+    catch {
+        return { byProjectRoot: {}, byId: {} };
+    }
+}
+function saveIndex(index) {
+    fs.writeFileSync(SESSIONS_FILE, JSON.stringify(index, null, 2), "utf8");
+}
+export function rememberSession(meta) {
+    const idx = loadIndex();
+    if (meta.projectRoot) {
+        idx.byProjectRoot[meta.projectRoot] = meta;
+    }
+    idx.byId[meta.id] = meta;
+    saveIndex(idx);
+}
+export function markSessionInitialized(id) {
+    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) {
+    const idx = loadIndex();
+    return idx.byId[id]?.initialized ?? false;
+}
+export function getLastSessionForProject(projectRoot) {
+    const idx = loadIndex();
+    return idx.byProjectRoot[projectRoot] ?? null;
+}
+export function getSessionById(id) {
+    const idx = loadIndex();
+    return idx.byId[id] ?? null;
+}
+export function listSessions() {
+    const idx = loadIndex();
+    return Object.values(idx.byId);
+}
+export function clearSessions() {
+    saveIndex({ byProjectRoot: {}, byId: {} });
+}
+// ── Chat history persistence ────────────────────────────────────────
+function ensureHistoryDir() {
+    if (!fs.existsSync(HISTORY_DIR)) {
+        fs.mkdirSync(HISTORY_DIR, { recursive: true });
+    }
+}
+function historyFile(sessionId) {
+    // 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, msg) {
+    ensureHistoryDir();
+    const line = JSON.stringify(msg) + "\n";
+    fs.appendFileSync(historyFile(sessionId), line, "utf8");
+}
+export function loadChatHistory(sessionId) {
+    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));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+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;
+}
+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;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/unifier.d.ts

@@ -0,0 +1,6 @@
+import { MiaCodeConfig, GeminiJsonEvent } from "./types.js";
+export interface UnifierInput {
+    userPrompt: string;
+    rawEvents: GeminiJsonEvent[];
+}
+export declare function runUnifierSession(rawEvents: GeminiJsonEvent[], userPrompt: string, config: MiaCodeConfig): Promise<string>;