@ema.co/mcp-toolkit 2026.3.24 → 2026.3.25-2

package/dist/knowledge/guidance-cache.js

@@ -16,7 +16,9 @@
 // ─────────────────────────────────────────────────────────────────────────────
 const DEFAULT_TTL_MS = 3_600_000; // 1 hour
 const SEARCH_LIMIT = 200;
-const SOURCE_FILTER = "mcp-toolkit";
+// Accept guidance from both MCP toolkit extractors and knowledge-adapters pipeline.
+// MCP owns raw TypeScript definitions; knowledge-adapters handles extraction + publishing.
+const SOURCE_FILTERS = ["mcp-toolkit", "repo-knowledge"];
 // ─────────────────────────────────────────────────────────────────────────────
 // Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -29,6 +31,8 @@ export class GuidanceCache {
     topics = [];
     patterns = [];
     questions = [];
+    invariants = [];
+    contextualGuidanceMap = new Map();
     warmedAt = null;
     constructor(searchFn, config) {
         this.searchFn = searchFn;
@@ -42,8 +46,8 @@ export class GuidanceCache {
      */
     async warm() {
         try {
-            const results = await this.searchFn(`source:${SOURCE_FILTER}`, {
-                filters: { source: [SOURCE_FILTER] },
+            const results = await this.searchFn(`source:${SOURCE_FILTERS[0]}`, {
+                filters: { source: SOURCE_FILTERS },
                 limit: SEARCH_LIMIT,
             });
             this.index(results);
@@ -114,6 +118,37 @@ export class GuidanceCache {
         this.maybeRefresh();
         return this.questions;
     }
+    /** All structural invariants (graph, branching, response, type rules). */
+    getInvariants() {
+        this.maybeRefresh();
+        return this.invariants;
+    }
+    /**
+     * Get contextual guidance for a specific key.
+     * Keys follow the pattern: "{tool}.{method}.{result_shape}"
+     * Also checks wildcards: "*.{method}.{shape}", "{tool}.*.{shape}", "*.*.{shape}"
+     */
+    getContextualGuidance(tool, method, shape) {
+        this.maybeRefresh();
+        // Try exact match first, then progressively broader wildcards
+        const candidates = [
+            `${tool}.${method}.${shape}`,
+            `${tool}.*.${shape}`,
+            `*.${method}.${shape}`,
+            `*.*.${shape}`,
+        ];
+        for (const key of candidates) {
+            const atom = this.contextualGuidanceMap.get(key);
+            if (atom)
+                return atom;
+        }
+        return undefined;
+    }
+    /** All contextual guidance atoms (for debugging/inspection). */
+    getAllContextualGuidance() {
+        this.maybeRefresh();
+        return Array.from(this.contextualGuidanceMap.values());
+    }
     // ── Internals ───────────────────────────────────────────────────────────
     clear() {
         this.rules = [];
@@ -122,6 +157,8 @@ export class GuidanceCache {
         this.topics = [];
         this.patterns = [];
         this.questions = [];
+        this.invariants = [];
+        this.contextualGuidanceMap = new Map();
     }
     /**
      * Index artifacts by reading structured data from structData.data.
@@ -172,6 +209,16 @@ export class GuidanceCache {
                     case "qualifying-question":
                         this.questions.push(data);
                         break;
+                    case "structural-invariant":
+                        this.invariants.push(data);
+                        break;
+                    case "contextual-guidance": {
+                        const atom = data;
+                        const key = atom.key
+                            ?? `${atom.tool ?? "*"}.${atom.method ?? "*"}.${atom.result_shape ?? "*"}`;
+                        this.contextualGuidanceMap.set(key, { ...atom, key });
+                        break;
+                    }
                     default:
                         break;
                 }
@@ -195,8 +242,18 @@ export class GuidanceCache {
             return "workflow-pattern";
         if (tags.includes("qualifying-question"))
             return "qualifying-question";
+        if (tags.includes("structural-invariant"))
+            return "structural-invariant";
+        if (tags.includes("structural-invariant"))
+            return "structural-invariant";
+        if (tags.includes("contextual-guidance"))
+            return "contextual-guidance";
         if (name.includes("tool-guidance"))
             return "tool-guidance";
+        if (name.startsWith("invariant-"))
+            return "structural-invariant";
+        if (name.includes("contextual-guidance"))
+            return "contextual-guidance";
         return undefined;
     }
 }

package/dist/knowledge/intelligence/staleness.js

@@ -15,6 +15,10 @@ export const FILE_TO_SOURCE = {
     "src/config/workflow-patterns.ts": ["workflow-patterns"],
     "src/config/guidance-rules.ts": ["guidance-rules"],
     "src/mcp/knowledge-guidance-topics.ts": ["guidance-topics"],
+    // Upstream dependency: workflow-engine/pkg/engine/validator.go
+    // When the Go validator changes, structural-rules.ts should be updated to match.
+    // The knowledge-adapters pipeline (mcp-toolkit adapter) re-extracts and publishes
+    // to DE, where GuidanceCache auto-refreshes within 1hr TTL.
     "src/mcp/domain/structural-rules.ts": ["structural-invariants"],
     "src/mcp/domain/validation-rules.ts": ["validation-rules"],
     "src/sdk/generated/deprecated-actions.ts": ["deprecated-actions"],

package/dist/knowledge/search-client.js

@@ -165,6 +165,46 @@ const QUERY_SIGNALS = [
         ],
     },
 ];
+// ─────────────────────────────────────────────────────────────────────────────
+// Dynamic Preamble — context-aware system instructions for :answer endpoint
+// ─────────────────────────────────────────────────────────────────────────────
+/** Base preamble applied to all answer queries. */
+const BASE_PREAMBLE = [
+    "You are answering questions about the Ema AI Employee platform — a workflow orchestration system.",
+    "When referencing actions or nodes, use their exact actionType names (e.g., chat_categorizer, respond_with_sources).",
+    "When showing fixes, include concrete workflow_def JSON snippets when available in the source documents.",
+    "Cite specific document IDs when available.",
+].join(" ");
+/** Query-pattern-specific preamble additions. */
+const PREAMBLE_SIGNALS = [
+    {
+        pattern: /\b(fix|error|fail|broken|wrong|issue|bug|debug)\b/i,
+        addition: "Focus on the Fix field from structural invariants. Show the violation, then the fix.",
+    },
+    {
+        pattern: /\b(how to|how do|pattern|example|wire|connect|build)\b/i,
+        addition: "Provide step-by-step instructions with workflow_def JSON examples where available.",
+    },
+    {
+        pattern: /\b(rule|constraint|invariant|must|require|validate)\b/i,
+        addition: "List the relevant rules with their severity (critical/warning) and enforcement status.",
+    },
+];
+/**
+ * Build a context-aware preamble for the :answer endpoint.
+ * Returns undefined if preamble should be omitted (keeps DE default).
+ */
+function buildDefaultPreamble(query) {
+    // Skip preamble for very short or exact-match queries (action name lookups)
+    if (query.length < 10 || !query.includes(" "))
+        return undefined;
+    const additions = PREAMBLE_SIGNALS
+        .filter(s => s.pattern.test(query))
+        .map(s => s.addition);
+    return additions.length > 0
+        ? `${BASE_PREAMBLE} ${additions.join(" ")}`
+        : BASE_PREAMBLE;
+}
 /**
  * Build per-query boostSpec from signal matching.
  * Returns undefined if no signals match or if the caller already filtered
@@ -265,12 +305,14 @@ function transformDeResponse(deResponse, mode) {
  * Falls back gracefully — returns results-only if answer generation fails.
  */
 async function answerDirect(query, options) {
-    const { filters, topK = 10, elevate = false } = options;
+    const { filters, topK = 10, elevate = false, preamble } = options;
     const de = getDeConfig();
     const headers = buildDeHeaders();
     if (!headers)
         return { results: [], mode: "answer" };
     const filter = buildFilterExpression(filters, elevate);
+    // Dynamic preamble: caller-provided or auto-generated from query context
+    const effectivePreamble = preamble ?? buildDefaultPreamble(query);
     const body = {
         query: { text: query },
         relatedQuestionsSpec: { enable: true },
@@ -280,6 +322,7 @@ async function answerDirect(query, options) {
             ignoreLowRelevantContent: true,
             includeCitations: true,
             modelSpec: { modelVersion: "stable" },
+            ...(effectivePreamble ? { promptSpec: { preamble: effectivePreamble } } : {}),
         },
         searchSpec: {
             searchParams: {
@@ -529,6 +572,7 @@ export async function searchDocuments(query, options = {}) {
             filters: options.filters,
             topK: options.topK,
             elevate: options.elevate,
+            preamble: options.preamble,
         });
         if (answerResult.generativeAnswer || answerResult.results.length > 0)
             return answerResult;
@@ -550,6 +594,50 @@ export async function searchDocuments(query, options = {}) {
     return result;
 }
 // ─────────────────────────────────────────────────────────────────────────────
+// Browse — list/filter documents without a search query
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Browse DE documents without a search query.
+ * Uses the :search endpoint with an empty query — same endpoint, filter-only mode.
+ * Useful for listing all documents of a type, source, or tag.
+ *
+ * @see https://docs.cloud.google.com/generative-ai-app-builder/docs/browse-generic-search
+ */
+export async function browseDocuments(options = {}) {
+    const { filters, elevate = false, pageSize = 50, orderBy } = options;
+    const de = getDeConfig();
+    const headers = buildDeHeaders();
+    if (!headers)
+        return { results: [], mode: "raw" };
+    await ensureGcpAuth();
+    const filter = buildFilterExpression(filters, elevate);
+    const body = {
+        query: "",
+        pageSize,
+        ...(filter ? { filter } : {}),
+        ...(orderBy ? { orderBy } : {}),
+        contentSearchSpec: {
+            snippetSpec: { returnSnippet: false },
+        },
+    };
+    const url = `${de.baseUrl}/${de.servingConfig}:search`;
+    try {
+        const resp = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(DE_TIMEOUT_MS),
+        });
+        if (!resp.ok)
+            return { results: [], mode: "raw" };
+        const data = await resp.json();
+        return transformDeResponse(data, "raw");
+    }
+    catch {
+        return { results: [], mode: "raw" };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // User Event Tracking
 // ─────────────────────────────────────────────────────────────────────────────
 export async function writeUserEvent(event) {

package/dist/mcp/domain/generation-schema.js

@@ -1,51 +1,227 @@
 /**
  * Generation Schema
  *
- * Transforms AGENT_CATALOG into a compact format for workflow generation.
- * This avoids the token waste of including full documentation in prompts.
+ * API-first schema generation: fetches live action definitions from the
+ * backend, enriches with catalog metadata, falls back to static catalog
+ * when the API is unavailable.
+ *
+ * This ensures agents always see the FULL set of required inputs/outputs
+ * as defined by the backend, not a hand-curated subset from documentation.
  *
  * The auto-builder sends ~70K tokens of documentation per request.
  * This schema reduces that to ~5K tokens of actionable constraints.
  */
 import { AGENT_CATALOG } from "../knowledge.js";
 import { INPUT_SOURCE_RULES } from "./validation-rules.js";
+import { STRUCTURAL_INVARIANTS } from "./structural-rules.js";
 import { LLM_ACTIONS, LLM_WIDGET_INPUTS, widgetBinding } from "../../config/widget-bindings.js";
-// ─────────────────────────────────────────────────────────────────────────────
-// Schema Generation
-// ─────────────────────────────────────────────────────────────────────────────
+import { searchDocuments } from "../../knowledge/search-client.js";
+export async function buildCompactAgents(client) {
+    // Build catalog index for enrichment
+    const catalogIndex = new Map();
+    for (const agent of AGENT_CATALOG) {
+        catalogIndex.set(agent.actionName, agent);
+    }
+    // Try API-first for full input/output definitions
+    if (client) {
+        try {
+            const apiAgents = await buildFromApi(client, catalogIndex);
+            if (Object.keys(apiAgents).length > 0) {
+                return { agents: apiAgents, source: "api" };
+            }
+        }
+        catch (e) {
+            console.error(`[generation-schema] API listActions failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // DE middle layer: search for action definitions in Discovery Engine
+    try {
+        const deAgents = await buildFromDE(catalogIndex);
+        if (deAgents && Object.keys(deAgents).length > 0) {
+            return { agents: deAgents, source: "api" };
+        }
+    }
+    catch (e) {
+        console.error(`[generation-schema] DE search failed, using static catalog: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // Final fallback: static catalog (may have incomplete inputs)
+    return { agents: buildFromCatalog(catalogIndex), source: "catalog" };
+}
+/** Synchronous version for backwards compatibility (uses catalog only). */
+export function buildCompactAgentsSync() {
+    const catalogIndex = new Map();
+    for (const agent of AGENT_CATALOG) {
+        catalogIndex.set(agent.actionName, agent);
+    }
+    return { agents: buildFromCatalog(catalogIndex), source: "catalog" };
+}
 /**
- * Build a compact agent lookup from the full catalog
+ * Build agents from live API — full input/output definitions.
+ * Enriches with catalog metadata (description, whenToUse, etc.).
  */
-export function buildCompactAgents() {
+async function buildFromApi(client, catalogIndex) {
+    const actionDTOs = await client.listActions();
     const agents = {};
-    for (const agent of AGENT_CATALOG) {
+    for (const dto of actionDTOs) {
+        const typeName = dto.typeName;
+        const name = typeName?.name?.name;
+        if (!name)
+            continue;
         const inputs = {};
-        for (const input of agent.inputs ?? []) {
-            inputs[input.name] = { type: input.type, required: input.required };
+        const outputs = {};
+        // Parse inputs from API response (FULL definition)
+        const inputsObj = dto.inputs?.inputs;
+        if (inputsObj && typeof inputsObj === "object") {
+            for (const [inputName, inputDef] of Object.entries(inputsObj)) {
+                const def = inputDef;
+                inputs[inputName] = {
+                    type: (def.type?.wellKnownType ?? "WELL_KNOWN_TYPE_ANY"),
+                    required: !def.isOptional,
+                };
+            }
+        }
+        // Parse outputs from API response
+        const outputsObj = dto.outputs?.outputs;
+        if (outputsObj && typeof outputsObj === "object") {
+            for (const [outputName, outputDef] of Object.entries(outputsObj)) {
+                const def = outputDef;
+                outputs[outputName] = (def.type?.wellKnownType ?? "WELL_KNOWN_TYPE_ANY");
+            }
+        }
+        // Inject widget inputs for LLM actions (may already be in API response)
+        if (LLM_ACTIONS.has(name)) {
+            for (const binding of LLM_WIDGET_INPUTS) {
+                if (!inputs[binding.inputName]) {
+                    inputs[binding.inputName] = {
+                        type: "WELL_KNOWN_TYPE_ANY",
+                        required: binding.required,
+                    };
+                }
+            }
         }
+        // Enrich with catalog metadata (doesn't override inputs/outputs)
+        const catalogEntry = catalogIndex.get(name);
+        agents[name] = {
+            name: catalogEntry?.displayName ?? name,
+            category: catalogEntry?.category ?? "unknown",
+            description: catalogEntry?.description,
+            whenToUse: catalogEntry?.whenToUse,
+            aliases: catalogEntry?.aliases,
+            tier: catalogEntry?.tier,
+            inputs,
+            outputs,
+            constraints: catalogEntry?.criticalRules,
+        };
+    }
+    return agents;
+}
+/**
+ * Build agents from DE search — middle layer between API and static catalog.
+ * Queries DE for entity-type action docs, matches to catalog by action name
+ * extracted from the document ID (e.g., "entity:search_v2" → "search_v2").
+ * Returns null if DE search yields no action entities.
+ */
+async function buildFromDE(catalogIndex) {
+    const response = await searchDocuments("action definitions inputs outputs workflow actions", {
+        topK: 15,
+        filters: { type: ["entity"] },
+    });
+    if (!response.results || response.results.length === 0)
+        return null;
+    const deAgents = {};
+    const deActionNames = new Set();
+    for (const result of response.results) {
+        const doc = result.document;
+        if (!doc?.id)
+            continue;
+        // Extract action name from entity ID (e.g., "entity:search_v2" → "search_v2")
+        const actionName = doc.id.startsWith("entity:") ? doc.id.slice("entity:".length) : "";
+        if (!actionName)
+            continue;
+        deActionNames.add(actionName);
+        const catalogEntry = catalogIndex.get(actionName);
+        const inputs = {};
         const outputs = {};
-        for (const output of agent.outputs ?? []) {
-            outputs[output.name] = output.type;
+        // Use catalog I/O specs (DE entities don't carry structured I/O)
+        if (catalogEntry) {
+            for (const input of catalogEntry.inputs ?? []) {
+                inputs[input.name] = { type: input.type, required: input.required };
+            }
+            for (const output of catalogEntry.outputs ?? []) {
+                outputs[output.name] = output.type;
+            }
         }
-        if (LLM_ACTIONS.has(agent.actionName)) {
+        if (LLM_ACTIONS.has(actionName)) {
             for (const binding of LLM_WIDGET_INPUTS) {
+                if (!inputs[binding.inputName]) {
+                    inputs[binding.inputName] = {
+                        type: "WELL_KNOWN_TYPE_ANY",
+                        required: binding.required,
+                    };
+                }
+            }
+        }
+        deAgents[actionName] = {
+            name: catalogEntry?.displayName ?? doc.name ?? actionName,
+            category: catalogEntry?.category ?? "unknown",
+            description: catalogEntry?.description ?? doc.description ?? doc.summary,
+            whenToUse: catalogEntry?.whenToUse,
+            aliases: catalogEntry?.aliases,
+            tier: catalogEntry?.tier,
+            inputs,
+            outputs,
+            constraints: catalogEntry?.criticalRules,
+        };
+    }
+    if (deActionNames.size === 0)
+        return null;
+    // Supplement with catalog entries not found in DE
+    for (const [actionName, catalogEntry] of catalogIndex) {
+        if (deAgents[actionName])
+            continue;
+        deAgents[actionName] = buildCatalogAgent(actionName, catalogEntry);
+    }
+    return deAgents;
+}
+/** Build a CompactAgent from a single catalog entry. */
+function buildCatalogAgent(actionName, entry) {
+    const inputs = {};
+    for (const input of entry.inputs ?? []) {
+        inputs[input.name] = { type: input.type, required: input.required };
+    }
+    const outputs = {};
+    for (const output of entry.outputs ?? []) {
+        outputs[output.name] = output.type;
+    }
+    if (LLM_ACTIONS.has(actionName)) {
+        for (const binding of LLM_WIDGET_INPUTS) {
+            if (!inputs[binding.inputName]) {
                 inputs[binding.inputName] = {
                     type: "WELL_KNOWN_TYPE_ANY",
                     required: binding.required,
                 };
             }
         }
-        agents[agent.actionName] = {
-            name: agent.displayName,
-            category: agent.category,
-            description: agent.description,
-            whenToUse: agent.whenToUse,
-            aliases: agent.aliases,
-            tier: agent.tier,
-            inputs,
-            outputs,
-            constraints: agent.criticalRules,
-        };
+    }
+    return {
+        name: entry.displayName,
+        category: entry.category,
+        description: entry.description,
+        whenToUse: entry.whenToUse,
+        aliases: entry.aliases,
+        tier: entry.tier,
+        inputs,
+        outputs,
+        constraints: entry.criticalRules,
+    };
+}
+/**
+ * Build agents from static AGENT_CATALOG (fallback when API unavailable).
+ */
+function buildFromCatalog(catalogIndex) {
+    const agents = {};
+    for (const [actionName, entry] of catalogIndex) {
+        agents[actionName] = buildCatalogAgent(actionName, entry);
     }
     return agents;
 }
@@ -118,11 +294,37 @@ export function buildConstraints() {
     };
 }
 /**
- * Generate the complete compact schema for workflow generation
+ * Generate the complete compact schema for workflow generation.
+ * API-first: fetches live action definitions when client is provided.
  */
-export function generateSchema() {
+export async function generateSchema(client, cache) {
+    const invariants = cache?.getInvariants()?.length
+        ? cache.getInvariants()
+        : STRUCTURAL_INVARIANTS;
+    const { agents, source } = await buildCompactAgents(client);
+    return {
+        agents,
+        schema_source: source,
+        typeRules: buildTypeRules(),
+        inputRules: INPUT_SOURCE_RULES.map(rule => ({
+            action: rule.actionPattern,
+            recommended: rule.recommended,
+            avoid: rule.avoid,
+            severity: rule.severity,
+        })),
+        constraints: buildConstraints(),
+        structuralInvariants: invariants.map(({ id, rule, violation, fix, severity }) => ({ id, rule, violation, fix, severity })),
+    };
+}
+/** Synchronous version (catalog-only, no API). For callers that can't await. */
+export function generateSchemaSync(cache) {
+    const invariants = cache?.getInvariants()?.length
+        ? cache.getInvariants()
+        : STRUCTURAL_INVARIANTS;
+    const { agents, source } = buildCompactAgentsSync();
     return {
-        agents: buildCompactAgents(),
+        agents,
+        schema_source: source,
         typeRules: buildTypeRules(),
         inputRules: INPUT_SOURCE_RULES.map(rule => ({
             action: rule.actionPattern,
@@ -131,14 +333,15 @@ export function generateSchema() {
             severity: rule.severity,
         })),
         constraints: buildConstraints(),
+        structuralInvariants: invariants.map(({ id, rule, violation, fix, severity }) => ({ id, rule, violation, fix, severity })),
     };
 }
 /**
  * Generate a Markdown summary suitable for LLM prompts
  * This is ~5K tokens vs ~70K for full documentation
  */
-export function generateSchemaMarkdown() {
-    const schema = generateSchema();
+export function generateSchemaMarkdown(cache) {
+    const schema = generateSchemaSync(cache);
     let md = `# Workflow Generation Schema\n\n`;
     // Agent summary table with tier and description
     md += `## Available Agents (${Object.keys(schema.agents).length})\n\n`;
@@ -195,13 +398,23 @@ export function generateSchemaMarkdown() {
     for (const c of schema.constraints.inputFormats) {
         md += `- ${c}\n`;
     }
+    // Structural self-check — critical invariants the LLM must verify before outputting
+    const criticalInvariants = schema.structuralInvariants.filter(i => i.severity === "critical");
+    md += `\n## Self-Check (VERIFY BEFORE OUTPUTTING)\n\n`;
+    md += `Before finalizing your workflow, verify each rule:\n\n`;
+    md += `| # | Rule | Violation Example | Fix |\n`;
+    md += `|---|------|-------------------|-----|\n`;
+    for (let i = 0; i < criticalInvariants.length; i++) {
+        const inv = criticalInvariants[i];
+        md += `| ${i + 1} | ${inv.rule} | ${inv.violation} | ${inv.fix} |\n`;
+    }
     return md;
 }
 /**
  * Get compact agent info for a specific action
  */
 export function getAgentSchema(actionName) {
-    const schema = generateSchema();
+    const schema = generateSchemaSync();
     return schema.agents[actionName];
 }
 /**
@@ -215,7 +428,7 @@ export function isTypeCompatible(sourceType, targetType) {
     if (sourceType === targetType)
         return true;
     // Check explicit rules
-    const schema = generateSchema();
+    const schema = generateSchemaSync();
     const rule = schema.typeRules.find(r => r.sourceType === sourceType);
     return rule?.targetTypes.includes(targetType) ?? false;
 }