@ateam-ai/mcp 0.4.41 → 0.4.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.4.41",
+  "version": "0.4.43",
   "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/tools.js

@@ -26,6 +26,7 @@ const STAMP_WHERE_TOOLS = new Set([
   "ateam_github_patch", "ateam_github_write", "ateam_github_push",
   "ateam_github_promote", "ateam_github_rollback",
   "ateam_test_skill", "ateam_test_pipeline", "ateam_test_connector", "ateam_test_notification",
+  "ateam_verify_surface",
 ]);
 import { renderAgentDocHeader, mergeAgentDoc, AGENT_DOC_SENTINEL } from "./agentDoc.js";
 
@@ -87,6 +88,63 @@ async function pollDeployJob(jobId, sid, { label = 'deploy', maxMs = 15 * 60_000
 //
 // Returns null when the solution declares no widgets (nothing to check), else
 // { ok, checked, healthy, plugins[], issues[]?, hint? }.
+// ─────────────────────────────────────────────────────────────────────────────
+// Authored-source representation marker
+//
+// A skill/solution definition read from GitHub is NOT the runtime. It is a
+// mirror that drifts: on solution 'ada' (2026-08-04) the `dev` copy declared 29
+// tools while production was running 66, because deploy-time connector imports
+// are regenerated on every deploy and only mirrored to `main`. An agent that
+// answers "what tools does this skill have?" from a repo read gets a wrong
+// answer today, and would get an emptier one once generated data leaves the
+// committed file.
+//
+// So every read of a definition path carries an ADDITIVE `_ateam_representation`
+// telling the caller what it is holding and which tool returns the live view.
+// Additive on purpose — wrapping or reshaping the existing response would break
+// callers that expect the raw payload.
+//
+// `kind` reports what the file ACTUALLY is right now, not what we intend it to
+// become: files without `source_schema_version >= 2` still carry generated data,
+// so calling them "authored_source" today would be a lie.
+// See Docs/WIP/SKILL_JSON_SPLIT_PLAN_2026-08-04.md (Phase C).
+// ─────────────────────────────────────────────────────────────────────────────
+const _SKILL_JSON_RE = /^skills\/([^/]+)\/skill\.json$/;
+
+function _representationFor(filePath, content, solution_id) {
+  const p = String(filePath || "");
+  const skillMatch = p.match(_SKILL_JSON_RE);
+  if (p !== "solution.json" && !skillMatch) return null;
+
+  let schemaVersion = null;
+  try {
+    const parsed = typeof content === "string" ? JSON.parse(content) : content;
+    schemaVersion = parsed?.source_schema_version ?? null;
+  } catch { /* not JSON, or truncated — fall through to the v1 wording */ }
+
+  const authoredOnly = typeof schemaVersion === "number" && schemaVersion >= 2;
+
+  return {
+    kind: authoredOnly ? "authored_source" : "git_mirror_v1",
+    is_runtime_state: false,
+    runtime_state_may_differ: true,
+    may_include_generated_fields: !authoredOnly,
+    ...(authoredOnly
+      ? { generated_fields_omitted: ["auto_imported_tools", "deployment_timestamps"] }
+      : { contains_generated_fields: ["auto_imported_tools", "deployment_timestamps"] }),
+    warning: authoredOnly
+      ? "Authored source only. Connector-imported tools are NOT in this file — they are regenerated at deploy time. Do not answer capability questions from it."
+      : "This is a git mirror, not runtime state. Its tools[] and timestamps are a snapshot from the last write to this branch and may not match what is deployed. Do not answer capability questions from it.",
+    live_state_tool: {
+      name: "ateam_get_solution",
+      arguments: {
+        solution_id,
+        ...(skillMatch ? { skill_id: skillMatch[1], section: "tools" } : {}),
+      },
+    },
+  };
+}
+
 // Compress a skill/solution definition to a small, non-truncating summary for
 // tool results — enough to confirm the shape without the 10s-of-KB full doc.
 function _summarizeDef(def) {
@@ -1610,7 +1668,11 @@ export const tools = [
     core: true,
     description:
       "Read any file from a solution's GitHub repo. Returns the file content. Use this to read connector source code, skill definitions, or any versioned file. " +
-      "Default reads from `main` (deployed/prod state). Pass `ref: 'dev'` to read in-progress work.",
+      "Default reads from `main` (deployed/prod state). Pass `ref: 'dev'` to read in-progress work.\n\n" +
+      "⚠️ NOT RUNTIME STATE. For `solution.json` and `skills/<id>/skill.json` this returns a git MIRROR, not what is deployed. " +
+      "Connector-imported tools are regenerated at deploy time, so a repo copy's `tools[]` can differ from production (on one solution `dev` showed 29 tools while production ran 66). " +
+      "Reads of those paths carry an `_ateam_representation` field saying what you are holding. " +
+      "To answer \"what can this skill actually do?\", call ateam_get_solution(solution_id, skill_id, section:'tools') — never this tool.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1764,7 +1826,9 @@ export const tools = [
       "Use this when you want to:\n" +
       "  • Review changes before promoting to prod\n" +
       "  • See if dev is ahead of main at all (returns ahead_by: 0 if nothing to promote)\n" +
-      "  • Inspect arbitrary branch/tag/commit comparisons (override base/head)",
+      "  • **Diagnose a failed promote** — check `behind_by` and `status`. `status: 'diverged'` (behind_by > 0) means main holds commits dev never received, which is what makes ateam_github_promote return 409 Merge conflict. ALWAYS call this after a promote failure, before reporting anything to the user.\n" +
+      "  • Inspect arbitrary branch/tag/commit comparisons (override base/head)\n\n" +
+      "Note: `files[]` lists what DIFFERS, not what conflicts. For solution.json and skills/*/skill.json the difference is often deploy-generated data (regenerated connector tools, timestamps) rather than authored change — see ateam_github_read's `_ateam_representation`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1872,6 +1936,35 @@ export const tools = [
   // INFRASTRUCTURE — redeploy, master key bulk operations
   // ═══════════════════════════════════════════════════════════════════
 
+  {
+    name: "ateam_verify_surface",
+    core: true,
+    description:
+      "PROVE a connector ui_plugin actually renders WITH DATA — the required evidence that a user-visible " +
+      "UI fix is done. A plugin fetches its data over postMessage from its parent window, so opening its " +
+      "iframe alone shows the empty state and 'confirms' the very bug you're checking. This opens the plugin " +
+      "in the REAL host surface in headless Chromium, records every MCP tool call it makes, and returns " +
+      "{ ok, verdict, visible_text, calls, failures }. It distinguishes 'invented tool name' / 'right tool, " +
+      "no data' / 'plugin never asked'. FAIL-CLOSED: a browser-mcp outage returns ok:false verdict:'inconclusive' " +
+      "(never a soft pass). Run AFTER a UI/data fix; quote visible_text in your report. Requires authentication.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: { type: "string", description: "The solution id." },
+        plugin_id: {
+          type: "string",
+          description: "The ui_plugin id to probe, e.g. 'mcp:accounting-mcp:spending-dashboard'.",
+        },
+        expect: {
+          type: "object",
+          description: "Optional assertion: { tools: ['memory.get', ...] } — each MUST be called by the plugin, else ok:false.",
+          properties: { tools: { type: "array", items: { type: "string" } } },
+        },
+        actor_id: { type: "string", description: "Optional actor to render as; defaults to the solution's context actor." },
+      },
+      required: ["solution_id", "plugin_id"],
+    },
+  },
   {
     name: "ateam_redeploy",
     core: true,
@@ -1989,6 +2082,7 @@ const TENANT_TOOLS = new Set([
   "ateam_test_skill",
   "ateam_test_notification",
   "ateam_test_pipeline",
+  "ateam_verify_surface",
   "ateam_test_voice",
   "ateam_test_status",
   "ateam_test_abort",
@@ -2525,7 +2619,7 @@ const handlers = {
         { step: 2, action: "Build & Run", description: "Define your solution + skills + connector code, then validate, deploy, and health-check in one call. Include mcp_store with connector source code on the first deploy.", tools: ["ateam_build_and_run"] },
         { step: 3, action: "Version", description: "Every deploy auto-pushes to main on GitHub. The repo (tenant--solution-id) is the source of truth for connector code.", tools: ["ateam_github_status", "ateam_github_log"] },
         { step: 4, action: "Iterate", description: "Edit connector code ONE FILE AT A TIME via ateam_github_patch, then redeploy with ateam_build_and_run (auto-pulls from GitHub). NEVER re-pass all connector code inline after first deploy. For skill definitions, use ateam_patch.", tools: ["ateam_github_patch", "ateam_build_and_run", "ateam_patch"] },
-        { step: 5, action: "Test & Debug", description: "Chat with the solution via ateam_conversation (auto-routes; multi-turn via actor_id). It is ASYNC — see conversation_flow below: kick off → get chain_id → poll ateam_chain_status until chain_done → read the reply. Use ateam_test_pipeline for intent debugging, ateam_test_voice for voice. Diagnose with logs and metrics.", tools: ["ateam_conversation", "ateam_chain_status", "ateam_get_chain", "ateam_test_pipeline", "ateam_test_skill", "ateam_test_voice", "ateam_get_execution_logs", "ateam_get_metrics"] },
+        { step: 5, action: "Test & Debug", description: "Chat with the solution via ateam_conversation (auto-routes; multi-turn via actor_id). It is ASYNC — see conversation_flow below: kick off → get chain_id → poll ateam_chain_status until chain_done → read the reply. Use ateam_test_pipeline for intent debugging, ateam_test_voice for voice. For a UI plugin, ateam_verify_surface PROVES it renders with data (required evidence for a user-visible fix). Diagnose with logs and metrics.", tools: ["ateam_conversation", "ateam_chain_status", "ateam_get_chain", "ateam_test_pipeline", "ateam_test_skill", "ateam_test_voice", "ateam_verify_surface", "ateam_get_execution_logs", "ateam_get_metrics"] },
         { step: 6, action: "Checkpoint", description: "When solution is in a good state, create a checkpoint (safe point). You can rollback to any checkpoint if something breaks.", tools: ["ateam_github_promote", "ateam_github_list_versions"] },
       ],
     },
@@ -3535,7 +3629,17 @@ const handlers = {
         // output cap and truncates the rest of the result. Return a compact
         // summary by default; pass include_definition:true for the whole thing.
         ...(include_definition
-          ? { after_state: patched }
+          ? {
+              after_state: patched,
+              // The base of this after-state came from a git read, so it inherits
+              // that copy's staleness — notably regenerated connector tools. Say so
+              // rather than letting an agent treat it as runtime truth.
+              _ateam_representation: _representationFor(
+                target === "skill" && skill_id ? `skills/${skill_id}/skill.json` : "solution.json",
+                patched,
+                solution_id,
+              ),
+            }
           : { after_state_summary: _summarizeDef(patched) }),
         would_write,
         would_write_bytes: JSON.stringify(patched, null, 2).length,
@@ -3878,6 +3982,20 @@ const handlers = {
     };
   },
 
+  ateam_verify_surface: async ({ solution_id, plugin_id, expect, actor_id }, sid) => {
+    if (!solution_id) return { ok: false, error: "solution_id required" };
+    if (!plugin_id) return { ok: false, error: "plugin_id required" };
+    const body = {};
+    if (expect) body.expect = expect;
+    if (actor_id) body.actor_id = actor_id;
+    // Forwards to the skill-validator, which runs Core's ui.surfaceProbe via /mcp.
+    // 60s: navigate + settle + warm-retry inside Core, plus the hop.
+    return await post(
+      `/deploy/solutions/${solution_id}/plugins/${encodeURIComponent(plugin_id)}/verify-surface`,
+      body, sid, { timeoutMs: 60000 }
+    );
+  },
+
   ateam_test_skill: async ({ solution_id, skill_id, message, wait, wait_for, chain_timeout_ms, actor_id }, sid) => {
     // Resolve wait mode. Priority: wait_for (new explicit form) > wait (legacy).
     // wait:false  → "never"   (return job_id, no polling)
@@ -4437,7 +4555,12 @@ const handlers = {
   ateam_github_read: async ({ solution_id, path: filePath, ref }, sid) => {
     const qs = new URLSearchParams({ path: filePath });
     if (ref) qs.set('branch', ref);
-    return get(`/deploy/solutions/${solution_id}/github/read?${qs.toString()}`, sid);
+    const result = await get(`/deploy/solutions/${solution_id}/github/read?${qs.toString()}`, sid);
+    // Additive only — never reshape `result`, callers depend on the raw payload.
+    const rep = _representationFor(filePath, result?.content, solution_id);
+    return rep && result && typeof result === "object"
+      ? { ...result, _ateam_representation: rep }
+      : result;
   },
 
   ateam_github_patch: async ({ solution_id, path: filePath, content, search, replace, message, ref }, sid) =>