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

package/dist/knowledge/pipeline/confidence.js

@@ -85,6 +85,19 @@ export function scoreToLabel(score) {
         return "inferred";
     return "low-confidence";
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Fragment helpers — GitHub-style #fragment on knowledge_ref
+// ─────────────────────────────────────────────────────────────────────────────
+/** Strip #fragment from a knowledge_ref, returning the bare document ID. */
+export function stripFragment(ref) {
+    const idx = ref.indexOf("#");
+    return idx === -1 ? ref : ref.slice(0, idx);
+}
+/** Extract the #fragment from a knowledge_ref, or undefined if none. */
+export function extractFragment(ref) {
+    const idx = ref.indexOf("#");
+    return idx === -1 ? undefined : ref.slice(idx + 1);
+}
 /**
  * Compute confidence adjustment based on the ratio of negative to total feedback.
  *

package/dist/knowledge/pipeline/document.js

@@ -34,20 +34,30 @@ export function toDeDocument(doc) {
     const textContent = doc.structData?.content
         || [doc.structData?.name, doc.structData?.summary, doc.structData?.description].filter(Boolean).join("\n");
     const contentHash = computeContentHash(textContent || doc.id);
+    const now = new Date().toISOString();
     const augmented = {
         ...doc.structData,
         content_hash: contentHash,
-        augmented_at: new Date().toISOString(),
+        augmented_at: now,
         status: doc.structData?.status ?? "active",
         confidence_score: doc.structData?.confidence_score
             ?? computeConfidenceScore(doc.structData?.provenance ?? "inferred"),
+        // Lifecycle timestamps — set once at publish, preserved on re-publish
+        // Aligned with knowledge-service's 3-layer model (produced_at/published_at)
+        published_at: doc.structData?.published_at ?? now,
+        produced_at: doc.structData?.produced_at ?? now,
     };
-    // Compute freshness_tier from TTL if present (set by extraction pipeline from YAML config)
+    // Compute freshness_tier: TTL-based (explicit) or content-age (universal)
     if (doc.structData?.ttl) {
         const tier = computeFreshnessTier(doc.structData.ttl, doc.structData.extracted_at);
         if (tier)
             augmented.freshness_tier = tier;
     }
+    else {
+        const tier = computeContentFreshnessTier(augmented.produced_at);
+        if (tier)
+            augmented.freshness_tier = tier;
+    }
     augmentByType(doc, augmented);
     return {
         id: sanitizeId(doc.id),
@@ -58,6 +68,25 @@ export function toDeDocument(doc) {
         },
     };
 }
+/**
+ * Universal content-age freshness tier (no TTL config required).
+ * Applies to all docs via produced_at — DE's boost-fresh/demote-expired
+ * controls handle the ranking impact.
+ */
+// TODO(knowledge-service): migrate alongside computeFreshnessTier when shared lib is ready
+export function computeContentFreshnessTier(producedAt) {
+    if (!producedAt)
+        return undefined;
+    const ageMs = Date.now() - new Date(producedAt).getTime();
+    if (Number.isNaN(ageMs))
+        return undefined;
+    const ageDays = ageMs / (86_400_000);
+    if (ageDays < 7)
+        return "fresh";
+    if (ageDays >= 90)
+        return "stale";
+    return undefined; // neutral — no boost or penalty
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Type-Dispatched Augmentation
 // ─────────────────────────────────────────────────────────────────────────────

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=\"<doc_id>\"` to correlate feedback with specific knowledge documents — this drives automatic confidence scoring (documents with high negative feedback are auto-downgraded).");
+        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,9 +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 { getOrCreateClientId } from "./client-id.js";
-import { getAttributionToken } from "../knowledge/session-state.js";
+import { stripFragment } from "../../../knowledge/pipeline/confidence.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;
@@ -134,43 +133,25 @@ async function handleSubmit(args) {
         }
     }
     // Confidence loop: if feedback references a knowledge doc, update its confidence in DE
+    // Strip #fragment — confidence scoring operates at the document level
     let confidenceUpdate;
-    if (knowledgeRef && CONFIDENCE_CATEGORIES.includes(category)) {
+    const docId = knowledgeRef ? stripFragment(knowledgeRef) : undefined;
+    if (docId && CONFIDENCE_CATEGORIES.includes(category)) {
         try {
             const { processConfidenceFeedback } = await import("../knowledge/confidence-loop.js");
-            confidenceUpdate = await processConfidenceFeedback(category, knowledgeRef, qualityData) ?? undefined;
+            confidenceUpdate = await processConfidenceFeedback(category, docId, qualityData) ?? undefined;
         }
         catch {
             // Best-effort — don't block feedback submission
         }
     }
-    // UserEvent emission: fire DE conversion/view-item for positive feedback with knowledge_ref.
+    // 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 (knowledgeRef) {
-        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(knowledgeRef);
-                writeUserEvent({
-                    eventType: conversionType ? "conversion" : "view-item",
-                    userPseudoId: clientId,
-                    ...(token ? { attributionToken: token } : {}),
-                    documents: [{
-                            id: knowledgeRef,
-                            ...(conversionType ? { conversionValue: isSuccess ? 1.0 : 0.8 } : {}),
-                        }],
-                    ...(conversionType ? { conversionType } : {}),
-                }).catch(() => { });
-            })
-                .catch(() => { });
+    if (docId) {
+        const eventOpts = categoryToEvent(category, qualityData);
+        if (eventOpts) {
+            emitKnowledgeUserEvent({ ...eventOpts, docIds: [docId] });
         }
     }
     return {

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

@@ -22,7 +22,7 @@ import { SESSION_ID } from "./session.js";
 // Category classification lives in confidence.ts (knowledge pipeline layer)
 // Re-export here so feedback handlers can use it without reaching into pipeline internals
 export { FeedbackSignal, CATEGORY_SIGNAL, } from "../../../knowledge/pipeline/confidence.js";
-import { CATEGORY_SIGNAL, FeedbackSignal } from "../../../knowledge/pipeline/confidence.js";
+import { CATEGORY_SIGNAL, FeedbackSignal, stripFragment, extractFragment } from "../../../knowledge/pipeline/confidence.js";
 /** All valid category names — derived from the signal map */
 export const ALL_CATEGORIES = Object.keys(CATEGORY_SIGNAL);
 /** Categories that affect confidence scoring (negative, positive, or quality) */
@@ -359,28 +359,42 @@ export async function analyzeFeedback(rootOverride) {
     };
     deduplicateEntries(feedback.filter((e) => e.category === "gap"), "Documentation gap");
     deduplicateEntries(feedback.filter((e) => e.category === "confusion"), "Unclear guidance");
-    // Graph-correlated insights: group feedback by knowledge_ref
+    // Graph-correlated insights: group feedback by knowledge_ref (doc-level)
+    // Fragment hotspots tracked per document (e.g., "L51-L56": 3)
     const graphCorrelations = {};
     for (const entry of feedback) {
         const ref = entry.quality_data?.knowledge_ref;
         if (!ref)
             continue;
-        if (!graphCorrelations[ref]) {
-            graphCorrelations[ref] = { count: 0, categories: {} };
+        const docId = stripFragment(ref);
+        const fragment = extractFragment(ref);
+        if (!graphCorrelations[docId]) {
+            graphCorrelations[docId] = { count: 0, categories: {} };
+        }
+        graphCorrelations[docId].count++;
+        graphCorrelations[docId].categories[entry.category] =
+            (graphCorrelations[docId].categories[entry.category] ?? 0) + 1;
+        if (fragment) {
+            if (!graphCorrelations[docId].fragments) {
+                graphCorrelations[docId].fragments = {};
+            }
+            graphCorrelations[docId].fragments[fragment] =
+                (graphCorrelations[docId].fragments[fragment] ?? 0) + 1;
         }
-        graphCorrelations[ref].count++;
-        graphCorrelations[ref].categories[entry.category] =
-            (graphCorrelations[ref].categories[entry.category] ?? 0) + 1;
     }
     // Compute average accuracy for quality-rated nodes
     for (const entry of feedback) {
         const ref = entry.quality_data?.knowledge_ref;
         if (!ref || !entry.quality_data?.accuracy)
             continue;
-        const corr = graphCorrelations[ref];
+        const docId = stripFragment(ref);
+        const corr = graphCorrelations[docId];
         if (!corr)
             continue;
-        const qualityEntries = feedback.filter((e) => e.quality_data?.knowledge_ref === ref && e.quality_data?.accuracy != null);
+        const qualityEntries = feedback.filter((e) => {
+            const eRef = e.quality_data?.knowledge_ref;
+            return eRef && stripFragment(eRef) === docId && e.quality_data?.accuracy != null;
+        });
         corr.avgAccuracy =
             qualityEntries.reduce((sum, e) => sum + (e.quality_data.accuracy ?? 0), 0) /
                 qualityEntries.length;

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/dist/mcp/tools.js

@@ -786,10 +786,11 @@ A **profile** = tenant + environment + auth. Example: "acme-corp-prod" = Acme Co
 - \`feedback(method="submit", category="suggestion", message="...")\` - suggest improvements
 - \`feedback(method="submit", category="probe_response", message="<answer>", context="<probe.id>")\` - respond to a _probe question
 - \`feedback(method="submit", category="quality", message="...", knowledge_ref="topic_authentication")\` - rate knowledge accuracy (drives confidence scoring)
-- \`feedback(method="submit", category="correction", message="...", knowledge_ref="rule_get-before-modify")\` - report wrong information
+- \`feedback(method="submit", category="correction", message="...", knowledge_ref="rule_get-before-modify#L51-L56")\` - report wrong info at specific lines
+- \`feedback(method="submit", category="correction", message="...", knowledge_ref="topic_auth#authentication")\` - report issue in a section
 
 ## Knowledge Confidence
-Include \`knowledge_ref\` to correlate feedback with specific knowledge documents. Documents with high negative feedback are auto-downgraded in search results.
+Include \`knowledge_ref\` to correlate feedback with specific knowledge documents. Use \`#fragment\` for sub-document precision (e.g., \`topic_auth#L51-L56\` for lines, \`topic_auth#authentication\` for sections). Documents with high negative feedback are auto-downgraded in search results.
 
 ## Review Feedback
 - \`feedback(method="list")\` - view recent feedback
@@ -842,7 +843,7 @@ Messages are emitted by MCP response actions (search, publish, deploy) and stay
                     },
                     knowledge_ref: {
                         type: "string",
-                        description: "Knowledge document ID this feedback relates to (e.g. 'topic_authentication', 'rule_get-before-modify'). Drives automatic confidence scoring — documents with negative feedback rank lower in search.",
+                        description: "Knowledge document ID, optionally with #fragment for sub-document precision. Examples: 'topic_auth', 'topic_auth#L51-L56' (lines), 'topic_auth#L51' (single line), 'topic_auth#authentication' (section). Same as GitHub URL fragments. Drives confidence scoring at the document level (fragment stripped for scoring, preserved for reporting).",
                     },
                     severity: {
                         type: "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "2026.4.9-1",
+  "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",