@ema.co/mcp-toolkit 0.2.0

package/dist/state.js

@@ -0,0 +1,88 @@
+import Database from "better-sqlite3";
+export class StateStore {
+    db;
+    mapTable = "persona_map_v2";
+    fpTable = "persona_fingerprint_v2";
+    runsTable = "sync_runs_v2";
+    constructor(path) {
+        this.db = new Database(path);
+        this.db.pragma("journal_mode = WAL");
+        this.migrate();
+    }
+    close() {
+        this.db.close();
+    }
+    migrate() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.mapTable} (
+        master_env TEXT NOT NULL,
+        master_user_id TEXT NOT NULL,
+        master_persona_id TEXT NOT NULL,
+        target_env TEXT NOT NULL,
+        target_user_id TEXT NOT NULL,
+        target_persona_id TEXT NOT NULL,
+        PRIMARY KEY (master_env, master_user_id, master_persona_id, target_env, target_user_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS ${this.fpTable} (
+        env TEXT NOT NULL,
+        env_user_id TEXT NOT NULL,
+        persona_id TEXT NOT NULL,
+        fingerprint TEXT NOT NULL,
+        last_seen_at TEXT NOT NULL,
+        PRIMARY KEY (env, env_user_id, persona_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS ${this.runsTable} (
+        id TEXT PRIMARY KEY,
+        master_env TEXT NOT NULL,
+        master_env_user_id TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        finished_at TEXT,
+        status TEXT NOT NULL,
+        error TEXT
+      );
+    `);
+    }
+    getMapping(args) {
+        const row = this.db
+            .prepare(`SELECT target_persona_id
+         FROM ${this.mapTable}
+         WHERE master_env = ? AND master_user_id = ? AND master_persona_id = ? AND target_env = ? AND target_user_id = ?`)
+            .get(args.masterEnv, args.masterUserId, args.masterPersonaId, args.targetEnv, args.targetUserId);
+        return row?.target_persona_id ?? null;
+    }
+    upsertMapping(row) {
+        this.db
+            .prepare(`INSERT INTO ${this.mapTable} (master_env, master_user_id, master_persona_id, target_env, target_user_id, target_persona_id)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(master_env, master_user_id, master_persona_id, target_env, target_user_id)
+         DO UPDATE SET target_persona_id = excluded.target_persona_id`)
+            .run(row.master_env, row.master_user_id, row.master_persona_id, row.target_env, row.target_user_id, row.target_persona_id);
+    }
+    getFingerprint(args) {
+        const row = this.db
+            .prepare(`SELECT fingerprint FROM ${this.fpTable} WHERE env = ? AND env_user_id = ? AND persona_id = ?`)
+            .get(args.env, args.envUserId, args.personaId);
+        return row?.fingerprint ?? null;
+    }
+    upsertFingerprint(row) {
+        this.db
+            .prepare(`INSERT INTO ${this.fpTable} (env, env_user_id, persona_id, fingerprint, last_seen_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(env, env_user_id, persona_id)
+         DO UPDATE SET fingerprint = excluded.fingerprint, last_seen_at = excluded.last_seen_at`)
+            .run(row.env, row.env_user_id, row.persona_id, row.fingerprint, row.last_seen_at);
+    }
+    beginRun(row) {
+        this.db
+            .prepare(`INSERT INTO ${this.runsTable} (id, master_env, master_env_user_id, started_at, status)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(row.id, row.master_env, row.master_env_user_id, row.started_at, row.status);
+    }
+    finishRun(args) {
+        this.db
+            .prepare(`UPDATE ${this.runsTable} SET finished_at = ?, status = ?, error = ? WHERE id = ?`)
+            .run(args.finishedAt, args.status, args.error ?? null, args.id);
+    }
+}

package/dist/sync.js

@@ -0,0 +1,416 @@
+/**
+ * Sync Engine
+ *
+ * Core synchronization logic for replicating AI Employees across environments.
+ * Uses fingerprinting for change detection and SQLite for state tracking.
+ */
+import crypto from "node:crypto";
+import { getMasterEnv, resolveBearerToken } from "./sdk/config.js";
+import { EmaApiError, EmaClient } from "./sdk/client.js";
+import { SYNC_METADATA_KEY } from "./sdk/models.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+// Sync tag format: <!-- synced_from:env/id -->
+const SYNC_TAG_REGEX = /<!-- synced_from:([^/]+)\/([a-f0-9-]+) -->/;
+const SYNC_TAG_CLEANUP_REGEX = /<!-- (?:synced_from|sync|_ema_sync):[^\n]*-->/g;
+// ─────────────────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+function nowIso() {
+    return new Date().toISOString();
+}
+function getPersonaTemplateId(p) {
+    return (p.template_id ?? p.templateId);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function stableStringify(v) {
+    if (v === null || v === undefined)
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(",")}]`;
+    if (typeof v === "object") {
+        const o = v;
+        const keys = Object.keys(o).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(v);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Sync Tag Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract clean description (without sync marker).
+ */
+export function getCleanDescription(description) {
+    if (!description)
+        return "";
+    return description.replace(SYNC_TAG_CLEANUP_REGEX, "").trim();
+}
+/**
+ * Build compact sync tag.
+ */
+export function buildSyncTag(masterEnv, masterId) {
+    return `<!-- synced_from:${masterEnv}/${masterId} -->`;
+}
+/**
+ * Build description with sync tag appended.
+ */
+export function buildDescriptionWithSyncTag(cleanDescription, masterEnv, masterId) {
+    const marker = buildSyncTag(masterEnv, masterId);
+    return cleanDescription ? `${cleanDescription}\n\n${marker}` : marker;
+}
+/**
+ * Parse sync tag from description.
+ */
+export function parseSyncTag(description) {
+    if (!description)
+        return null;
+    const match = description.match(SYNC_TAG_REGEX);
+    if (!match)
+        return null;
+    return { masterEnv: match[1], masterId: match[2] };
+}
+/**
+ * Clean proto_config by removing any legacy sync tags.
+ */
+function cleanProtoConfig(sourceProtoConfig) {
+    const base = { ...(sourceProtoConfig ?? {}) };
+    delete base[SYNC_METADATA_KEY];
+    return base;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Fingerprinting
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Compute a deterministic fingerprint (SHA256) of a persona's configuration.
+ * Used for change detection - only syncs when fingerprint differs.
+ */
+export function fingerprintPersona(p) {
+    // Clean proto_config (remove sync metadata)
+    let protoConfigForFingerprint = p.proto_config ?? null;
+    if (protoConfigForFingerprint && typeof protoConfigForFingerprint === "object") {
+        protoConfigForFingerprint = { ...protoConfigForFingerprint };
+        delete protoConfigForFingerprint[SYNC_METADATA_KEY];
+        if (Object.keys(protoConfigForFingerprint).length === 0) {
+            protoConfigForFingerprint = null;
+        }
+    }
+    // Clean description (remove sync tag)
+    const cleanDesc = getCleanDescription(p.description);
+    const canonical = {
+        name: p.name ?? null,
+        description: cleanDesc || null,
+        proto_config: protoConfigForFingerprint,
+        welcome_messages: p.welcome_messages ?? null,
+        trigger_type: p.trigger_type ?? null,
+        workflow_def: p.workflow_def ?? null,
+        workflow_interface: p.workflow_interface ?? null,
+        embedding_enabled: p.embedding_enabled ?? null,
+        // Excluded: id, status, access_level, status_log (computed/user-specific)
+    };
+    const bytes = Buffer.from(stableStringify(canonical), "utf8");
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Workflow Transformation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Transform workflow_def by replacing source persona ID with target persona ID.
+ * Required because workflow_def contains embedded persona ID references.
+ */
+export function transformWorkflowForTarget(workflowDef, sourcePersonaId, targetPersonaId) {
+    const transformed = JSON.parse(JSON.stringify(workflowDef));
+    // Transform workflowName.name.namespaces[2]
+    const workflowName = transformed.workflowName;
+    if (workflowName?.name?.namespaces && Array.isArray(workflowName.name.namespaces)) {
+        workflowName.name.namespaces = workflowName.name.namespaces.map((ns) => ns === sourcePersonaId ? targetPersonaId : ns);
+    }
+    // Replace all other occurrences
+    const jsonStr = JSON.stringify(transformed);
+    const replaced = jsonStr.replace(new RegExp(escapeRegex(sourcePersonaId), "g"), targetPersonaId);
+    return JSON.parse(replaced);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Routing
+// ─────────────────────────────────────────────────────────────────────────────
+function globToRegex(glob) {
+    const re = "^" + glob.split("").map((c) => (c === "*" ? ".*" : c === "?" ? "." : escapeRegex(c))).join("") + "$";
+    return new RegExp(re);
+}
+function personaMatchesRule(p, r) {
+    if ((r.personaIds ?? []).includes(p.id))
+        return true;
+    const name = (p.name ?? "").trim();
+    if (!name)
+        return false;
+    for (const pref of r.namePrefixes ?? []) {
+        if (name.startsWith(pref))
+            return true;
+    }
+    for (const g of r.nameGlobs ?? []) {
+        if (globToRegex(g).test(name))
+            return true;
+    }
+    for (const rx of r.nameRegexes ?? []) {
+        if (new RegExp(rx).test(name))
+            return true;
+    }
+    return false;
+}
+function pickTargets(cfg, persona) {
+    const routing = cfg.routing ?? [];
+    if (!routing || !Array.isArray(routing))
+        return { targetEnvs: [] };
+    const rules = routing.filter((r) => personaMatchesRule(persona, r));
+    const envs = new Set();
+    for (const r of rules) {
+        for (const t of r.targetEnvs ?? [])
+            envs.add(t);
+    }
+    return { targetEnvs: [...envs] };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Environment Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function envByName(cfg, name) {
+    const e = cfg.environments.find((x) => x.name === name);
+    if (!e)
+        throw new Error(`Unknown environment: ${name}`);
+    return e;
+}
+function buildEnv(e) {
+    return { name: e.name, baseUrl: e.baseUrl, bearerToken: resolveBearerToken(e.bearerTokenEnv) };
+}
+/**
+ * Run a single sync pass - scans master personas and replicates to targets.
+ */
+export async function syncOnce(cfg, state) {
+    const masterEnvCfg = getMasterEnv(cfg);
+    if (!masterEnvCfg) {
+        throw new Error("No master environment configured (isMaster: true)");
+    }
+    const masterEnvName = masterEnvCfg.name;
+    const runId = crypto.randomUUID();
+    state.beginRun({
+        id: runId,
+        master_env: masterEnvName,
+        master_env_user_id: masterEnvName, // Use env name as user ID
+        started_at: nowIso(),
+        status: "running",
+    });
+    const masterClient = new EmaClient(buildEnv(masterEnvCfg));
+    try {
+        const personas = await masterClient.getPersonasForTenant();
+        let scanned = 0;
+        let changed = 0;
+        let synced = 0;
+        let skipped = 0;
+        const errors = [];
+        for (let p of personas) {
+            scanned++;
+            const routing = pickTargets(cfg, p);
+            if (routing.targetEnvs.length === 0) {
+                skipped++;
+                continue;
+            }
+            // Fetch full persona if workflow_def missing
+            if (!p.workflow_def) {
+                const fullPersona = await masterClient.getPersonaById(p.id);
+                if (fullPersona) {
+                    p = { ...p, ...fullPersona };
+                }
+            }
+            const fp = fingerprintPersona(p);
+            const prevMasterFp = state.getFingerprint({ env: masterEnvName, envUserId: masterEnvName, personaId: p.id });
+            const masterChanged = prevMasterFp !== fp;
+            // Check which targets need sync
+            const targetsNeedingSync = [];
+            for (const targetEnvName of routing.targetEnvs) {
+                if (targetEnvName === masterEnvName)
+                    continue;
+                const mappedId = state.getMapping({
+                    masterEnv: masterEnvName,
+                    masterUserId: masterEnvName,
+                    masterPersonaId: p.id,
+                    targetEnv: targetEnvName,
+                    targetUserId: targetEnvName,
+                });
+                if (!mappedId) {
+                    targetsNeedingSync.push(targetEnvName);
+                    continue;
+                }
+                const targetFp = state.getFingerprint({ env: targetEnvName, envUserId: targetEnvName, personaId: mappedId });
+                if (targetFp !== fp)
+                    targetsNeedingSync.push(targetEnvName);
+            }
+            if (!masterChanged && targetsNeedingSync.length === 0) {
+                skipped++;
+                continue;
+            }
+            if (masterChanged)
+                changed++;
+            // Record master fingerprint
+            if (!cfg.dryRun) {
+                state.upsertFingerprint({
+                    env: masterEnvName,
+                    env_user_id: masterEnvName,
+                    persona_id: p.id,
+                    fingerprint: fp,
+                    last_seen_at: nowIso(),
+                });
+            }
+            // Sync to each target
+            for (const targetEnvName of targetsNeedingSync) {
+                const targetCfg = envByName(cfg, targetEnvName);
+                const targetClient = new EmaClient(buildEnv(targetCfg));
+                try {
+                    await upsertReplicaPersona({
+                        cfg,
+                        state,
+                        masterEnvName,
+                        masterPersona: p,
+                        masterFingerprint: fp,
+                        targetEnv: targetEnvName,
+                        targetClient,
+                        runId,
+                    });
+                    synced++;
+                }
+                catch (e) {
+                    errors.push(e instanceof Error ? e.message : String(e));
+                }
+            }
+        }
+        state.finishRun({
+            id: runId,
+            finishedAt: nowIso(),
+            status: errors.length ? "error" : "success",
+            error: errors.length ? errors.slice(0, 10).join(" | ") : undefined,
+        });
+        return { runId, scanned, changed, synced, skipped };
+    }
+    catch (e) {
+        state.finishRun({
+            id: runId,
+            finishedAt: nowIso(),
+            status: "error",
+            error: e instanceof Error ? e.message : String(e),
+        });
+        throw e;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Replica Upsert
+// ─────────────────────────────────────────────────────────────────────────────
+async function upsertReplicaPersona(args) {
+    const { cfg, state, masterEnvName, masterPersona, masterFingerprint, targetEnv, targetClient, runId } = args;
+    let mappedId = state.getMapping({
+        masterEnv: masterEnvName,
+        masterUserId: masterEnvName,
+        masterPersonaId: masterPersona.id,
+        targetEnv,
+        targetUserId: targetEnv,
+    });
+    // Search by name if no mapping
+    if (!mappedId && masterPersona.name) {
+        const targetPersonas = await targetClient.getPersonasForTenant();
+        const existingByName = targetPersonas.find((p) => p.name === masterPersona.name);
+        if (existingByName) {
+            mappedId = existingByName.id;
+            if (!cfg.dryRun) {
+                state.upsertMapping({
+                    master_env: masterEnvName,
+                    master_user_id: masterEnvName,
+                    master_persona_id: masterPersona.id,
+                    target_env: targetEnv,
+                    target_user_id: targetEnv,
+                    target_persona_id: mappedId,
+                });
+            }
+        }
+    }
+    if (cfg.dryRun)
+        return;
+    const cleanedProtoConfig = cleanProtoConfig(masterPersona.proto_config);
+    const cleanMasterDesc = getCleanDescription(masterPersona.description);
+    const descriptionWithTag = buildDescriptionWithSyncTag(cleanMasterDesc, masterEnvName, masterPersona.id);
+    if (mappedId) {
+        // Update existing
+        let transformedWorkflow;
+        if (masterPersona.workflow_def) {
+            transformedWorkflow = transformWorkflowForTarget(masterPersona.workflow_def, masterPersona.id, mappedId);
+        }
+        const upd = {
+            persona_id: mappedId,
+            name: masterPersona.name,
+            description: descriptionWithTag,
+            proto_config: cleanedProtoConfig,
+            welcome_messages: masterPersona.welcome_messages,
+            embedding_enabled: masterPersona.embedding_enabled,
+            workflow: transformedWorkflow,
+        };
+        try {
+            await targetClient.updateAiEmployee(upd, { verbose: cfg.verbose });
+            state.upsertFingerprint({
+                env: targetEnv,
+                env_user_id: targetEnv,
+                persona_id: mappedId,
+                fingerprint: masterFingerprint,
+                last_seen_at: nowIso(),
+            });
+            return;
+        }
+        catch (e) {
+            if (e instanceof EmaApiError && e.statusCode === 404) {
+                // Fall through to create
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    // Create new persona
+    const sourceTemplateId = getPersonaTemplateId(masterPersona);
+    if (!sourceTemplateId) {
+        throw new Error(`Cannot create persona in ${targetEnv}: missing template_id`);
+    }
+    const createReq = {
+        name: masterPersona.name ?? "Unnamed Persona",
+        description: descriptionWithTag,
+        template_id: sourceTemplateId,
+        proto_config: cleanedProtoConfig,
+        welcome_messages: masterPersona.welcome_messages,
+        trigger_type: masterPersona.trigger_type,
+    };
+    const created = await targetClient.createAiEmployee(createReq, { verbose: cfg.verbose });
+    const newId = created.persona_id ?? created.id;
+    if (!newId)
+        throw new Error(`Create in ${targetEnv} succeeded but no persona_id returned`);
+    // Follow-up: sync workflow now that we have target ID
+    if (masterPersona.workflow_def) {
+        const transformedWorkflow = transformWorkflowForTarget(masterPersona.workflow_def, masterPersona.id, newId);
+        await targetClient.updateAiEmployee({
+            persona_id: newId,
+            proto_config: cleanedProtoConfig,
+            workflow: transformedWorkflow,
+        });
+    }
+    state.upsertMapping({
+        master_env: masterEnvName,
+        master_user_id: masterEnvName,
+        master_persona_id: masterPersona.id,
+        target_env: targetEnv,
+        target_user_id: targetEnv,
+        target_persona_id: newId,
+    });
+    state.upsertFingerprint({
+        env: targetEnv,
+        env_user_id: targetEnv,
+        persona_id: newId,
+        fingerprint: masterFingerprint,
+        last_seen_at: nowIso(),
+    });
+}