@ema.co/mcp-toolkit 2026.4.9-2 → 2026.4.9-3

package/dist/mcp/guidance.js

@@ -198,7 +198,7 @@ function formatToolSection(tg) {
     }
     if (tg.toolName === "feedback") {
         extras.push("\nYour feedback is automatically collected and analyzed to improve the toolkit for all agents.");
-        extras.push("Include `knowledge_ref` to correlate feedback with specific knowledge documents — this drives automatic confidence scoring (documents with high negative feedback are auto-downgraded). Use `#fragment` for sub-document precision: `knowledge_ref=\"topic_auth#L51-L56\"` (lines), `knowledge_ref=\"topic_auth#authentication\"` (section). Same as GitHub URL fragments.");
+        extras.push("Include `knowledge_ref` to correlate feedback with specific knowledge documents — this drives both confidence scoring (MCP-side) and DE native ranking (UserEvents). All categories emit DE events: positive feedback sends conversion signals, negative feedback (correction, confusion, gap) sends zero-value conversions so DE learns what didn't work. Use `#fragment` for sub-document precision: `knowledge_ref=\"topic_auth#L51-L56\"` (lines), `knowledge_ref=\"topic_auth#authentication\"` (section).");
     }
     return `## ${title}
 Use the \`${tg.toolName}\` tool${tg.quickTip ? `. ${tg.quickTip}` : ""}:

package/dist/mcp/handlers/feedback/index.js

@@ -16,10 +16,8 @@ import { submitFeedback, listFeedback, listTelemetry, analyzeFeedback, rotateLog
 import { markProbeResponded } from "./probes.js";
 import { appendToOutbox, flushOutbox, getOutboxStats, readLocalMessages } from "./outbox.js";
 import { isRemoteEnabled } from "./remote-store.js";
-import { writeUserEvent } from "../../../knowledge/search-client.js";
 import { stripFragment } from "../../../knowledge/pipeline/confidence.js";
-import { getOrCreateClientId } from "./client-id.js";
-import { getAttributionToken } from "../knowledge/session-state.js";
+import { emitKnowledgeUserEvent, categoryToEvent } from "../knowledge/user-events.js";
 import { analyzeGlobal } from "./global-analysis.js";
 import { TOOLKIT_VERSION } from "../env/config.js";
 const VALID_CATEGORIES = ALL_CATEGORIES;
@@ -147,34 +145,13 @@ async function handleSubmit(args) {
             // Best-effort — don't block feedback submission
         }
     }
-    // UserEvent emission: fire DE conversion/view-item for positive feedback with knowledge_ref.
-    // Strip fragment — DE attribution tokens and document IDs are doc-level.
+    // UserEvent emission: fire DE event for ALL feedback with knowledge_ref.
+    // Positive → conversion (value 1.0), negative → conversion (value 0.0), neutral → view-item.
     // Independent of confidence loop — no guards, no cooldown. Fire-and-forget.
     if (docId) {
-        const isSuccess = category === "success";
-        const isHighQuality = category === "quality"
-            && (qualityData?.accuracy ?? 0) >= 4
-            && (qualityData?.usefulness ?? 0) >= 4;
-        const isInteraction = category === "interaction";
-        if (isSuccess || isHighQuality || isInteraction) {
-            const conversionType = isSuccess ? "knowledge-success"
-                : isHighQuality ? "knowledge-quality-high"
-                    : undefined; // interaction → view-item, no conversionType
-            getOrCreateClientId()
-                .then((clientId) => {
-                const token = getAttributionToken(docId);
-                writeUserEvent({
-                    eventType: conversionType ? "conversion" : "view-item",
-                    userPseudoId: clientId,
-                    ...(token ? { attributionToken: token } : {}),
-                    documents: [{
-                            id: docId,
-                            ...(conversionType ? { conversionValue: isSuccess ? 1.0 : 0.8 } : {}),
-                        }],
-                    ...(conversionType ? { conversionType } : {}),
-                }).catch(() => { });
-            })
-                .catch(() => { });
+        const eventOpts = categoryToEvent(category, qualityData);
+        if (eventOpts) {
+            emitKnowledgeUserEvent({ ...eventOpts, docIds: [docId] });
         }
     }
     return {

package/dist/mcp/handlers/knowledge/outcome-feedback.js

@@ -20,8 +20,7 @@
  */
 import { getConsultedDocs } from "./session-state.js";
 import { processConfidenceFeedback } from "./confidence-loop.js";
-import { writeUserEvent } from "../../../knowledge/search-client.js";
-import { getOrCreateClientId } from "../feedback/client-id.js";
+import { emitKnowledgeUserEvent } from "./user-events.js";
 /** Weight multiplier per signal layer */
 const LAYER_WEIGHTS = {
     system: 0.1, // API accepted it — weakest signal
@@ -178,27 +177,17 @@ export async function emitOutcomeFeedback(event) {
             }
         }
     }
-    // Fire UserEvents (fire-and-forget)
-    getOrCreateClientId()
-        .then((clientId) => {
-        // Conversion value = outcome quality × layer weight
-        const baseValue = outcome.quality === "success" ? 1.0
-            : outcome.quality === "partial" ? 0.5
-                : 0;
-        const conversionValue = baseValue * weight;
-        const isConversion = outcome.isPositive && outcome.quality !== "accepted";
-        const documents = [...docs].map((docId) => ({
-            id: docId,
-            ...(isConversion ? { conversionValue } : {}),
-        }));
-        writeUserEvent({
-            eventType: isConversion ? "conversion" : "view-item",
-            userPseudoId: clientId,
-            ...(isConversion ? { conversionType: eventType } : {}),
-            documents,
-        }).catch(() => { });
-    })
-        .catch(() => { });
+    // Fire UserEvents via centralized emitter (handles attribution tokens + fragment stripping)
+    const baseValue = outcome.quality === "success" ? 1.0
+        : outcome.quality === "partial" ? 0.5
+            : 0;
+    const conversionValue = baseValue * weight;
+    emitKnowledgeUserEvent({
+        docIds: [...docs],
+        signal: outcome.isPositive ? "positive" : "negative",
+        conversionType: eventType,
+        conversionValue,
+    });
     console.error(`[OUTCOME-FEEDBACK] ${eventType} (layer=${layer}, weight=${weight}): ` +
         `${docs.size} consulted docs, ${updates} confidence updates`);
     return { docs_processed: docs.size, confidence_updates: updates, event_type: eventType };

package/dist/mcp/handlers/knowledge/user-events.js

@@ -0,0 +1,112 @@
+/**
+ * Centralized DE UserEvent emission for knowledge feedback signals.
+ *
+ * Single entry point for all feedback → DE UserEvent emission.
+ * Handles: attribution token lookup, fragment stripping, signal→event mapping,
+ * and fire-and-forget delivery.
+ *
+ * Ownership boundary:
+ * - MCP OWNS: interaction/feedback collection, signal classification
+ * - knowledge-service WILL OWN: DE transport, attribution, event schema
+ *
+ * TODO(knowledge-service): migrate DE transport when knowledge-service owns DE integration.
+ * MCP will continue to own feedback collection and signal classification.
+ * knowledge-service will own: writeUserEvent, attribution cache, event→DE mapping.
+ */
+import { writeUserEvent } from "../../../knowledge/search-client.js";
+import { getOrCreateClientId } from "../feedback/client-id.js";
+import { getAttributionToken } from "./session-state.js";
+import { stripFragment } from "../../../knowledge/pipeline/confidence.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Feedback category → signal mapping
+// ─────────────────────────────────────────────────────────────────────────────
+// TODO(knowledge-service): signal classification stays in MCP (owns feedback semantics)
+const CATEGORY_EVENT_MAP = {
+    // Positive signals
+    success: { signal: "positive", conversionType: "knowledge-success", value: 1.0 },
+    interaction: { signal: "neutral", conversionType: "", value: 0 },
+    // Negative signals
+    correction: { signal: "negative", conversionType: "knowledge-correction", value: 0.0 },
+    confusion: { signal: "negative", conversionType: "knowledge-confusion", value: 0.0 },
+    gap: { signal: "negative", conversionType: "knowledge-gap", value: 0.0 },
+    error_unclear: { signal: "negative", conversionType: "knowledge-error", value: 0.0 },
+};
+/**
+ * Map a feedback category + quality data to UserEvent parameters.
+ * Returns undefined for categories that shouldn't emit events (e.g., suggestion, probe_response).
+ */
+export function categoryToEvent(category, qualityData) {
+    // Quality category: only emit for high-quality ratings
+    if (category === "quality") {
+        const isHighQuality = (qualityData?.accuracy ?? 0) >= 4
+            && (qualityData?.usefulness ?? 0) >= 4;
+        if (!isHighQuality)
+            return undefined;
+        return {
+            docIds: [], // caller fills in
+            signal: "positive",
+            conversionType: "knowledge-quality-high",
+            conversionValue: 0.8,
+        };
+    }
+    const mapped = CATEGORY_EVENT_MAP[category];
+    if (!mapped)
+        return undefined;
+    return {
+        docIds: [], // caller fills in
+        signal: mapped.signal,
+        conversionType: mapped.conversionType || undefined,
+        conversionValue: mapped.value,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Centralized emitter
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Emit a DE UserEvent for knowledge feedback signals.
+ *
+ * Handles attribution token lookup, fragment stripping, and fire-and-forget delivery.
+ * All feedback paths (explicit feedback, outcome feedback) should use this function
+ * instead of calling writeUserEvent directly.
+ *
+ * TODO(knowledge-service): DE transport (writeUserEvent, attribution) moves to shared lib.
+ * This function becomes: knowledgeService.emitFeedbackEvent({ docIds, signal, ... })
+ */
+export function emitKnowledgeUserEvent(opts) {
+    if (opts.docIds.length === 0)
+        return;
+    const isConversion = opts.signal !== "neutral";
+    const conversionValue = opts.conversionValue
+        ?? (opts.signal === "positive" ? 1.0 : opts.signal === "negative" ? 0.0 : undefined);
+    getOrCreateClientId()
+        .then((clientId) => {
+        // Strip fragments and dedupe doc IDs
+        const seen = new Set();
+        const documents = [];
+        let attributionToken;
+        for (const rawId of opts.docIds) {
+            const docId = stripFragment(rawId);
+            if (!docId || seen.has(docId))
+                continue;
+            seen.add(docId);
+            // Use first available attribution token (all docs from same search share one)
+            if (!attributionToken) {
+                attributionToken = getAttributionToken(docId);
+            }
+            documents.push({
+                id: docId,
+                ...(isConversion && conversionValue !== undefined ? { conversionValue } : {}),
+            });
+        }
+        if (documents.length === 0)
+            return;
+        writeUserEvent({
+            eventType: isConversion ? "conversion" : "view-item",
+            userPseudoId: clientId,
+            ...(attributionToken ? { attributionToken } : {}),
+            ...(isConversion && opts.conversionType ? { conversionType: opts.conversionType } : {}),
+            documents,
+        }).catch(() => { });
+    })
+        .catch(() => { });
+}

package/dist/mcp/knowledge-guidance-topics.js

@@ -692,13 +692,22 @@ The toolkit also collects anonymous telemetry (tool usage, error rates, latency)
 
 ## Knowledge Confidence Scoring
 
-Feedback drives automatic confidence scoring on knowledge documents. Include a knowledge_ref to correlate feedback with specific documents:
-- knowledge_ref="<document_id>" — top-level parameter, triggers real-time confidence update
-- Negative categories (downgrade score): gap, confusion, correction, error_unclear
-- Positive categories (upgrade score): success, interaction
-- Nuanced: quality (depends on accuracy/usefulness scores — <3 negative, >=4 positive, no scores = neutral)
+Feedback drives two parallel DE ranking signals when knowledge_ref is provided:
 
-Documents with negative feedback are auto-downgraded. Labels are derived from score thresholds:
+1. **Confidence Loop (MCP-side)** — immediate structData.confidence_score update via PATCH
+2. **DE UserEvents (native ranking)** — conversion/view-item events for DE's ML-based ranking
+
+All feedback categories emit DE UserEvents:
+- Positive (conversion, value=1.0): success, interaction
+- Negative (conversion, value=0.0): correction, confusion, gap, error_unclear
+- Quality: depends on accuracy/usefulness scores (>=4 both → positive at 0.8, else skipped)
+- Neutral (view-item): interaction
+
+Include knowledge_ref to correlate feedback with specific documents:
+- knowledge_ref="<document_id>" — triggers both confidence update and DE event
+- Use #fragment for sub-document precision: knowledge_ref="topic_auth#L51-L56"
+
+Labels derived from confidence score thresholds:
 - verified (>= 0.80) — no significant negative feedback
 - inferred (0.50–0.79) — some negative feedback received
 - low-confidence (< 0.50) — multiple negative reports, auto-downgraded in search

package/package.json

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