@ema.co/mcp-toolkit 0.2.3 → 0.3.0

package/dist/sdk/version-tracking.js

@@ -0,0 +1,346 @@
+/**
+ * Persona Version Tracking - Core Types and Logic
+ *
+ * Provides versioning infrastructure for AI Employee configurations.
+ * Designed to work locally (git-backed) and map cleanly to backend tables.
+ */
+import crypto from "node:crypto";
+import { fingerprintPersona } from "../sync.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generate a deterministic content hash for a snapshot.
+ * Used for deduplication and fast equality checks.
+ */
+export function hashSnapshot(snapshot) {
+    // Sort keys for deterministic serialization
+    // Sort data_sources by file_id for deterministic ordering
+    const sortedDataSources = [...(snapshot.data_sources ?? [])].sort((a, b) => a.file_id.localeCompare(b.file_id));
+    const canonical = sortObjectKeys({
+        workflow_definition: snapshot.workflow_definition,
+        workflow_id: snapshot.workflow_id,
+        workflow_interface: snapshot.workflow_interface,
+        proto_config: snapshot.proto_config,
+        display_name: snapshot.display_name,
+        description: snapshot.description,
+        welcome_messages: snapshot.welcome_messages,
+        trigger_type: snapshot.trigger_type,
+        embedding_enabled: snapshot.embedding_enabled,
+        template_id: snapshot.template_id,
+        data_sources: sortedDataSources,
+    });
+    const bytes = Buffer.from(JSON.stringify(canonical), "utf8");
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Deep sort object keys for deterministic JSON serialization.
+ */
+function sortObjectKeys(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(sortObjectKeys);
+    if (typeof obj !== "object")
+        return obj;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = sortObjectKeys(obj[key]);
+    }
+    return sorted;
+}
+/**
+ * Generate a new version ID (UUID v4).
+ */
+export function generateVersionId() {
+    return crypto.randomUUID();
+}
+/**
+ * Generate a version name from version number.
+ */
+export function generateVersionName(versionNumber) {
+    return `v${versionNumber}`;
+}
+/**
+ * Get current ISO timestamp.
+ */
+export function nowIso() {
+    return new Date().toISOString();
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Snapshot Creation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract data source references from persona's status_log.
+ * status_log is a Record<widgetName, FileStatus[]> where FileStatus has
+ * fields like: id, filename, status, tags, etc.
+ */
+export function extractDataSources(persona) {
+    const statusLog = persona.status_log;
+    if (!statusLog) {
+        return [];
+    }
+    const dataSources = [];
+    for (const [widgetName, files] of Object.entries(statusLog)) {
+        // Skip internal/system entries (prefixed with underscore)
+        if (widgetName.startsWith("_")) {
+            continue;
+        }
+        if (!Array.isArray(files)) {
+            continue;
+        }
+        for (const file of files) {
+            if (typeof file !== "object" || file === null) {
+                continue;
+            }
+            const f = file;
+            // Use id if available, fallback to filename for legacy files
+            const fileId = f.id ?? f.filename;
+            if (!fileId) {
+                continue;
+            }
+            dataSources.push({
+                file_id: fileId,
+                filename: f.filename ?? fileId,
+                widget_name: widgetName,
+                tags: Array.isArray(f.tags) ? f.tags : [],
+                status: f.status ?? "unknown",
+            });
+        }
+    }
+    return dataSources;
+}
+/**
+ * Create a PersonaSnapshot from a PersonaDTO.
+ */
+export function createSnapshotFromPersona(persona) {
+    return {
+        workflow_definition: persona.workflow_def ?? null,
+        workflow_id: persona.workflow_id ?? null,
+        workflow_interface: persona.workflow_interface ?? null,
+        proto_config: persona.proto_config ?? null,
+        display_name: persona.name ?? "",
+        description: persona.description ?? "",
+        welcome_messages: persona.welcome_messages ?? null,
+        trigger_type: persona.trigger_type ?? null,
+        embedding_enabled: persona.embedding_enabled ?? null,
+        template_id: persona.template_id ?? persona.templateId ?? null,
+        data_sources: extractDataSources(persona),
+    };
+}
+/**
+ * Create a new version snapshot from a persona.
+ */
+export function createVersionSnapshot(options) {
+    const snapshot = createSnapshotFromPersona(options.persona);
+    const contentHash = hashSnapshot(snapshot);
+    const versionNumber = (options.previous_version_number ?? 0) + 1;
+    return {
+        id: generateVersionId(),
+        persona_id: options.persona.id,
+        tenant_id: options.tenant_id,
+        environment: options.environment,
+        version_number: versionNumber,
+        version_name: generateVersionName(versionNumber),
+        content_hash: contentHash,
+        snapshot,
+        created_at: nowIso(),
+        created_by: options.created_by ?? "mcp-toolkit",
+        trigger: options.trigger,
+        message: options.message ?? "",
+        parent_version_id: options.parent_version_id,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Version Comparison
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Compare two version snapshots and generate a diff.
+ */
+export function compareVersions(v1, v2) {
+    const diff = {
+        v1: { id: v1.id, version_name: v1.version_name, created_at: v1.created_at },
+        v2: { id: v2.id, version_name: v2.version_name, created_at: v2.created_at },
+        identical: v1.content_hash === v2.content_hash,
+        changed_fields: [],
+        changes: {},
+    };
+    if (diff.identical) {
+        return diff;
+    }
+    // Compare snapshot fields (excluding data_sources which is handled separately)
+    const fields = [
+        "workflow_definition",
+        "workflow_id",
+        "workflow_interface",
+        "proto_config",
+        "display_name",
+        "description",
+        "welcome_messages",
+        "trigger_type",
+        "embedding_enabled",
+        "template_id",
+    ];
+    for (const field of fields) {
+        const val1 = v1.snapshot[field];
+        const val2 = v2.snapshot[field];
+        if (JSON.stringify(val1) !== JSON.stringify(val2)) {
+            diff.changed_fields.push(field);
+            diff.changes[field] = { from: val1, to: val2 };
+        }
+    }
+    // Detailed workflow diff if workflow changed
+    if (diff.changed_fields.includes("workflow_definition")) {
+        diff.workflow_diff = compareWorkflowDefinitions(v1.snapshot.workflow_definition, v2.snapshot.workflow_definition);
+    }
+    // Data source diff
+    const dataSourceDiff = compareDataSources(v1.snapshot.data_sources ?? [], v2.snapshot.data_sources ?? []);
+    if (dataSourceDiff.files_added.length > 0 || dataSourceDiff.files_removed.length > 0) {
+        diff.changed_fields.push("data_sources");
+        diff.changes["data_sources"] = {
+            from: v1.snapshot.data_sources,
+            to: v2.snapshot.data_sources,
+        };
+        diff.data_source_diff = dataSourceDiff;
+    }
+    return diff;
+}
+/**
+ * Compare data sources between two snapshots.
+ */
+function compareDataSources(ds1, ds2) {
+    const ids1 = new Set(ds1.map((d) => d.file_id));
+    const ids2 = new Set(ds2.map((d) => d.file_id));
+    const files_added = [];
+    const files_removed = [];
+    // Files in ds2 but not in ds1 = added
+    for (const ds of ds2) {
+        if (!ids1.has(ds.file_id)) {
+            files_added.push(ds.filename);
+        }
+    }
+    // Files in ds1 but not in ds2 = removed
+    for (const ds of ds1) {
+        if (!ids2.has(ds.file_id)) {
+            files_removed.push(ds.filename);
+        }
+    }
+    return { files_added, files_removed };
+}
+/**
+ * Compare two workflow definitions and identify node changes.
+ */
+function compareWorkflowDefinitions(w1, w2) {
+    const result = {
+        nodes_added: [],
+        nodes_removed: [],
+        nodes_modified: [],
+    };
+    if (!w1 && !w2)
+        return result;
+    if (!w1) {
+        // All nodes in w2 are new
+        const actions = w2?.actions ?? [];
+        result.nodes_added = actions.map((a) => a.name ?? "unnamed").filter(Boolean);
+        return result;
+    }
+    if (!w2) {
+        // All nodes in w1 are removed
+        const actions = w1.actions ?? [];
+        result.nodes_removed = actions.map((a) => a.name ?? "unnamed").filter(Boolean);
+        return result;
+    }
+    const actions1 = w1.actions ?? [];
+    const actions2 = w2.actions ?? [];
+    const names1 = new Set(actions1.map((a) => a.name ?? "").filter(Boolean));
+    const names2 = new Set(actions2.map((a) => a.name ?? "").filter(Boolean));
+    // Find added
+    for (const name of names2) {
+        if (!names1.has(name)) {
+            result.nodes_added.push(name);
+        }
+    }
+    // Find removed
+    for (const name of names1) {
+        if (!names2.has(name)) {
+            result.nodes_removed.push(name);
+        }
+    }
+    // Find modified (present in both but different)
+    const map1 = new Map(actions1.map((a) => [a.name ?? "", a]));
+    const map2 = new Map(actions2.map((a) => [a.name ?? "", a]));
+    for (const name of names1) {
+        if (names2.has(name)) {
+            const a1 = map1.get(name);
+            const a2 = map2.get(name);
+            if (JSON.stringify(a1) !== JSON.stringify(a2)) {
+                result.nodes_modified.push(name);
+            }
+        }
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Change Summary Generation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generate a human-readable summary of changes between versions.
+ */
+export function generateChangesSummary(diff) {
+    if (diff.identical) {
+        return ["No changes"];
+    }
+    const summary = [];
+    // Field-level changes
+    for (const field of diff.changed_fields) {
+        if (field === "workflow_definition" && diff.workflow_diff) {
+            // Detailed workflow changes
+            const wd = diff.workflow_diff;
+            if (wd.nodes_added.length > 0) {
+                summary.push(`Added nodes: ${wd.nodes_added.join(", ")}`);
+            }
+            if (wd.nodes_removed.length > 0) {
+                summary.push(`Removed nodes: ${wd.nodes_removed.join(", ")}`);
+            }
+            if (wd.nodes_modified.length > 0) {
+                summary.push(`Modified nodes: ${wd.nodes_modified.join(", ")}`);
+            }
+        }
+        else if (field === "data_sources" && diff.data_source_diff) {
+            // Detailed data source changes
+            const dsd = diff.data_source_diff;
+            if (dsd.files_added.length > 0) {
+                summary.push(`Added files: ${dsd.files_added.join(", ")}`);
+            }
+            if (dsd.files_removed.length > 0) {
+                summary.push(`Removed files: ${dsd.files_removed.join(", ")}`);
+            }
+        }
+        else if (field === "display_name") {
+            const from = diff.changes[field]?.from;
+            const to = diff.changes[field]?.to;
+            summary.push(`Renamed: "${from}" → "${to}"`);
+        }
+        else if (field === "description") {
+            summary.push("Description updated");
+        }
+        else if (field === "proto_config") {
+            summary.push("Configuration updated");
+        }
+        else if (field === "welcome_messages") {
+            summary.push("Welcome messages updated");
+        }
+        else if (field === "embedding_enabled") {
+            const enabled = diff.changes[field]?.to;
+            summary.push(`Embedding ${enabled ? "enabled" : "disabled"}`);
+        }
+        else {
+            summary.push(`${field} changed`);
+        }
+    }
+    return summary.length > 0 ? summary : ["Configuration changed"];
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────────
+export { fingerprintPersona };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",

package/docs/advisor-comms-assistant-fixes.md

@@ -1,175 +0,0 @@
-# Advisor Communications Assistant - Workflow Fixes
-
-**Persona ID**: `d5aa0b7a-792d-4e3d-8a74-ac87457ffca2`
-**Environment**: demo
-**Analysis Date**: 2026-01-10
-
-## Summary
-
-| Severity | Count | Status |
-|----------|-------|--------|
-| Critical | 3 | Needs fix |
-| Warning | 0 | - |
-| Info | 4 | Acceptable |
-
-## Critical Issues & Fixes
-
-### Issue 1: Document → Email Attachment Type Mismatch
-
-**Location**: `generate_documentnr7ttm` → `send_email_agentq7zdvj`
-
-**Problem**: 
-- `document_link` output is type `WELL_KNOWN_TYPE_DOCUMENT`
-- `attachment_links` input expects `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES`
-
-**Fix Options**:
-
-**Option A (Recommended)**: Use `named_inputs` instead
-```yaml
-# Change from:
-send_email_agentq7zdvj.inputs.attachment_links:
-  actionOutput:
-    actionName: generate_documentnr7ttm
-    output: document_link
-
-# To:
-send_email_agentq7zdvj.inputs.named_inputs:
-  multiBinding:
-    elements:
-      - namedBinding:
-          name: document_attachment
-          value:
-            actionOutput:
-              actionName: generate_documentnr7ttm
-              output: document_link
-```
-
-**Option B**: Use a fixed_response node to convert document_link to text
-
----
-
-### Issue 2: Combined Results → Content Generator Type Mismatch
-
-**Location**: `combine_search_resultssmoo58` → `personalized_content_generatorfosf62`
-
-**Problem**:
-- `combined_results` output is type `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES`
-- `search_results` input expects `WELL_KNOWN_TYPE_SEARCH_RESULT`
-
-**Fix**:
-Route original search results directly instead of combined:
-
-```yaml
-# Change from:
-personalized_content_generatorfosf62.inputs.search_results:
-  actionOutput:
-    actionName: combine_search_resultssmoo58
-    output: combined_results
-
-# To:
-personalized_content_generatorfosf62.inputs.search_results:
-  actionOutput:
-    actionName: searchfleqzf
-    output: search_results
-```
-
-**Alternative**: Use `named_inputs` for combined results:
-```yaml
-personalized_content_generatorfosf62.inputs.named_inputs:
-  multiBinding:
-    elements:
-      - namedBinding:
-          name: combined_context
-          value:
-            actionOutput:
-              actionName: combine_search_resultssmoo58
-              output: combined_results
-```
-
----
-
-### Issue 3: Summarized Conversation → Custom Agent Conversation Mismatch
-
-**Location**: `conversation_summarizer` → `custom_agentrjrvw6`
-
-**Problem**:
-- `summarized_conversation` is type `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES`
-- `conversation` input expects `WELL_KNOWN_TYPE_CHAT_CONVERSATION`
-
-**Fix**:
-Use the trigger's conversation output instead:
-
-```yaml
-# Change from:
-custom_agentrjrvw6.inputs.conversation:
-  actionOutput:
-    actionName: conversation_summarizer
-    output: summarized_conversation
-
-# To:
-custom_agentrjrvw6.inputs.conversation:
-  actionOutput:
-    actionName: trigger
-    output: chat_conversation
-```
-
-And pass the summarized query via `named_inputs`:
-```yaml
-custom_agentrjrvw6.inputs.named_inputs:
-  multiBinding:
-    elements:
-      - namedBinding:
-          name: context
-          value:
-            actionOutput:
-              actionName: conversation_summarizer
-              output: summarized_conversation
-```
-
----
-
-## Info Issues (Acceptable)
-
-### Sequential Searches
-The workflow has sequential dependencies between searches:
-- `conversation_summarizer` → `live_web_search7kmyak`
-- `searchfleqzf` → `combine_search_resultssmoo58`
-
-**Assessment**: Acceptable - the searches depend on each other's outputs.
-
-### Multiple LLM Nodes
-5 LLM nodes process results from `searchfleqzf`:
-- `respond_client_update`
-- `respond_market_impact`
-- `respond_exposure`
-- `respond_compliance`
-- `respond_health`
-
-**Assessment**: Expected behavior - these are conditional branches from the categorizer.
-
----
-
-## Application Instructions
-
-### Via Ema UI (Recommended)
-1. Open persona in Auto Builder
-2. For each critical issue:
-   - Click on the target node
-   - Modify the input binding as described
-3. Save and test
-
-### Via API
-Use the `/api/personas/update_persona` endpoint with the corrected `workflow` field.
-
----
-
-## Type Compatibility Quick Reference
-
-| From Type | Can Connect To |
-|-----------|---------------|
-| CHAT_CONVERSATION | conversation inputs, named_inputs |
-| TEXT_WITH_SOURCES | query, named_inputs, instructions |
-| SEARCH_RESULT | search_results inputs, named_inputs |
-| DOCUMENT | named_inputs (NOT text inputs) |
-
-**Rule**: When in doubt, use `named_inputs` - it accepts ANY type.