atabey 0.0.6 → 0.0.8

package/{src/cli/commands/knowledge.ts → framework-mcp/dist/src/cli/commands/knowledge.js}

@@ -1,26 +1,23 @@
 import fs from "fs";
 import path from "path";
-
 import { getFrameworkDir } from "../utils/memory.js";
-
 import { writeTextFile } from "../utils/fs.js";
-
-export async function updateKnowledgeBaseCommand(topic: string, content: string) {
+export async function updateKnowledgeBaseCommand(topic, content) {
     if (!topic || !content) {
-        console.error("❌ Usage: atabey update_knowledge_base <topic> <content>");
+        console.error("[ERROR] Usage: atabey update_knowledge_base <topic> <content>");
         return;
     }
     const frameworkDir = getFrameworkDir();
     const kbDir = path.join(frameworkDir, "knowledge");
-    if (!fs.existsSync(kbDir)) fs.mkdirSync(kbDir, { recursive: true });
+    if (!fs.existsSync(kbDir))
+        fs.mkdirSync(kbDir, { recursive: true });
     const fileName = topic.replace(/[^a-z0-9]/gi, "_").toLowerCase() + ".md";
     writeTextFile(path.join(kbDir, fileName), content);
-    console.warn(`✅ Knowledge base updated: ${topic}`);
+    console.warn(`[OK] Knowledge base updated: ${topic}`);
 }
-
-export async function searchKnowledgeBaseCommand(query: string) {
+export async function searchKnowledgeBaseCommand(query) {
     if (!query) {
-        console.error("❌ Usage: atabey search_knowledge_base <query>");
+        console.error("[ERROR] Usage: atabey search_knowledge_base <query>");
         return;
     }
     const frameworkDir = getFrameworkDir();
@@ -40,5 +37,6 @@ ${content.slice(0, 300)}...`);
             found = true;
         }
     }
-    if (!found) console.warn("ℹ️ No matching entries found.");
+    if (!found)
+        console.warn("ℹ️ No matching entries found.");
 }

package/{src/cli/commands/lint.ts → framework-mcp/dist/src/cli/commands/lint.js}

@@ -1,11 +1,9 @@
 import { execSync } from "child_process";
-
 import { getPackageVersion } from "../utils/pkg.js";
-
 /**
  * Run ESLint for the project (same as npm run lint).
  */
-export async function lintCommand(): Promise<void> {
+export async function lintCommand() {
     console.warn(`🔍 Running ESLint (v${getPackageVersion()})...`);
     const projectRoot = process.cwd();
     try {
@@ -14,9 +12,10 @@ export async function lintCommand(): Promise<void> {
             stdio: "inherit",
             env: process.env,
         });
-        console.warn("\n✅ ESLint passed with no errors.");
-    } catch {
-        console.warn("\n❌ ESLint reported errors. Fix violations before committing.");
+        console.warn("\n[OK] ESLint passed with no errors.");
+    }
+    catch {
+        console.warn("\n[ERROR] ESLint reported errors. Fix violations before committing.");
         console.warn("   Tip: npm run lint -- --fix");
         process.exit(1);
     }

package/framework-mcp/dist/src/cli/commands/log.js

@@ -0,0 +1,10 @@
+import { normalizeAgentName } from "../utils/string.js";
+import { Storage } from "../../shared/storage.js";
+export async function logAgentActionCommand(data) {
+    const agent = normalizeAgentName(data.agent);
+    const db = Storage.getDB();
+    db.prepare(`
+        INSERT INTO logs (agent, action, trace_id, status, summary, findings)
+        VALUES (?, ?, ?, ?, ?, ?)
+    `).run(agent, data.action, data.traceId || null, data.status || "SUCCESS", data.summary || "", data.details ? JSON.stringify(data.details) : null);
+}

package/{src/cli/commands/memory.ts → framework-mcp/dist/src/cli/commands/memory.js}

@@ -1,6 +1,4 @@
 import { updateProjectMemory } from "../utils/memory.js";
-
-export async function updateProjectMemoryCommand(section: string, content: string) {
+export async function updateProjectMemoryCommand(section, content) {
     updateProjectMemory(section, content);
 }
-

package/framework-mcp/dist/src/cli/commands/orchestrate.js

@@ -0,0 +1,159 @@
+import { UI } from "../utils/ui.js";
+import { z } from "zod";
+import { logger } from "../../shared/logger.js";
+import { sleep } from "../utils/time.js";
+import { Storage } from "../../shared/storage.js";
+import { asTraceID } from "../../shared/types.js";
+export const HermesMessageSchema = z.object({
+    timestamp: z.string(),
+    from: z.string(),
+    to: z.string(),
+    category: z.enum(["ACTION", "DELEGATION", "SUBTASK", "REPLY", "ALERT"]),
+    content: z.string(), // This is the payload to be validated
+    traceId: z.string(),
+    parentId: z.string().optional(),
+    status: z.enum(["PENDING", "PROCESSED", "WAITING", "APPROVED"]),
+    priority: z.enum(["HIGH", "NORMAL", "LOW"]).optional(),
+    action: z.string().optional(),
+    requiresApproval: z.boolean().optional(),
+    dependencies: z.array(z.string()).optional(),
+});
+let isLooping = false;
+export async function orchestrateCommand(options) {
+    UI.intent("Hermes Message Broker", "Starting the live agent orchestration loop...");
+    const maxIterations = options?.maxIterations;
+    let iterationCount = 0;
+    isLooping = true;
+    while (isLooping) {
+        try {
+            // 1. Check for agent timeouts using SQLite
+            const agents = Storage.getAllAgents();
+            for (const agent of agents) {
+                if (agent.state === "EXECUTING" && agent.last_updated) {
+                    const lastUpdatedTime = Date.parse(agent.last_updated);
+                    if (!isNaN(lastUpdatedTime) && Date.now() - lastUpdatedTime > 30 * 60 * 1000) {
+                        const displayAgent = `@${agent.name}`;
+                        UI.error(`[WARN]  Agent ${displayAgent} has TIMED OUT. Triggering Self-Healing...`);
+                        Storage.updateAgentStatus(agent.name, "READY", "Idle (Recovered from Timeout)");
+                        UI.success(`[OK] Hermes Self-Healing: ${displayAgent} reset to READY state.`);
+                    }
+                }
+            }
+            // 2. Fetch actionable messages from SQLite
+            const pendingMessages = Storage.getPendingMessages() || [];
+            if (pendingMessages.length > 0) {
+                UI.intent("Multi-Agent Orchestration", `${pendingMessages.length} pending tasks found in database.`);
+                for (const msg of pendingMessages) {
+                    // Dependency Check
+                    if (msg.parentId) {
+                        const tasks = Storage.getTasks(asTraceID(msg.traceId));
+                        const task = tasks.find(t => t.id === msg.parentId);
+                        if (task && task.dependencies.length > 0) {
+                            const incompleteDeps = tasks.filter(t => task.dependencies.includes(t.id) && t.status !== "COMPLETED");
+                            if (incompleteDeps.length > 0) {
+                                logger.debug(`Skipping task ${msg.parentId} for ${msg.to} - waiting for dependencies: ${incompleteDeps.map(d => d.id).join(", ")}`);
+                                continue;
+                            }
+                        }
+                    }
+                    // Risk and Approval Logic
+                    let riskFlag = false;
+                    try {
+                        const { RiskEngine } = await import("../../modules/engines/risk-engine.js");
+                        const assessment = RiskEngine.assessTaskRisk(msg.content);
+                        if (assessment.requiresApproval) {
+                            riskFlag = true;
+                            UI.warning(`[SECURITY]  Risk Engine auto-flagged Trace ${msg.traceId} as HIGH RISK`);
+                        }
+                    }
+                    catch { /* engine not ready */ }
+                    if ((msg.category === "ACTION" || msg.category === "ALERT" || riskFlag) && (msg.requiresApproval || riskFlag) && msg.status !== "APPROVED") {
+                        UI.warning(`\n[WARN]  [APPROVAL REQUEST] Trace ${msg.traceId} requires approval:`);
+                        UI.warning(`   Description: ${msg.content}`);
+                        const approved = await askUserApproval(msg.traceId, msg.content);
+                        if (approved && msg.id !== undefined) {
+                            Storage.updateMessageStatus(msg.id, "APPROVED");
+                            UI.success(`Approved trace: ${msg.traceId}`);
+                        }
+                        else if (msg.id !== undefined) {
+                            Storage.updateMessageStatus(msg.id, "PROCESSED"); // Mark as ignored/rejected
+                            continue;
+                        }
+                    }
+                    // Process message
+                    UI.agentBox(msg.to, msg.content, `Trace: ${msg.traceId} | From: ${msg.from} | Category: ${msg.category}`);
+                    let targetState = "EXECUTING";
+                    if (msg.category === "DELEGATION" || msg.category === "SUBTASK")
+                        targetState = "BRIEFED";
+                    let taskDescription = msg.content;
+                    try {
+                        const payload = JSON.parse(msg.content);
+                        taskDescription = payload.task || msg.content;
+                    }
+                    catch { /* ... */ }
+                    Storage.updateAgentStatus(msg.to, targetState, taskDescription);
+                    if (targetState === "BRIEFED") {
+                        Storage.updateAgentStatus(msg.to, "EXECUTING", taskDescription);
+                    }
+                    if (msg.id !== undefined) {
+                        Storage.updateMessageStatus(msg.id, "PROCESSED");
+                    }
+                }
+                // Sync to Markdown for human readability
+                const { syncMarkdownMemory } = await import("../utils/memory.js");
+                syncMarkdownMemory();
+            }
+        }
+        catch (globalLoopErr) {
+            UI.error(`[WARN]  Critical error in Hermes orchestration loop: ${globalLoopErr.message}`);
+        }
+        iterationCount++;
+        if (maxIterations !== undefined && iterationCount >= maxIterations) {
+            isLooping = false;
+            break;
+        }
+        await sleep(2000);
+    }
+}
+/**
+ * Standard tool for agents to delegate tasks to other agents.
+ */
+export async function sendMessage(args) {
+    try {
+        const message = {
+            timestamp: new Date().toISOString(),
+            from: args.from,
+            to: args.to,
+            category: args.category,
+            content: args.content,
+            traceId: asTraceID(args.traceId),
+            parentId: args.parentId,
+            status: "PENDING",
+            priority: args.priority || "NORMAL",
+            requiresApproval: args.requiresApproval || false
+        };
+        Storage.saveMessage(message);
+        return message;
+    }
+    catch (err) {
+        UI.error(`Message could not be delivered: ${args.from} -> ${args.to}`);
+        logger.debug("Hermes sendMessage failed", err);
+    }
+}
+async function askUserApproval(_traceId, _content) {
+    if (process.env.ATABEY_TEST_DIR || !process.stdin.isTTY) {
+        return false;
+    }
+    const readline = await import("readline");
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    return new Promise((resolve) => {
+        rl.question("[INFO] Approve this operation? (y/N): ", (answer) => {
+            rl.close();
+            const cleanAnswer = answer.trim().toLowerCase();
+            resolve(cleanAnswer === "y" || cleanAnswer === "yes");
+        });
+    });
+}

package/framework-mcp/dist/src/cli/commands/plan.js

@@ -0,0 +1,117 @@
+import fs from "fs";
+import path from "path";
+import { generateULID } from "../utils/time.js";
+import { UI } from "../utils/ui.js";
+import { RoutingEngine } from "../../modules/engines/routing-engine.js";
+import { PlanningEngine } from "../../modules/engines/planning-engine.js";
+import { sendMessage } from "./orchestrate.js";
+import { Storage } from "../../shared/storage.js";
+import { asTraceID } from "../../shared/types.js";
+/**
+ * Submits a structured plan (DAG) to the framework.
+ */
+export async function submitPlanCommand(tasks) {
+    const traceId = asTraceID(generateULID());
+    const plan = PlanningEngine.createPlan(tasks);
+    const validation = PlanningEngine.validatePlan(plan);
+    if (!validation.valid) {
+        UI.error("Invalid Plan Submission:");
+        validation.errors.forEach((e) => UI.error(` - ${e}`));
+        process.exit(64);
+    }
+    UI.intent("Dynamic Task Planner", `Processing plan with ${plan.tasks.length} tasks (Plan Trace: ${traceId})`);
+    // Save plan metadata to SQLite
+    Storage.setMetadata(`plan_${traceId}`, JSON.stringify(plan));
+    for (const task of plan.tasks) {
+        const taskData = {
+            id: task.id,
+            traceId,
+            description: task.task,
+            agent: task.agent,
+            priority: "NORMAL",
+            status: "PENDING",
+            dependencies: task.dependencies || []
+        };
+        Storage.saveTask(taskData);
+        // Queue as a delegated message in SQLite
+        await sendMessage({
+            from: "@manager",
+            to: task.agent,
+            category: "DELEGATION",
+            content: JSON.stringify({ task: task.task, traceId }),
+            traceId,
+            parentId: task.id,
+            priority: "NORMAL",
+            dependencies: task.dependencies || []
+        });
+    }
+    UI.success(`[OK] Dynamic plan submitted and queued: ${plan.tasks.length} tasks.`);
+}
+/**
+ * Reads ALL markdown files from the docs/ directory and creates
+ * planning tasks from them. Agents will use this to understand
+ * project requirements and generate code accordingly.
+ */
+export async function planCommand() {
+    const projectRoot = process.cwd();
+    const docsDir = path.join(projectRoot, "docs");
+    if (!fs.existsSync(docsDir)) {
+        UI.error("Docs directory not found at docs/");
+        console.warn("[TIP]  Create a docs/ folder with your project requirements in .md files.");
+        return;
+    }
+    const entries = fs.readdirSync(docsDir, { withFileTypes: true });
+    const mdFiles = entries.filter(e => e.isFile() && e.name.endsWith(".md"));
+    if (mdFiles.length === 0) {
+        UI.warning("No markdown files found in docs/ directory.");
+        console.warn("[TIP]  Add .md files to docs/ with your project requirements.");
+        return;
+    }
+    UI.intent("Planning Engine", `Reading ${mdFiles.length} document(s) from docs/...`);
+    let totalTasks = 0;
+    for (const file of mdFiles) {
+        const filePath = path.join(docsDir, file.name);
+        const content = fs.readFileSync(filePath, "utf8");
+        const traceId = asTraceID(generateULID());
+        UI.success(`📄 docs/${file.name} (Trace: ${traceId})`);
+        // Extract checklist items and create sequential task chain
+        const taskRegex = /- \[ \]\s+(.+)/g;
+        let taskMatch;
+        let taskCount = 0;
+        let lastTaskId = null;
+        while ((taskMatch = taskRegex.exec(content)) !== null) {
+            const taskText = taskMatch[1].trim();
+            if (taskText.length >= 3) {
+                taskCount++;
+                totalTasks++;
+                // Capability routing via RoutingEngine
+                const targetAgent = RoutingEngine.resolveAgent(taskText);
+                const subTaskId = generateULID();
+                const taskData = {
+                    id: subTaskId,
+                    traceId,
+                    description: taskText,
+                    agent: targetAgent,
+                    priority: "NORMAL",
+                    status: "PENDING",
+                    dependencies: lastTaskId ? [lastTaskId] : []
+                };
+                Storage.saveTask(taskData);
+                // Queue as a delegated message
+                await sendMessage({
+                    from: "@manager",
+                    to: targetAgent,
+                    category: "DELEGATION",
+                    content: JSON.stringify({ task: taskText, traceId }),
+                    traceId,
+                    parentId: subTaskId,
+                    priority: "NORMAL",
+                    dependencies: lastTaskId ? [lastTaskId] : []
+                });
+                lastTaskId = subTaskId;
+            }
+        }
+        console.warn(`   📋 Actionable tasks detected: ${taskCount}`);
+    }
+    UI.success(`\n[OK] Planning complete: ${totalTasks} tasks identified.`);
+}

package/{src/cli/commands/script.ts → framework-mcp/dist/src/cli/commands/script.js}

@@ -1,20 +1,19 @@
 import fs from "fs";
 import path from "path";
 import cp from "child_process";
-
 const targetDir = process.cwd(); // Assuming targetDir is process.cwd() in the CLI context
-
-export async function runScriptCommand(script: string, projectPath: string) {
+export async function runScriptCommand(script, projectPath) {
     const fullPath = path.join(targetDir, projectPath);
     if (!fs.existsSync(fullPath)) {
-        console.warn(`❌ Project path not found: ${projectPath}`);
+        console.warn(`[ERROR] Project path not found: ${projectPath}`);
         return;
     }
-    console.warn(`🚀 Running 'npm run ${script}' in ${projectPath}...`);
+    console.warn(`[START] Running 'npm run ${script}' in ${projectPath}...`);
     try {
         cp.spawnSync("npm", ["run", script], { cwd: fullPath, stdio: "inherit", shell: true });
-    } catch (e: unknown) {
+    }
+    catch (e) {
         const message = e instanceof Error ? e.message : "Unknown error";
-        console.warn(`❌ Failed to run script: ${message}`);
+        console.warn(`[ERROR] Failed to run script: ${message}`);
     }
 }

package/{src/cli/commands/security.ts → framework-mcp/dist/src/cli/commands/security.js}

@@ -1,11 +1,8 @@
 import fs from "fs";
 import path from "path";
-
 import { collectFiles } from "../utils/fs.js";
-
 const targetDir = process.cwd();
-
-export async function securityAuditCommand(targetPath: string) {
+export async function securityAuditCommand(targetPath) {
     console.warn(`🔍 Running Advanced Security Audit on: ${targetPath}...`);
     const scanRules = [
         { pattern: /sql`/, message: "Potential Raw SQL usage detected", severity: "HIGH" },
@@ -17,7 +14,7 @@ export async function securityAuditCommand(targetPath: string) {
         { pattern: /:\s*any(?!\w)/, message: "Usage of 'any' type detected", severity: "MEDIUM" },
         { pattern: /\.innerHTML\s*=/, message: "Unsafe innerHTML assignment detected", severity: "MEDIUM" },
     ];
-    const issues: string[] = [];
+    const issues = [];
     const files = collectFiles(path.join(targetDir, targetPath), [".ts", ".tsx", ".js", ".jsx"]);
     files.forEach((f) => {
         const content = fs.readFileSync(f, "utf8");
@@ -31,8 +28,9 @@ export async function securityAuditCommand(targetPath: string) {
         });
     });
     if (issues.length === 0) {
-        console.warn("✅ No security issues detected.");
-    } else {
-        issues.forEach((issue) => console.warn(`⚠️  ${issue}`));
+        console.warn("[OK] No security issues detected.");
+    }
+    else {
+        issues.forEach((issue) => console.warn(`[WARN]  ${issue}`));
     }
 }

package/framework-mcp/dist/src/cli/commands/status.js

@@ -0,0 +1,97 @@
+import chalk from "chalk";
+import fs from "fs";
+import path from "path";
+import { getFrameworkDir, listTasks, readState, readStatus } from "../utils/memory.js";
+/**
+ * Print the current framework status.
+ */
+export async function statusCommand() {
+    const state = readState();
+    const tasks = listTasks();
+    const agentStatuses = readStatus();
+    const frameworkDir = getFrameworkDir();
+    if (!state) {
+        console.error("[ERROR] Error: Memory state not found. Please run 'init' first.");
+        return;
+    }
+    console.warn("\n[DATA] --- PROJECT STATUS ---");
+    console.warn(`🔹 Phase: ${state.phase}`);
+    console.warn(`🆔 Trace ID: ${state.traceId}`);
+    console.warn(`[AI] Manager: ${state.managerState}`);
+    // --- Health Engine Integration ---
+    try {
+        const { HealthEngine } = await import("../../modules/engines/health-engine.js");
+        const health = HealthEngine.getHealth();
+        if (health) {
+            let healthColor = chalk.green;
+            if (health.score < 50)
+                healthColor = chalk.red;
+            else if (health.score < 80)
+                healthColor = chalk.yellow;
+            console.warn(`❤️  Project Health: ${healthColor(health.score + "%")} (Quality: ${health.codeQuality} | Security: ${health.security})`);
+        }
+    }
+    catch {
+        // Health engine not initialized or compiled yet
+    }
+    // Read Agent Status from Storage
+    console.warn("\n[ATABEY]  Atabey Army Status (Agent States & Performance):");
+    const { Storage } = await import("../../shared/storage.js");
+    for (const [agentName, info] of Object.entries(agentStatuses)) {
+        const { state, task } = info;
+        let coloredState = state;
+        if (state === "READY")
+            coloredState = chalk.green(state);
+        else if (state === "EXECUTING")
+            coloredState = chalk.yellow(state);
+        else if (state === "BLOCKED" || state === "TIMEOUT")
+            coloredState = chalk.red(state);
+        else if (state === "WAITING")
+            coloredState = chalk.cyan(state);
+        // Calculate Success Rate from SQLite logs
+        let successRateStr = "";
+        const logs = Storage.getLogs(agentName);
+        const total = logs.length;
+        if (total > 0) {
+            const successCount = logs.filter(l => l.status === "SUCCESS").length;
+            const rate = (successCount / total) * 100;
+            successRateStr = ` | Success Rate: ${rate.toFixed(1)}% (${successCount}/${total})`;
+        }
+        console.warn(`  ${chalk.bold(agentName.padEnd(12))} : [${coloredState}] - ${task}${successRateStr}`);
+    }
+    if (tasks.length > 0) {
+        console.warn("\n📋 Active Tasks:");
+        tasks.forEach((t) => {
+            const agent = t.agent.startsWith("@") ? t.agent : `@${t.agent}`;
+            console.warn(`  - [${t.priority}] ${t.status}: ${t.description} (${agent})`);
+        });
+    }
+    const metricsPath = path.join(frameworkDir, "observability", "metrics.json");
+    if (fs.existsSync(metricsPath)) {
+        try {
+            const rawMetrics = fs.readFileSync(metricsPath, "utf8");
+            const metrics = JSON.parse(rawMetrics);
+            let totalTokens = 0;
+            const agentTokens = {};
+            metrics.forEach(m => {
+                totalTokens += m.estimatedTokens;
+                const name = m.agent.startsWith("@") ? m.agent : `@${m.agent}`;
+                agentTokens[name] = (agentTokens[name] || 0) + m.estimatedTokens;
+            });
+            // Assume $5.00 per 1M tokens average pricing
+            const estimatedCost = (totalTokens / 1_000_000) * 5.00;
+            console.warn("\n💸 --- OBSERVABILITY & COST DASHBOARD ---");
+            console.warn(`💳 Total Estimated Tokens: ${totalTokens.toLocaleString()}`);
+            console.warn(`💲 Total Estimated LLM Cost: $${estimatedCost.toFixed(4)}`);
+            if (Object.keys(agentTokens).length > 0) {
+                console.warn("\n[COST] Cost Distribution per Agent:");
+                Object.entries(agentTokens).forEach(([agent, tokens]) => {
+                    const agentCost = (tokens / 1_000_000) * 5.00;
+                    console.warn(`  ${chalk.bold(agent.padEnd(12))} : ${tokens.toLocaleString()} tokens ($${agentCost.toFixed(4)})`);
+                });
+            }
+        }
+        catch { /* ignore metrics read errors */ }
+    }
+    console.warn("\n-----------------------\n");
+}

package/framework-mcp/dist/src/cli/commands/trace.js

@@ -0,0 +1,109 @@
+import { updateDocumentStore, generateULID, getFrameworkDir } from "../utils/memory.js";
+import { sanitizeInput, normalizeAgentName, normalizePriority } from "../utils/string.js";
+/**
+ * Generate a new Trace ID and add it to project memory.
+ */
+export async function traceNewCommand(description, agent = "manager", priority = "P2") {
+    const traceId = generateULID();
+    const safeDescription = sanitizeInput(description);
+    const safeAgent = normalizeAgentName(agent);
+    const safePriority = normalizePriority(priority);
+    const frameworkDir = getFrameworkDir();
+    // ...
+    // --- Document Store Write ---
+    updateDocumentStore("task", {
+        traceId,
+        description: safeDescription,
+        agent: safeAgent,
+        priority: safePriority,
+        status: "IN_PROGRESS",
+        createdAt: new Date().toISOString()
+    }, traceId, frameworkDir);
+    // ----------------------------
+    console.warn(`[OK] New Trace ID created: ${traceId}`);
+    console.warn(`📝 Added to task list: ${description}
+`);
+    return traceId;
+}
+/**
+ * Replay the chronological message exchanges of a specific Trace ID.
+ */
+export async function traceReplayCommand(traceId) {
+    const fs = await import("fs");
+    const path = await import("path");
+    const { UI } = await import("../utils/ui.js");
+    const frameworkDir = getFrameworkDir();
+    const archiveDir = path.join(frameworkDir, "messages", "archive");
+    UI.intent("Trace Replay Engine", `Searching archive logs for Trace ID: ${traceId}...`);
+    const events = [];
+    // Scan messages/ folder for active/pending messages
+    const messagesDir = path.join(frameworkDir, "messages");
+    if (fs.existsSync(messagesDir)) {
+        const files = fs.readdirSync(messagesDir).filter(f => f.endsWith(".json"));
+        files.forEach(file => {
+            try {
+                const filePath = path.join(messagesDir, file);
+                const content = fs.readFileSync(filePath, "utf8").trim();
+                if (!content)
+                    return;
+                content.split("\n").forEach(line => {
+                    if (!line.trim())
+                        return;
+                    const msg = JSON.parse(line);
+                    if (msg.traceId === traceId) {
+                        events.push(msg);
+                    }
+                });
+            }
+            catch { /* ignore */ }
+        });
+    }
+    // Scan messages/archive/ folder for processed messages
+    if (fs.existsSync(archiveDir)) {
+        const files = fs.readdirSync(archiveDir).filter(f => f.endsWith(".json"));
+        files.forEach(file => {
+            try {
+                const filePath = path.join(archiveDir, file);
+                const content = fs.readFileSync(filePath, "utf8").trim();
+                if (!content)
+                    return;
+                content.split("\n").forEach(line => {
+                    if (!line.trim())
+                        return;
+                    const msg = JSON.parse(line);
+                    if (msg.traceId === traceId) {
+                        events.push(msg);
+                    }
+                });
+            }
+            catch { /* ignore */ }
+        });
+    }
+    if (events.length === 0) {
+        UI.warning(`No message exchanges found for Trace ID: ${traceId}`);
+        return;
+    }
+    // Sort chronologically by timestamp
+    events.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
+    console.warn("\n================================================================================");
+    console.warn(`🗺️  TRACE TIMELINE REPLAY: ${traceId}`);
+    console.warn("================================================================================");
+    events.forEach(evt => {
+        const timeStr = new Date(evt.timestamp).toLocaleTimeString();
+        console.warn(`\n[${timeStr}] ${evt.from} ➔ ${evt.to} [${evt.category}]`);
+        try {
+            const parsed = JSON.parse(evt.content);
+            if (parsed.task) {
+                console.warn(`  💬 Task: ${parsed.task}`);
+            }
+            else {
+                console.warn(`  💬 Content: ${evt.content}`);
+            }
+        }
+        catch {
+            console.warn(`  💬 Content: ${evt.content}`);
+        }
+    });
+    console.warn("\n================================================================================");
+    UI.success("Trace replay completed.");
+}