@ema.co/mcp-toolkit 2026.3.25-4 → 2026.4.9

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

@@ -7,6 +7,57 @@
 import { loadConfig, saveConfig, addProfile, removeProfile, setCurrentProfile, listProfiles, getActiveProfile, slugify, profileName, } from "../../../config/profile.js";
 import { invalidateEnvCache } from "../env/config.js";
 import { tryGcloudAuth } from "../../../auth/gcloud.js";
+/**
+ * Derive API URL, app URL, and environment name from a custom app URL.
+ * Supports any `*.ema.co` hostname. Returns null for non-ema.co domains.
+ */
+function deriveFromAppUrl(appUrl) {
+    try {
+        const url = new URL(appUrl.includes("://") ? appUrl : `https://${appUrl}`);
+        const hostname = url.hostname;
+        // Match *.ema.co pattern
+        const match = hostname.match(/^(.+)\.ema\.co$/);
+        if (!match)
+            return null;
+        const subdomain = match[1]; // e.g., "staging.acme", "app", "demo"
+        // Well-known frontends map to standard envs
+        if (subdomain === "app") {
+            return { apiUrl: "https://api.ema.co", appUrl: "https://app.ema.co", envName: "prod" };
+        }
+        if (["demo", "staging", "dev"].includes(subdomain)) {
+            return {
+                apiUrl: `https://api.${subdomain}.ema.co`,
+                appUrl: `https://${subdomain}.ema.co`,
+                envName: subdomain,
+            };
+        }
+        // Custom subdomain: derive API URL by prepending "api."
+        return {
+            apiUrl: `https://api.${subdomain}.ema.co`,
+            appUrl: `https://${subdomain}.ema.co`,
+            envName: subdomain,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Probe an API URL to check reachability. Returns true if the endpoint
+ * responds (even with 401/403 — means it's reachable but auth-gated).
+ */
+async function probeApiUrl(apiUrl) {
+    try {
+        const resp = await fetch(`${apiUrl.replace(/\/$/, "")}/api/health`, {
+            method: "HEAD",
+            signal: AbortSignal.timeout(5000),
+        });
+        return resp.ok || resp.status === 401 || resp.status === 403;
+    }
+    catch {
+        return false;
+    }
+}
 export async function handleConfig(args) {
     const method = args.method;
     switch (method) {
@@ -161,14 +212,56 @@ async function handleStatus() {
 // Login
 // ─────────────────────────────────────────────────────────────────────────────
 async function handleLogin(args) {
-    // Use explicit env > preference default_env > "prod"
-    const envName = args.env || loadConfig().preferences.default_env || "prod";
+    const customAppUrl = args.app_url;
+    const customApiUrl = args.api_url;
     const tenantHint = args.tenant;
     const directToken = args.token;
+    // Resolve URLs and env name from custom app_url or standard env
+    let envName;
+    let resolvedApiUrl;
+    let resolvedAppUrl;
+    let probeWarning;
+    if (customAppUrl) {
+        const derived = deriveFromAppUrl(customAppUrl);
+        if (derived) {
+            envName = args.env || derived.envName;
+            resolvedApiUrl = customApiUrl?.replace(/\/$/, "") ?? derived.apiUrl;
+            resolvedAppUrl = derived.appUrl;
+        }
+        else {
+            // Non-ema.co domain — derive env from hostname, require api_url if not provided
+            const parsed = new URL(customAppUrl.includes("://") ? customAppUrl : `https://${customAppUrl}`);
+            envName = args.env || slugify(parsed.hostname.split(".")[0]);
+            resolvedAppUrl = `${parsed.protocol}//${parsed.host}`;
+            if (customApiUrl) {
+                resolvedApiUrl = customApiUrl.replace(/\/$/, "");
+            }
+            else {
+                // Best guess: api.{hostname}
+                resolvedApiUrl = `${parsed.protocol}//api.${parsed.host}`;
+            }
+        }
+        // Probe the API URL — warn but don't block if unreachable
+        const reachable = await probeApiUrl(resolvedApiUrl);
+        if (!reachable) {
+            probeWarning =
+                `Derived API URL (${resolvedApiUrl}) did not respond. ` +
+                    `Login will proceed with this URL, but if auth fails, verify the correct API URL ` +
+                    `and retry with: config(method="login", app_url="${customAppUrl}", api_url="<correct_url>")`;
+        }
+    }
+    else {
+        // Standard flow: explicit env > preference default_env > "prod"
+        envName = args.env || loadConfig().preferences.default_env || "prod";
+        resolvedApiUrl = customApiUrl?.replace(/\/$/, "")
+            ?? (envName === "prod" ? "https://api.ema.co" : `https://api.${envName}.ema.co`);
+    }
     try {
         const { login } = await import("../../../auth/login.js");
         const result = await login({
             environment: envName,
+            baseUrl: resolvedApiUrl,
+            ...(resolvedAppUrl ? { appUrl: resolvedAppUrl } : {}),
             tenantId: tenantHint,
             token: directToken,
         });
@@ -183,7 +276,8 @@ async function handleLogin(args) {
             },
             environment: {
                 name: envName,
-                url: `https://api${envName === "prod" ? "" : `.${envName}`}.ema.co`,
+                url: resolvedApiUrl,
+                ...(resolvedAppUrl ? { app_url: resolvedAppUrl } : {}),
             },
             user: { email: result.userEmail ?? "" },
             created_at: new Date().toISOString(),
@@ -225,6 +319,7 @@ async function handleLogin(args) {
                 profile_name: profileName(slugify(t.company_name), envName),
                 active: t.tenant_id === result.tenantId,
             })),
+            ...(probeWarning ? { _warning: probeWarning } : {}),
             _tip: "Token stored. All tools will now use this profile automatically.",
             _next_step: `persona(method="list", profile="${name}")`,
         };
@@ -362,7 +457,7 @@ async function handleUse(args) {
 // ─────────────────────────────────────────────────────────────────────────────
 // Set / Get preferences
 // ─────────────────────────────────────────────────────────────────────────────
-const ALLOWED_KEYS = ["debug", "default_env", "resource_source"];
+const ALLOWED_KEYS = ["debug", "default_env", "resource_source", "api_url", "app_url"];
 async function handleSet(args) {
     const key = args.key;
     const value = args.value;
@@ -372,11 +467,14 @@ async function handleSet(args) {
             error: `Unknown preference key: ${key}. Available: ${ALLOWED_KEYS.join(", ")}`,
         };
     }
-    // Validate default_env values
+    // Validate default_env values — accept well-known envs + any env from existing profiles
     if (key === "default_env") {
-        const valid = ["prod", "staging", "dev", "demo"];
-        if (!valid.includes(value)) {
-            return { error: `Invalid default_env: ${value}. Must be one of: ${valid.join(", ")}` };
+        const config = loadConfig();
+        const wellKnown = ["prod", "staging", "dev", "demo"];
+        const profileEnvNames = Object.values(config.profiles).map(p => p.environment.name);
+        const allValid = [...new Set([...wellKnown, ...profileEnvNames])];
+        if (!allValid.includes(value)) {
+            return { error: `Invalid default_env: ${value}. Must be one of: ${allValid.join(", ")}` };
         }
     }
     // Validate resource_source values
@@ -386,6 +484,24 @@ async function handleSet(args) {
             return { error: `Invalid resource_source: ${value}. Must be one of: ${valid.join(", ")}` };
         }
     }
+    // api_url and app_url update the current profile's environment URLs
+    if (key === "api_url" || key === "app_url") {
+        const config = loadConfig();
+        const profile = config.profiles[config.current_profile];
+        if (!profile) {
+            return { error: "No active profile. Log in first.", _tip: 'config(method="login")' };
+        }
+        const previous = key === "api_url" ? profile.environment.url : profile.environment.app_url;
+        if (key === "api_url") {
+            profile.environment.url = value;
+        }
+        else {
+            profile.environment.app_url = value;
+        }
+        saveConfig(config);
+        invalidateEnvCache();
+        return { set: { key, value, previous, profile: config.current_profile } };
+    }
     const config = loadConfig();
     const previous = config.preferences[key];
     config.preferences[key] = value;

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

@@ -16,6 +16,9 @@ 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 { analyzeGlobal } from "./global-analysis.js";
 import { TOOLKIT_VERSION } from "../env/config.js";
 const VALID_CATEGORIES = ALL_CATEGORIES;
@@ -141,6 +144,35 @@ async function handleSubmit(args) {
             // Best-effort — don't block feedback submission
         }
     }
+    // UserEvent emission: fire DE conversion/view-item for positive feedback with knowledge_ref.
+    // 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(() => { });
+        }
+    }
     return {
         success: true,
         feedback_id: entry.id,

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

@@ -12,6 +12,7 @@ import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { getToolkitRoot } from "../../../sdk/paths.js";
+import { userEventCounters } from "../../../knowledge/search-client.js";
 import { appendToOutbox } from "./outbox.js";
 import { isRemoteEnabled } from "./remote-store.js";
 import { SESSION_ID } from "./session.js";
@@ -384,6 +385,8 @@ export async function analyzeFeedback(rootOverride) {
             qualityEntries.reduce((sum, e) => sum + (e.quality_data.accuracy ?? 0), 0) /
                 qualityEntries.length;
     }
+    // UserEvent pipeline counters (in-memory, this session only)
+    const hasEventActivity = userEventCounters.sent > 0 || userEventCounters.failed > 0;
     return {
         summary: {
             total_feedback: feedback.length,
@@ -394,6 +397,7 @@ export async function analyzeFeedback(rootOverride) {
             telemetry_period: telemetry.length > 0
                 ? { from: telemetry[0].ts, to: telemetry[telemetry.length - 1].ts }
                 : null,
+            ...(hasEventActivity ? { user_events: { ...userEventCounters } } : {}),
         },
         category_breakdown: categoryBreakdown,
         hot_spots: {

package/dist/mcp/handlers/knowledge/confidence-loop.js

@@ -40,13 +40,18 @@ const cooldownMap = new Map();
 let sessionUpdateCount = 0;
 /** Per-document feedback history for graduated scoring */
 const feedbackHistoryMap = new Map();
+/** Recognized outcome suffixes from the outcome-feedback module */
+const OUTCOME_SUFFIXES = ["_success", "_failure", "_partial", "_misaligned", "_accepted"];
 /** Classify feedback strength based on context */
 export function classifyEvidence(category, context) {
-    // Deploy failures are hard evidence
-    if (context?.includes("deploy_failure"))
-        return "hard";
-    if (category === "correction" && context?.includes("deploy"))
-        return "hard";
+    // Any tool outcome with a structured context suffix is hard evidence.
+    // Context format from outcome-feedback: "{tool}_{operation}_{quality}"
+    if (context) {
+        for (const suffix of OUTCOME_SUFFIXES) {
+            if (context.endsWith(suffix))
+                return "hard";
+        }
+    }
     // Explicit corrections with knowledge_ref are medium-hard
     if (category === "correction")
         return "hard";

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

@@ -15,6 +15,8 @@ import { inferSourceType } from "../../../knowledge/pipeline/types.js";
 import { computeConfidenceScore } from "../../../knowledge/pipeline/confidence.js";
 import { actionsForSearchResults, actionsForNoResults, actionsForPublish } from "../response-actions.js";
 import { generateRelatedQueries } from "./related-queries.js";
+import { getOrCreateClientId } from "../feedback/client-id.js";
+import { recordSearchResults } from "./session-state.js";
 const GCS_BUCKET = "em1-knowledge";
 async function checkSupersedeGuard(supersedes) {
     if (!supersedes || supersedes.length === 0)
@@ -568,7 +570,8 @@ async function handleQuery(args) {
         if (response.generativeAnswer) {
             result.generative_answer = response.generativeAnswer;
             result.citations = response.citations;
-            result._warning = "Generative answer is AI-synthesized. Verify against source documents.";
+            result._warning = "Generative answer is AI-synthesized. Code examples may be fabricated or simplified — NEVER copy JSON without verification.";
+            result._next_step = 'Use workflow(mode="get") for canonical workflow_def format, or knowledge("schema/workflow-def", detail="excerpts") for validated examples.';
         }
         // Follow-up token for multi-turn answer conversations
         if (response.answerQueryToken) {
@@ -599,6 +602,8 @@ async function handleQuery(args) {
         if (related.length > 0) {
             result._related_queries = related;
         }
+        // Record results in session state for attribution cache + consultedDocs tracking
+        recordSearchResults(results.map((r) => ({ id: r.id })), response.attributionToken);
         fireSearchEvent(query, response.attributionToken);
         return result;
     }
@@ -649,6 +654,8 @@ function contextualNextStep(results) {
         return "Follow the guide steps relevant to your task";
     return "Review results and refine search if needed";
 }
+/** Cached client ID for UserEvent pseudoId — resolved once, then sync. */
+let _cachedPseudoId;
 function fireSearchEvent(query, attributionToken) {
     recordTelemetry({
         type: "search_event",
@@ -657,10 +664,21 @@ function fireSearchEvent(query, attributionToken) {
         ok: true,
         resource_uri: attributionToken,
     }).catch(() => { });
-    writeUserEvent({
-        eventType: "search",
-        userPseudoId: "mcp-agent",
-        attributionToken,
-        searchInfo: { searchQuery: query },
-    }).catch(() => { });
+    // Resolve pseudoId: use cached value if available, otherwise resolve async (first call only)
+    const emit = (pseudoId) => {
+        writeUserEvent({
+            eventType: "search",
+            userPseudoId: pseudoId,
+            attributionToken,
+            searchInfo: { searchQuery: query },
+        }).catch(() => { });
+    };
+    if (_cachedPseudoId) {
+        emit(_cachedPseudoId);
+    }
+    else {
+        getOrCreateClientId()
+            .then((id) => { _cachedPseudoId = id; emit(id); })
+            .catch(() => { emit("mcp-agent"); }); // fallback if client-id resolution fails
+    }
 }

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

@@ -0,0 +1,205 @@
+/**
+ * Outcome Feedback — Layered signal emitter for knowledge quality feedback.
+ *
+ * Captures the full lifecycle of an agent interaction:
+ *
+ *   Intent stated → work done → outcome assessed at multiple layers
+ *
+ * Signal layers (each carries different weight):
+ *   1. API acceptance  (0.1) — system accepted the input structurally
+ *   2. Agent assessment (0.3) — agent's self-evaluation of alignment
+ *   3. Agent validation (0.5) — functional testing (conversation, debug)
+ *   4. End-user signal  (1.0) — real user responded, kept using it, or abandoned
+ *
+ * Intent tracking:
+ *   - Original intent is recorded at the start of the interaction
+ *   - If intent pivots mid-journey, that's knowledge (not failure):
+ *     "Users with intent X often pivot to Y" → proactive suggestion for next agent
+ *   - Outcome is assessed against the FINAL intent, not the original
+ *   - But the pivot itself is published as a pattern signal
+ */
+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";
+/** Weight multiplier per signal layer */
+const LAYER_WEIGHTS = {
+    system: 0.1, // API accepted it — weakest signal
+    agent: 0.3, // Agent self-assessment — has context but may be biased
+    validation: 0.5, // Functional testing — objective but synthetic
+    user: 1.0, // End-user response — ground truth
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Outcome Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+function resolveOutcome(success) {
+    if (typeof success === "boolean") {
+        return success
+            ? { quality: "success", isPositive: true, suffix: "success", category: "success" }
+            : { quality: "failure", isPositive: false, suffix: "failure", category: "correction" };
+    }
+    switch (success) {
+        case "success":
+            return { quality: "success", isPositive: true, suffix: "success", category: "success" };
+        case "partial":
+            return { quality: "partial", isPositive: true, suffix: "partial", category: "success" };
+        case "accepted":
+            return { quality: "accepted", isPositive: true, suffix: "accepted", category: "interaction" };
+        case "misaligned":
+            return { quality: "misaligned", isPositive: false, suffix: "misaligned", category: "correction" };
+        case "failure":
+            return { quality: "failure", isPositive: false, suffix: "failure", category: "correction" };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Intent Pivot Tracking
+// ─────────────────────────────────────────────────────────────────────────────
+const MAX_PIVOTS = 100;
+/** In-memory pivot accumulator — aggregated by the journey/feedback adapter */
+const intentPivots = [];
+/** Get accumulated intent pivots (for journey reporting) */
+export function getIntentPivots() {
+    return intentPivots;
+}
+/** Reset pivot state (for test isolation) */
+export function _resetIntentPivots() {
+    intentPivots.length = 0;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Entry Point
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Emit outcome feedback for all consulted knowledge docs in the current session.
+ *
+ * Best-effort: never throws. Failures are logged but don't block the calling handler.
+ *
+ * @example
+ * // Layer 1: Deploy accepted (system signal, low weight)
+ * await emitOutcomeFeedback({
+ *   tool: "workflow", operation: "deploy", success: "accepted", layer: "system",
+ * });
+ *
+ * // Layer 2: Agent thinks it looks right
+ * await emitOutcomeFeedback({
+ *   tool: "workflow", operation: "deploy", success: "partial", layer: "agent",
+ *   intent: "route billing questions to billing team",
+ * });
+ *
+ * // Layer 3: Conversation test confirms behavior
+ * await emitOutcomeFeedback({
+ *   tool: "conversation", operation: "test", success: "success", layer: "validation",
+ *   intent: "route billing questions to billing team",
+ * });
+ *
+ * // Layer 4: End-user kept using it (highest weight)
+ * await emitOutcomeFeedback({
+ *   tool: "conversation", operation: "usage", success: true, layer: "user",
+ * });
+ *
+ * // Intent pivot (knowledge, not failure):
+ * await emitOutcomeFeedback({
+ *   tool: "workflow", operation: "deploy", success: "success", layer: "validation",
+ *   intent: {
+ *     original: "route billing questions to billing team",
+ *     final: "route billing questions and auto-generate invoice summaries",
+ *     pivotReason: "user realized they also need invoice summaries during testing",
+ *   },
+ * });
+ */
+export async function emitOutcomeFeedback(event) {
+    const docs = getConsultedDocs();
+    const outcome = resolveOutcome(event.success);
+    const layer = event.layer ?? "system";
+    const weight = LAYER_WEIGHTS[layer];
+    const eventType = `${event.tool}-${event.operation}-${outcome.suffix}`;
+    // Track intent pivots — these are knowledge signals, not failures
+    if (event.intent && typeof event.intent === "object" && event.intent.final && event.intent.final !== event.intent.original) {
+        intentPivots.push({
+            original: event.intent.original,
+            final: event.intent.final,
+            reason: event.intent.pivotReason,
+            tool: event.tool,
+            timestamp: new Date().toISOString(),
+        });
+        // Evict oldest entries to prevent unbounded growth
+        while (intentPivots.length > MAX_PIVOTS)
+            intentPivots.shift();
+        console.error(`[INTENT-PIVOT] "${event.intent.original}" → "${event.intent.final}"` +
+            (event.intent.pivotReason ? ` (${event.intent.pivotReason})` : ""));
+    }
+    if (docs.size === 0) {
+        return { docs_processed: 0, confidence_updates: 0, event_type: eventType };
+    }
+    // "accepted" = system accepted it, no intent validation → skip confidence updates.
+    // This applies at ALL layers: "accepted" means structural acceptance, not functional
+    // success. Use "partial" or "success" to indicate functional validation.
+    if (outcome.quality === "accepted") {
+        return { docs_processed: docs.size, confidence_updates: 0, event_type: eventType };
+    }
+    const defaultCategory = outcome.category;
+    // Context encodes tool, operation, quality, AND layer for evidence classification
+    const context = `${event.tool}_${event.operation}_${outcome.suffix}`;
+    let updates = 0;
+    // Scale the quality signal for lower layers: system/agent produce weaker
+    // quality data, so downgrade "success" to "interaction" (neutral) at system layer.
+    // Higher layers (validation, user) keep the original category.
+    const effectiveDefaultCategory = (layer === "system" && defaultCategory === "success")
+        ? "interaction" // System-layer positive is neutral — API acceptance isn't validation
+        : defaultCategory;
+    const assessment = event.agentAssessment;
+    const helpfulSet = new Set(assessment?.helpful ?? []);
+    const misleadingSet = new Set(assessment?.misleading ?? []);
+    for (const docId of docs) {
+        try {
+            // Agent assessment overrides the blanket signal per doc
+            let category = effectiveDefaultCategory;
+            if (helpfulSet.has(docId)) {
+                category = "success";
+            }
+            else if (misleadingSet.has(docId)) {
+                category = "correction";
+            }
+            const result = await processConfidenceFeedback(category, docId, undefined, context);
+            if (result)
+                updates++;
+        }
+        catch {
+            // Best-effort
+        }
+    }
+    // Emit gap signals for missing knowledge
+    if (assessment?.missing) {
+        for (const topic of assessment.missing) {
+            try {
+                await processConfidenceFeedback("gap", `missing:${topic}`, undefined, context);
+            }
+            catch {
+                // Best-effort
+            }
+        }
+    }
+    // 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(() => { });
+    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/session-state.js

@@ -0,0 +1,110 @@
+/**
+ * Session State — Shared tracking for knowledge search sessions.
+ *
+ * Tracks which documents were served (consultedDocs), their attribution tokens,
+ * and DE resource names. Used by:
+ * - Task 2.2:  consultedDocs for deploy outcome feedback
+ * - Task 2.9:  attribution token cache for UserEvent correlation
+ * - Task 2.10: conversion events from positive feedback
+ * - Task 2.12: auto-citation tracking + dedup for answer mode
+ */
+const ATTRIBUTION_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const MAX_CACHE_SIZE = 500;
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+/** Documents consulted in the current deploy cycle. Reset before each deploy attempt. */
+const consultedDocs = new Set();
+/** Attribution token cache: artifactId → {token, ts, deResourceName}. */
+const attributionCache = new Map();
+/** Per-session dedup for L1 auto-citation view-item events. */
+const citationDedupeSet = new Set();
+/** Deploy attempt counter for retry-aware feedback. */
+let deployAttempts = 0;
+// ─── Periodic sweep to prevent memory leak ───────────────────────────────────
+let sweepTimer;
+function startSweepTimer() {
+    if (sweepTimer)
+        return;
+    sweepTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [id, entry] of attributionCache) {
+            if (now - entry.ts > ATTRIBUTION_TTL_MS)
+                attributionCache.delete(id);
+        }
+        // Evict oldest if over max size
+        if (attributionCache.size > MAX_CACHE_SIZE) {
+            const sorted = [...attributionCache.entries()].sort((a, b) => a[1].ts - b[1].ts);
+            const toRemove = sorted.slice(0, sorted.length - MAX_CACHE_SIZE);
+            for (const [id] of toRemove)
+                attributionCache.delete(id);
+        }
+    }, SWEEP_INTERVAL_MS);
+    // Don't prevent process exit
+    if (sweepTimer && typeof sweepTimer === "object" && "unref" in sweepTimer) {
+        sweepTimer.unref();
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Record that documents were served in a search response.
+ * Call after each knowledge() search returns results.
+ */
+export function recordSearchResults(results, attributionToken) {
+    startSweepTimer();
+    const now = Date.now();
+    for (const r of results) {
+        if (!r.id)
+            continue;
+        consultedDocs.add(r.id);
+        attributionCache.set(r.id, {
+            token: attributionToken,
+            ts: now,
+            deResourceName: r.deResourceName,
+        });
+    }
+}
+/** Get the attribution token for a document (if cached and not expired). */
+export function getAttributionToken(docId) {
+    const entry = attributionCache.get(docId);
+    if (!entry)
+        return undefined;
+    if (Date.now() - entry.ts > ATTRIBUTION_TTL_MS) {
+        attributionCache.delete(docId);
+        return undefined;
+    }
+    return entry.token;
+}
+/** Get all documents consulted in the current deploy cycle. */
+export function getConsultedDocs() {
+    return consultedDocs;
+}
+/** Reset consultedDocs for a new deploy cycle. Call before each deploy attempt. */
+export function resetConsultedDocs() {
+    consultedDocs.clear();
+}
+/** Increment deploy attempts counter. Call at start of each deploy. */
+export function incrementDeployAttempts() {
+    deployAttempts++;
+}
+/** Get current deploy attempt count. */
+export function getDeployAttempts() {
+    return deployAttempts;
+}
+/** Check if a citation has already been tracked this session (for L1 dedup). */
+export function hasEmittedCitation(docId) {
+    return citationDedupeSet.has(docId);
+}
+/** Mark a citation as emitted this session. */
+export function markCitationEmitted(docId) {
+    citationDedupeSet.add(docId);
+}
+/** Reset all state (for test isolation). */
+export function _resetSessionState() {
+    consultedDocs.clear();
+    attributionCache.clear();
+    citationDedupeSet.clear();
+    deployAttempts = 0;
+    if (sweepTimer) {
+        clearInterval(sweepTimer);
+        sweepTimer = undefined;
+    }
+}