@ema.co/mcp-toolkit 2026.3.23-3 → 2026.3.24

package/LICENSE-COMMERCIAL.md

@@ -0,0 +1,45 @@
+# Commercial License
+
+Copyright (c) 2026 Ema Unlimited, Inc.
+
+This software is available under a commercial license for organizations
+that wish to use, modify, or distribute it without the obligations of
+the GNU Affero General Public License (AGPL) v3.
+
+## Grant of License
+
+Subject to payment of applicable fees and compliance with the terms
+of a written commercial agreement, Ema Unlimited, Inc. grants you a
+non-exclusive, non-transferable license to:
+
+- Use the software in proprietary or closed-source environments
+- Modify the software without public disclosure
+- Deploy the software as part of a hosted or managed service
+- Integrate the software into internal or commercial systems
+
+## Restrictions
+
+Without an applicable commercial agreement, you may NOT:
+
+- Offer the software as a hosted or managed service
+- Expose the software’s network interfaces, handlers, or internal
+  port-based APIs in production
+- Create derivative works that are not released under AGPLv3
+- Circumvent licensing, feature controls, or access restrictions
+
+## Ownership
+
+All rights, title, and interest in the software remain with
+Ema Unlimited, Inc.. No rights are granted except as expressly stated.
+
+## Warranty Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
+
+## Contact
+
+For licensing inquiries, please contact:
+
+legal@ema.co or steven.poitras@ema.co

package/dist/config/generated/stage-eligibility.snapshot.js

@@ -2,14 +2,14 @@
  * AUTO-GENERATED — Do not edit manually.
  * Run: npm run generate:stage-snapshot
  *
- * Generated from 45 catalog actions.
- * 28 stages, 45 actions with eligibility.
+ * Generated from 57 catalog actions.
+ * 29 stages, 57 actions with eligibility.
  * Overrides applied: abstain_action, custom_agent, document_synthesis, entity_extraction_with_documents, fixed_response, general_hitl, json_mapper, respond_for_external_actions, search, text_categorizer
  */
 export const STAGE_ELIGIBILITY_SNAPSHOT = {
-    "catalogSize": 45,
-    "stageCount": 28,
-    "actionCount": 45,
+    "catalogSize": 57,
+    "stageCount": 29,
+    "actionCount": 57,
     "overridesApplied": [
         "abstain_action",
         "custom_agent",
@@ -32,7 +32,11 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
             "chat_categorizer",
             "conversation_to_search_query",
             "document_categorizer",
-            "text_categorizer"
+            "feedback_categorizer",
+            "make_response_public",
+            "text_categorizer",
+            "thread_categorizer",
+            "thread_summarizer"
         ],
         "refine": [
             "chat_categorizer",
@@ -56,6 +60,7 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
             "information_redacter",
             "insurance_claim_summarizer",
             "legal_expert",
+            "market_research",
             "medical_record_summarizer",
             "medical_research_assistant",
             "phishing_email_detector",
@@ -81,6 +86,7 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         ],
         "handle": [
             "call_llm",
+            "chart_creator",
             "custom_agent",
             "fixed_response",
             "generate_document",
@@ -90,11 +96,13 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         "respond": [
             "audit_evidence_verifier",
             "call_llm",
+            "chart_creator",
             "compliance_document_analyzer",
             "custom_agent",
             "cybersecurity_expert",
             "document_synthesis",
             "email_writer",
+            "feedback_categorizer",
             "financial_risk_assessor",
             "financial_statement_analyzer",
             "fixed_response",
@@ -102,17 +110,23 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
             "information_redacter",
             "insurance_claim_summarizer",
             "legal_expert",
+            "make_response_public",
+            "market_research",
             "medical_record_summarizer",
             "medical_research_assistant",
             "phishing_email_detector",
+            "qa_over_sql",
             "respond_with_sources",
             "sales_intelligence",
             "sentiment_analyzer",
             "tax_advisor",
-            "technical_support"
+            "technical_support",
+            "thread_categorizer",
+            "thread_summarizer"
         ],
         "reason": [
             "call_llm",
+            "chart_creator",
             "custom_agent",
             "fixed_response",
             "generate_document",
@@ -120,6 +134,7 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         ],
         "draft": [
             "call_llm",
+            "chart_creator",
             "custom_agent",
             "fixed_response",
             "generate_document",
@@ -128,6 +143,7 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         ],
         "compose": [
             "call_llm",
+            "chart_creator",
             "custom_agent",
             "fixed_response",
             "generate_document",
@@ -136,13 +152,19 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         ],
         "summarize": [
             "call_llm",
+            "chart_creator",
             "custom_agent",
+            "feedback_categorizer",
             "fixed_response",
             "generate_document",
-            "respond_with_sources"
+            "make_response_public",
+            "respond_with_sources",
+            "thread_categorizer",
+            "thread_summarizer"
         ],
         "resolve": [
             "call_llm",
+            "chart_creator",
             "custom_agent",
             "fixed_response",
             "generate_document",
@@ -152,6 +174,7 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         "analyze": [
             "audit_evidence_verifier",
             "call_llm",
+            "chart_creator",
             "compliance_document_analyzer",
             "custom_agent",
             "financial_risk_assessor",
@@ -163,6 +186,7 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
             "legal_expert",
             "medical_record_summarizer",
             "medical_research_assistant",
+            "qa_over_sql",
             "respond_with_sources",
             "sentiment_analyzer",
             "tax_advisor"
@@ -170,6 +194,7 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         "fallback": [
             "abstain_action",
             "call_llm",
+            "chart_creator",
             "custom_agent",
             "fixed_response",
             "generate_document",
@@ -177,6 +202,7 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         ],
         "handle-failure": [
             "call_llm",
+            "chart_creator",
             "custom_agent",
             "fixed_response",
             "generate_document",
@@ -189,10 +215,15 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
             "general_hitl"
         ],
         "convert": [
+            "combine_search_results",
+            "combine_text_with_sources",
+            "convert_to_text",
+            "custom_code_agent",
             "json_extractor",
             "json_formatter",
             "json_mapper",
-            "markdown_formatter"
+            "markdown_formatter",
+            "tags_extractor"
         ],
         "act-on-success": [
             "external_action_caller",
@@ -232,9 +263,21 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
             "rule_validation_with_documents"
         ],
         "format": [
+            "combine_search_results",
+            "combine_text_with_sources",
+            "convert_to_text",
+            "custom_code_agent",
             "json_extractor",
             "json_formatter",
-            "markdown_formatter"
+            "markdown_formatter",
+            "tags_extractor"
+        ],
+        "merge": [
+            "combine_search_results",
+            "combine_text_with_sources",
+            "convert_to_text",
+            "custom_code_agent",
+            "tags_extractor"
         ]
     },
     "byAction": {
@@ -484,6 +527,71 @@ export const STAGE_ELIGIBILITY_SNAPSHOT = {
         "markdown_formatter": [
             "convert",
             "format"
+        ],
+        "chart_creator": [
+            "analyze",
+            "compose",
+            "draft",
+            "fallback",
+            "handle",
+            "handle-failure",
+            "reason",
+            "resolve",
+            "respond",
+            "summarize"
+        ],
+        "combine_search_results": [
+            "convert",
+            "format",
+            "merge"
+        ],
+        "combine_text_with_sources": [
+            "convert",
+            "format",
+            "merge"
+        ],
+        "convert_to_text": [
+            "convert",
+            "format",
+            "merge"
+        ],
+        "custom_code_agent": [
+            "convert",
+            "format",
+            "merge"
+        ],
+        "tags_extractor": [
+            "convert",
+            "format",
+            "merge"
+        ],
+        "thread_categorizer": [
+            "classify",
+            "respond",
+            "summarize"
+        ],
+        "thread_summarizer": [
+            "classify",
+            "respond",
+            "summarize"
+        ],
+        "make_response_public": [
+            "classify",
+            "respond",
+            "summarize"
+        ],
+        "feedback_categorizer": [
+            "classify",
+            "respond",
+            "summarize"
+        ],
+        "market_research": [
+            "act",
+            "respond"
+        ],
+        "qa_over_sql": [
+            "analyze",
+            "respond"
         ]
     }
 };

package/dist/config/profile.js

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { hasCachedToken } from "../knowledge/gcp-auth.js";
+import { hasCachedToken, hasAdcCredentials } from "../knowledge/gcp-auth.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -287,10 +287,12 @@ export function getActiveProfile(dir) {
         ? new Date(envCred.gcpTokenExpiresAt).getTime() < Date.now()
         : false;
     const hasLoginGcpToken = !!envCred?.gcpToken && !gcpTokenExpired;
+    // ADC file check (primary method — auto-refreshable, no gcloud needed at runtime)
+    const hasAdc = hasAdcCredentials();
     // Check if a prior search already resolved a GCP token (any source).
     // Note: gcloud availability is checked at search time, not here (avoids blocking execSync).
     const hasResolvedAuth = hasCachedToken();
-    const searchAvailable = hasGcpToken || hasGcpSaKey || hasDeApiKey || hasLoginGcpToken || hasResolvedAuth;
+    const searchAvailable = hasGcpToken || hasAdc || hasGcpSaKey || hasDeApiKey || hasLoginGcpToken || hasResolvedAuth;
     return {
         name: config.current_profile,
         display: displayName(profile.tenant.name, profile.environment.name, config),

package/dist/config/stage-resolution.js

@@ -34,6 +34,8 @@ const CATEGORY_STAGE_MAP = {
     it_security: ["act", "respond"],
     hr: ["act", "respond"],
     analytics: ["analyze", "respond"],
+    utilities: ["convert", "format", "merge"],
+    agent_assist: ["respond", "classify", "summarize"],
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Manual Overrides — semantic constraints not derivable from category alone

package/dist/config/tool-guidance.js

@@ -238,6 +238,11 @@ export const TOOL_GUIDANCE = {
                 description: "Aggregate across ALL clients from cloud storage. Requires EMA_INTERNAL=1 and @ema.co gcloud auth.",
                 example: 'feedback(method="analyze", scope="global")',
             },
+            {
+                name: "Read local messages",
+                description: "Read scoped messages from this session's in-memory buffer. For intra-session task coordination.",
+                example: 'feedback(method="local", scope="role:compliance")',
+            },
             {
                 name: "Flush feedback",
                 description: "Send locally accumulated feedback to cloud storage. Happens automatically, but can be triggered manually.",
@@ -247,6 +252,7 @@ export const TOOL_GUIDANCE = {
         nextSteps: {
             submit: "Continue with your task. Your feedback will be reviewed to improve the toolkit.",
             list: "Review entries and use analyze for aggregated insights.",
+            local: "Read messages scoped to you. Act on tasks, approvals, or coordination messages from other agents in this session.",
             analyze: "Address actionable_items by updating guidance, resources, or patterns documentation. Global analysis (scope='global') uses BigQuery for cross-client aggregation. Pass days=7 to narrow the analysis window. Response includes _backend indicator, trends (week-over-week with direction), and version_comparison (error rates by version for regression detection).",
             flush: "Feedback has been sent to cloud storage. Use analyze(scope='global') to see aggregated insights across all clients.",
         },

package/dist/knowledge/gcp-auth.js

@@ -4,14 +4,20 @@
  * Resolution order (sync — getGcpAccessToken):
  * 1. EMA_GCP_ACCESS_TOKEN env var (explicit token)
  * 2. Cached token (from prior resolution)
- * 3. Stored OAuth credential from login flow (~/.ema-mcp/credentials.json)
- * 4. GOOGLE_APPLICATION_CREDENTIALS / EMA_GCP_SA_KEY (service account key → JWT → token)
- * 5. gcloud auth print-access-token (CLI fallback)
+ * 3. Application Default Credentials (~/.config/gcloud/application_default_credentials.json)
+ * 4. Stored OAuth credential from login flow (~/.ema-mcp/credentials.json)
+ * 5. GOOGLE_APPLICATION_CREDENTIALS / EMA_GCP_SA_KEY (service account key → JWT → token)
+ * 6. gcloud auth print-access-token (CLI fallback)
  *
  * Async variant (getGcpAccessTokenAsync) adds:
- * 6. Interactive: auto-launch Google auth if TTY available (once per session)
+ * 7. Interactive: auto-launch Google auth if TTY available (once per session)
  *
- * Service account auth (option 4) uses the standard Google OAuth2 JWT flow:
+ * ADC auth (option 3, PRIMARY) uses the OAuth2 refresh_token grant:
+ *   ADC file → refresh_token → POST oauth2.googleapis.com/token → access_token
+ * Auto-refreshes without user interaction. Set up once with:
+ *   gcloud auth application-default login
+ *
+ * Service account auth (option 5) uses the standard Google OAuth2 JWT flow:
  *   SA key → sign JWT → POST oauth2.googleapis.com/token → access_token
  * No external dependencies needed (uses Node.js built-in crypto).
  */
@@ -127,6 +133,77 @@ async function getTokenFromServiceAccount(sa) {
         return undefined;
     }
 }
+/**
+ * Load ADC from the well-known file location.
+ * Written by `gcloud auth application-default login`.
+ *
+ * Only returns `authorized_user` type credentials (with refresh_token).
+ * Service account type is already handled by loadServiceAccountKey().
+ */
+function loadAdcCredentials() {
+    const debug = !!process.env.EMA_DEBUG;
+    try {
+        // Well-known path: ~/.config/gcloud/application_default_credentials.json
+        // On Windows: %APPDATA%\gcloud\application_default_credentials.json
+        const adcPath = process.platform === "win32"
+            ? join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "gcloud", "application_default_credentials.json")
+            : join(homedir(), ".config", "gcloud", "application_default_credentials.json");
+        const raw = readFileSync(adcPath, "utf-8");
+        const creds = JSON.parse(raw);
+        if (creds.type !== "authorized_user") {
+            if (debug)
+                console.error(`[GCP-AUTH] ADC file is type "${creds.type}", not authorized_user — skipping.`);
+            return undefined;
+        }
+        if (!creds.client_id || !creds.client_secret || !creds.refresh_token) {
+            if (debug)
+                console.error("[GCP-AUTH] ADC file missing required fields (client_id, client_secret, refresh_token).");
+            return undefined;
+        }
+        if (debug)
+            console.error("[GCP-AUTH] Found ADC authorized_user credentials.");
+        return creds;
+    }
+    catch {
+        // File doesn't exist or isn't readable — that's fine
+        return undefined;
+    }
+}
+/**
+ * Exchange an ADC refresh token for a fresh access token.
+ * Uses the standard OAuth2 refresh_token grant.
+ */
+async function getTokenFromAdc(adc) {
+    const debug = !!process.env.EMA_DEBUG;
+    try {
+        const resp = await fetch("https://oauth2.googleapis.com/token", {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                client_id: adc.client_id,
+                client_secret: adc.client_secret,
+                refresh_token: adc.refresh_token,
+                grant_type: "refresh_token",
+            }).toString(),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!resp.ok) {
+            const detail = await resp.text().catch(() => "");
+            if (debug)
+                console.error(`[GCP-AUTH] ADC token refresh failed: ${resp.status} — ${detail.slice(0, 200)}`);
+            return undefined;
+        }
+        const data = (await resp.json());
+        if (debug)
+            console.error(`[GCP-AUTH] ADC token refreshed (expires in ${data.expires_in ?? "?"}s).`);
+        return data.access_token;
+    }
+    catch (err) {
+        if (debug)
+            console.error(`[GCP-AUTH] ADC token refresh error: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Main token getter
 // ─────────────────────────────────────────────────────────────────────────────
@@ -136,9 +213,10 @@ async function getTokenFromServiceAccount(sa) {
  * Resolution order:
  * 1. EMA_GCP_ACCESS_TOKEN env var — skipped if previously rejected (401/403)
  * 2. Cached token (if not expired)
- * 3. Stored OAuth credential from login flow (~/.ema-mcp/credentials.json)
- * 4. Service account key (GOOGLE_APPLICATION_CREDENTIALS or EMA_GCP_SA_KEY)
- * 5. gcloud auth print-access-token (CLI fallback)
+ * 3. ADC file (~/.config/gcloud/application_default_credentials.json) — primary
+ * 4. Stored OAuth credential from login flow (~/.ema-mcp/credentials.json)
+ * 5. Service account key (GOOGLE_APPLICATION_CREDENTIALS or EMA_GCP_SA_KEY)
+ * 6. gcloud auth print-access-token (CLI fallback)
  *
  * Returns undefined if no token source is available.
  */
@@ -157,13 +235,28 @@ export function getGcpAccessToken() {
             console.error(`[GCP-AUTH] Using cached token (expires in ${Math.round((_token.expiresAt - Date.now()) / 60_000)}m).`);
         return _token.value;
     }
-    // 3. Stored OAuth credential from login flow
+    // 3. ADC file → async refresh token exchange (PRIMARY)
+    // Can't do async in a sync function, so fire-and-forget + cache for next call
+    const adc = loadAdcCredentials();
+    if (adc) {
+        if (debug)
+            console.error("[GCP-AUTH] Found ADC credentials — initiating async token refresh.");
+        getTokenFromAdc(adc).then((token) => {
+            if (token) {
+                _token = { value: token, expiresAt: Date.now() + TOKEN_TTL_MS };
+            }
+        }).catch(() => { });
+        // If we have a cached token from a prior ADC refresh, use it
+        if (_token && _token.value)
+            return _token.value;
+    }
+    // 4. Stored OAuth credential from login flow
     const storedToken = loadStoredGcpToken();
     if (storedToken) {
         _token = { value: storedToken, expiresAt: Date.now() + TOKEN_TTL_MS };
         return storedToken;
     }
-    // 4. Service account key → async token exchange
+    // 5. Service account key → async token exchange
     // Can't do async in a sync function, so we kick off the exchange and cache for next call
     const sa = loadServiceAccountKey();
     if (sa) {
@@ -179,7 +272,7 @@ export function getGcpAccessToken() {
         if (_token && _token.value)
             return _token.value;
     }
-    // 5. gcloud CLI
+    // 6. gcloud CLI
     try {
         if (debug)
             console.error("[GCP-AUTH] Trying gcloud auth print-access-token...");
@@ -206,11 +299,11 @@ export function getGcpAccessToken() {
         }
     }
     if (debug)
-        console.error("[GCP-AUTH] All 5 resolution steps failed. No GCP token available.");
+        console.error("[GCP-AUTH] All 6 resolution steps failed. No GCP token available.");
     return undefined;
 }
 /**
- * Async version — waits for service account token exchange.
+ * Async version — waits for ADC/SA token exchange.
  * Use this when you can await (e.g., in search handlers).
  */
 export async function getGcpAccessTokenAsync() {
@@ -221,13 +314,22 @@ export async function getGcpAccessTokenAsync() {
     // 2. Cached token
     if (_token && Date.now() < _token.expiresAt)
         return _token.value;
-    // 3. Stored OAuth credential from login flow
+    // 3. ADC file → await refresh token exchange (PRIMARY)
+    const adc = loadAdcCredentials();
+    if (adc) {
+        const token = await getTokenFromAdc(adc);
+        if (token) {
+            _token = { value: token, expiresAt: Date.now() + TOKEN_TTL_MS };
+            return token;
+        }
+    }
+    // 4. Stored OAuth credential from login flow
     const storedToken = loadStoredGcpToken();
     if (storedToken) {
         _token = { value: storedToken, expiresAt: Date.now() + TOKEN_TTL_MS };
         return storedToken;
     }
-    // 4. Service account key → await token exchange
+    // 5. Service account key → await token exchange
     const sa = loadServiceAccountKey();
     if (sa) {
         const token = await getTokenFromServiceAccount(sa);
@@ -236,11 +338,11 @@ export async function getGcpAccessTokenAsync() {
             return token;
         }
     }
-    // 5. gcloud CLI (sync — handled inside getGcpAccessToken)
+    // 6. gcloud CLI (sync — handled inside getGcpAccessToken)
     const syncToken = getGcpAccessToken();
     if (syncToken)
         return syncToken;
-    // 6. Interactive: auto-launch Google auth if TTY available
+    // 7. Interactive: auto-launch Google auth if TTY available
     const refreshed = await refreshGcpToken();
     if (refreshed)
         return refreshed;
@@ -374,6 +476,10 @@ export function getLastGcpAuthError() {
 export function hasCachedToken() {
     return !!_token && Date.now() < _token.expiresAt;
 }
+/** Whether ADC file exists with authorized_user credentials (fast sync check, no network). */
+export function hasAdcCredentials() {
+    return !!loadAdcCredentials();
+}
 let _gcloudAvailable;
 /**
  * Whether `gcloud` CLI is installed (cached after first check).

package/dist/knowledge/guidance-cache.js

@@ -27,6 +27,8 @@ export class GuidanceCache {
     toolGuidanceMap = new Map();
     tips = [];
     topics = [];
+    patterns = [];
+    questions = [];
     warmedAt = null;
     constructor(searchFn, config) {
         this.searchFn = searchFn;
@@ -102,12 +104,24 @@ export class GuidanceCache {
         this.maybeRefresh();
         return this.topics;
     }
+    /** All workflow patterns. */
+    getPatterns() {
+        this.maybeRefresh();
+        return this.patterns;
+    }
+    /** All qualifying questions. */
+    getQuestions() {
+        this.maybeRefresh();
+        return this.questions;
+    }
     // ── Internals ───────────────────────────────────────────────────────────
     clear() {
         this.rules = [];
         this.toolGuidanceMap = new Map();
         this.tips = [];
         this.topics = [];
+        this.patterns = [];
+        this.questions = [];
     }
     /**
      * Index artifacts by reading structured data from structData.data.
@@ -152,6 +166,12 @@ export class GuidanceCache {
                     case "guidance-topic":
                         this.topics.push(data);
                         break;
+                    case "workflow-pattern":
+                        this.patterns.push(data);
+                        break;
+                    case "qualifying-question":
+                        this.questions.push(data);
+                        break;
                     default:
                         break;
                 }
@@ -171,6 +191,10 @@ export class GuidanceCache {
             return "contextual-tip";
         if (tags.includes("guidance-topic"))
             return "guidance-topic";
+        if (tags.includes("workflow-pattern"))
+            return "workflow-pattern";
+        if (tags.includes("qualifying-question"))
+            return "qualifying-question";
         if (name.includes("tool-guidance"))
             return "tool-guidance";
         return undefined;