@ateam-ai/mcp 0.4.47 → 0.4.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.4.47",
+  "version": "0.4.49",
   "mcpName": "io.github.ariekogan/ateam-mcp",
   "description": "A-Team MCP Server — build, validate, and deploy multi-agent solutions from any AI environment",
   "type": "module",

package/src/mcpFailure.js

@@ -0,0 +1,48 @@
+// src/mcpFailure.js
+//
+// Failure classification for the MCP tool dispatcher (used by handleToolCall in
+// tools.js). A tool call can succeed at the TRANSPORT layer (MCP returns a
+// result) while FAILING logically — the classic case being an upstream that
+// answers HTTP 200 with "Authentication required" sitting in the body. MCP's
+// `isError` and a machine-readable `code` are exactly for that gap: they let a
+// caller (e.g. the ateam-proxy connector) ask "did this actually work?" WITHOUT
+// parsing English.
+//
+// The human sentence STAYS in the result's content[].text — the reasoning loop
+// reads it to decide what to do next — we only ADD `isError` +
+// `structuredContent.code` alongside it. Never strip the prose.
+//
+//   node --test src/mcpFailure.test.js
+
+// This is the ONE boundary where recognizing the auth phrase from text is
+// correct: we translate the upstream lie into a structured code exactly once,
+// here, so nothing downstream ever has to.
+export const AUTH_SIGNAL_RX = /\b(unauthenticated|authentication required|authentication failed|not authenticated|no api_key in session|call ateam_auth|master key required|invalid api key|expired token|401)\b/i;
+
+/**
+ * Map a failure to a machine-readable code. An explicit code (set by a handler
+ * or carried on a thrown error) always wins; otherwise recognize the auth
+ * signal at this single boundary; otherwise a generic TOOL_FAILED.
+ * @param {string|object} source  the message/result the failure came with
+ * @param {string} [explicit]     a code the handler/error already set
+ * @returns {string}
+ */
+export function deriveErrorCode(source, explicit) {
+  if (explicit && typeof explicit === "string") return explicit;
+  const s = typeof source === "string"
+    ? source
+    : (() => { try { return JSON.stringify(source || ""); } catch { return String(source); } })();
+  if (AUTH_SIGNAL_RX.test(s)) return "UNAUTHENTICATED";
+  return "TOOL_FAILED";
+}
+
+/**
+ * A top-level object result with ok:false is a logical failure. Nested *.ok
+ * (widget_health.ok / validation.valid) are their own advisory signals and do
+ * NOT flip the tool to error — only the tool's OWN primary `ok` does.
+ * @param {any} result
+ * @returns {boolean}
+ */
+export function isLogicalFailure(result) {
+  return Boolean(result) && typeof result === "object" && !Array.isArray(result) && result.ok === false;
+}

package/src/mcpFailure.test.js

@@ -0,0 +1,64 @@
+// src/mcpFailure.test.js
+//
+// Proves the dispatcher's failure-classification rule: a logically-failed tool
+// result (returned ok:false, or an upstream 200-with-auth-text) is recognized
+// structurally and mapped to a machine-readable code — so the ateam-proxy never
+// has to read English to know a call failed. Tests the REAL exported functions.
+//   node --test src/mcpFailure.test.js
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { deriveErrorCode, isLogicalFailure, AUTH_SIGNAL_RX } from "./mcpFailure.js";
+
+test("auth phrases → UNAUTHENTICATED (the upstream 200-with-auth-text lie)", () => {
+  for (const s of [
+    "Authentication required — call ateam_auth first.",
+    "No api_key in session — call ateam_auth(api_key) first.",
+    "Master key required. Call ateam_auth(master_key) first.",
+    "Authentication failed: bad key",
+    "upstream said 401 Unauthorized",
+    "invalid API key",
+  ]) {
+    assert.equal(deriveErrorCode(s), "UNAUTHENTICATED", `expected UNAUTHENTICATED for: ${s}`);
+  }
+});
+
+test("non-auth failure → TOOL_FAILED", () => {
+  assert.equal(deriveErrorCode("could not read solution definition"), "TOOL_FAILED");
+  assert.equal(deriveErrorCode("redeploy timed out"), "TOOL_FAILED");
+});
+
+test("an explicit handler/error code always wins over text sniffing", () => {
+  // Even auth-looking text must not override a code the handler already set.
+  assert.equal(deriveErrorCode("Authentication required", "RATE_LIMITED"), "RATE_LIMITED");
+  assert.equal(deriveErrorCode("boom", "MISSING_SOLUTION"), "MISSING_SOLUTION");
+});
+
+test("object sources are stringified before matching (not just plain strings)", () => {
+  assert.equal(deriveErrorCode({ ok: false, message: "Authentication required" }), "UNAUTHENTICATED");
+  assert.equal(deriveErrorCode({ ok: false, error: "disk full" }), "TOOL_FAILED");
+});
+
+test("nullish / weird sources never throw, fall back to TOOL_FAILED", () => {
+  assert.equal(deriveErrorCode(null), "TOOL_FAILED");
+  assert.equal(deriveErrorCode(undefined), "TOOL_FAILED");
+});
+
+test("top-level ok:false is a logical failure; ok:true / missing / nested are not", () => {
+  assert.equal(isLogicalFailure({ ok: false, message: "x" }), true);
+  assert.equal(isLogicalFailure({ ok: true }), false);
+  assert.equal(isLogicalFailure({}), false);
+  // Nested advisory signals must NOT flip the tool to error (patch succeeded,
+  // widget just isn't rendering / def isn't valid yet).
+  assert.equal(isLogicalFailure({ ok: true, widget_health: { ok: false } }), false);
+  assert.equal(isLogicalFailure({ ok: true, validation: { valid: false } }), false);
+  // Arrays / primitives / null are never a logical failure.
+  assert.equal(isLogicalFailure([{ ok: false }]), false);
+  assert.equal(isLogicalFailure(null), false);
+  assert.equal(isLogicalFailure("ok:false"), false);
+});
+
+test("AUTH_SIGNAL_RX is exported for reuse and is case-insensitive", () => {
+  assert.ok(AUTH_SIGNAL_RX.test("AUTHENTICATION REQUIRED"));
+  assert.ok(!AUTH_SIGNAL_RX.test("everything is fine"));
+});

package/src/tools.js

@@ -29,6 +29,7 @@ const STAMP_WHERE_TOOLS = new Set([
   "ateam_verify_surface",
 ]);
 import { renderAgentDocHeader, mergeAgentDoc, AGENT_DOC_SENTINEL } from "./agentDoc.js";
+import { deriveErrorCode, isLogicalFailure } from "./mcpFailure.js";
 
 // ─── Async deploy helper ────────────────────────────────────────────
 //
@@ -795,7 +796,8 @@ export const tools = [
       "- Add a tool: updates: { \"tools_push\": [{ name: \"conn.tool\", description: \"...\", inputs: [...], output: {...} }] }\n" +
       "- Change intent: updates: { \"intents.supported_update\": [{ id: \"i1\", description: \"new desc\" }] }\n" +
       "- CREATE a new skill: target='skill', skill_id='my-new-skill', updates: { \"problem.statement\": \"...\", \"role.persona\": \"...\" } — auto-scaffolded and added to solution topology.\n\n" +
-      "PREVIEW BEFORE WRITING: pass dry_run:true to see the diff (arrays_merged, arrays_replaced, dropped_ids, added_ids) without applying. Use this before any destructive-looking edit.",
+      "PREVIEW BEFORE WRITING: pass dry_run:true to see the diff (arrays_merged, arrays_replaced, dropped_ids, added_ids) without applying. Use this before any destructive-looking edit.\n\n" +
+      "VERDICT (skill target): the response carries a NON-BLOCKING `validation` block { skill_id, valid, ready_to_export, error_count, incomplete_sections[], unresolved_refs } — the patch always saves even if the def is now invalid, so CHECK valid: false and fix incomplete_sections before relying on it (build_and_run will refuse to deploy an invalid skill). error_count can include auto-import connector-tool artifacts, so act on incomplete_sections first.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3831,6 +3833,46 @@ const handlers = {
       } catch { /* advisory — never downgrade a successful patch on the health check */ }
     }
 
+    // Phase 5: validation verdict (skill target only). NON-BLOCKING — "silent is
+    // the bug": a patch that leaves the definition invalid used to return ok:true
+    // with NO verdict, so an agent (or a persona routing here as the "cheapest
+    // correct tool") never saw it went red, and an invalid def slipped toward
+    // Core (build_and_run refuses on errors, but the patch path reported nothing).
+    // Report the verdict keyed by skill_id; never block. error_count can be
+    // inflated by auto-imported connector tools (INVALID_TOOL_INPUTS /
+    // MISSING_TOOL_OUTPUT fire on every solution because Core resolves their
+    // contract at deploy, not the author) — so lead with the author-facing
+    // signal: which sections are still incomplete, plus any unresolved refs.
+    let validation = null;
+    if (target === "skill" && skill_id) {
+      try {
+        const vr = await get(`/deploy/solutions/${solution_id}/skills/${encodeURIComponent(skill_id)}/validation`, sid);
+        const v = vr?.validation || vr || {};
+        const incomplete_sections = Object.entries(v.sections || {})
+          .filter(([, s]) => s && s.complete === false)
+          .map(([name]) => name);
+        const unresolved = Object.entries(v.unresolved_refs || {}).filter(([, n]) => Number(n) > 0);
+        validation = {
+          skill_id,
+          valid: v.valid === true,
+          ready_to_export: v.ready_to_export === true,
+          error_count: v.error_count ?? null,
+          warning_count: v.warning_count ?? null,
+          ...(incomplete_sections.length && { incomplete_sections }),
+          ...(unresolved.length && { unresolved_refs: Object.fromEntries(unresolved) }),
+          ...(v.error_count > 0 && {
+            _note: `error_count can include auto-import connector-tool artifacts — INVALID_TOOL_INPUTS / MISSING_TOOL_OUTPUT fire on every solution because Core resolves an auto-imported tool's contract at deploy, not the author. Act on incomplete_sections${unresolved.length ? " + unresolved_refs" : ""} first.`,
+          }),
+          ...(v.valid === false && {
+            _verdict: `Skill "${skill_id}" is INVALID — the patch was still saved + redeployed (non-blocking), but build_and_run will REFUSE to deploy while errors stand. Fix the above, then re-check.`,
+          }),
+        };
+      } catch { /* advisory — a validation hiccup never downgrades a saved patch */ }
+    }
+    const validationStatus = (validation && validation.valid === false)
+      ? ` ⚠️ Skill "${skill_id}" is INVALID (${validation.error_count ?? "?"} error(s)) — see validation (non-blocking; build_and_run will refuse until fixed).`
+      : "";
+
     return {
       ok: true,
       solution_id,
@@ -3860,13 +3902,14 @@ const handlers = {
       }),
       ...(isNewSkill && { created_skill: skill_id }),
       ...(redeployResult && { redeploy: redeployResult }),
+      ...(validation && { validation }),
       ...(widget_health && { widget_health }),
       ...(test_result && { test_result }),
-      _status: redeployOk
+      _status: (redeployOk
         ? (widget_health && !widget_health.ok
             ? `✅ Patched on ${store} + redeployed. ⚠️ ${widget_health.issues?.length || 0} widget(s) not rendering — see widget_health.`
             : `✅ Patched on ${store} + redeployed.`)
-        : `⚠️ Patched on ${store} ✅ but redeploy timed out. Run: ateam_redeploy(solution_id` + (skill_id ? `, skill_id: "${skill_id}"` : '') + ')',
+        : `⚠️ Patched on ${store} ✅ but redeploy timed out. Run: ateam_redeploy(solution_id` + (skill_id ? `, skill_id: "${skill_id}"` : '') + ')') + validationStatus,
       _next: isLocal
         ? 'Local edit saved + redeployed. When the tenant connects a GitHub repo, the local state is pushed → GitHub (which then becomes master).'
         : 'Create a checkpoint before making more changes: ateam_github_promote(solution_id)',
@@ -5174,6 +5217,10 @@ function summarizeLargeResult(result, toolName) {
   return JSON.stringify(result, null, 2).slice(0, MAX_RESPONSE_CHARS);
 }
 
+// Failure classification (isError + a machine-readable code, WITHOUT parsing
+// English) lives in ./mcpFailure.js — imported at the top — so the rule is
+// unit-testable in isolation (mcpFailure.test.js).
+
 // ─── Dispatcher ─────────────────────────────────────────────────────
 
 export async function handleToolCall(name, args, sessionId) {
@@ -5217,6 +5264,7 @@ export async function handleToolCall(name, args, sessionId) {
         ].join("\n"),
       }],
       isError: true,
+      structuredContent: { ok: false, code: "UNAUTHENTICATED" },
     };
   }
 
@@ -5273,13 +5321,28 @@ export async function handleToolCall(name, args, sessionId) {
       } catch { /* non-fatal — unauthed sessions or API blips shouldn't break bootstrap */ }
     }
 
+    const text = formatResult(result, name);
+    if (isLogicalFailure(result)) {
+      // Logical failure RETURNED (not thrown) — e.g. { ok:false, message:"…
+      // Authentication required" } or an upstream 200-with-auth-text. Flag it
+      // so a caller detects it from isError/code, not by reading the prose.
+      // The sentence stays in content[].text for the reasoning loop.
+      const code = deriveErrorCode(result.message || result.error || text, result.code);
+      return {
+        content: [{ type: "text", text }],
+        isError: true,
+        structuredContent: { ok: false, code },
+      };
+    }
     return {
-      content: [{ type: "text", text: formatResult(result, name) }],
+      content: [{ type: "text", text }],
     };
   } catch (err) {
+    const code = deriveErrorCode(err.message, err.code);
     return {
       content: [{ type: "text", text: err.message }],
       isError: true,
+      structuredContent: { ok: false, code },
     };
   }
 }