@qa-gentic/stlc-agents 1.0.15 → 1.0.17

package/src/cli/cmd-cost.js

@@ -0,0 +1,253 @@
+/**
+ * cmd-cost.js — `qa-stlc cost`
+ *
+ * Read session cost logs from ~/.qa-stlc/cost-*.jsonl and print a report.
+ * Also handles --set-model to persist the coding agent model preference.
+ *
+ * Usage:
+ *   qa-stlc cost                          # last session
+ *   qa-stlc cost --all                    # all sessions
+ *   qa-stlc cost --session <id>           # specific session
+ *   qa-stlc cost --json                   # raw JSON output
+ *   qa-stlc cost --set-model <model-id>   # save model for Cursor/Windsurf users
+ *
+ * Model detection order (mirrors cost_tracker.py):
+ *   STLC_CODING_AGENT_MODEL env var
+ *   → ANTHROPIC_MODEL env var  (Claude Code sets this automatically)
+ *   → GITHUB_COPILOT_MODEL env var
+ *   → ~/.qa-stlc/agent-model  (saved by --set-model)
+ *   → "claude-sonnet-4-6"  (default)
+ */
+
+"use strict";
+
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+const LOG_DIR   = path.join(os.homedir(), ".qa-stlc");
+const PREF_FILE = path.join(LOG_DIR, "agent-model");
+
+const C = {
+  reset:  "\x1b[0m", bold:   "\x1b[1m",
+  dim:    "\x1b[2m", cyan:   "\x1b[36m",
+  green:  "\x1b[32m", yellow: "\x1b[33m",
+};
+const b   = (s) => `${C.bold}${s}${C.reset}`;
+const dim = (s) => `${C.dim}${s}${C.reset}`;
+const grn = (s) => `${C.green}${s}${C.reset}`;
+const cyn = (s) => `${C.cyan}${s}${C.reset}`;
+
+function fmtTok(n) { return n >= 1000 ? `${(n/1000).toFixed(1)}K` : String(n); }
+function fmtUsd(n) { return `$${n.toFixed(6)}`; }
+function fmtMs(n)  { return `${n}ms`; }
+
+// ── Model preference helpers ───────────────────────────────────────────────
+
+const KNOWN_MODELS = {
+  // Anthropic
+  "claude-sonnet-4-6":         "$3/$15 per MTok",
+  "claude-opus-4-6":           "$5/$25 per MTok",
+  "claude-opus-4-7":           "$5/$25 per MTok",
+  "claude-haiku-4-5-20251001": "$1/$5 per MTok",
+  "claude-sonnet-4-20250514":  "$3/$15 per MTok",
+  // OpenAI / Copilot
+  "gpt-4o":                    "$2.50/$10 per MTok",
+  "gpt-4o-mini":               "$0.15/$0.60 per MTok",
+};
+
+function saveModelPref(modelId) {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  fs.writeFileSync(PREF_FILE, modelId.trim(), "utf8");
+}
+
+function readModelPref() {
+  try {
+    if (fs.existsSync(PREF_FILE)) return fs.readFileSync(PREF_FILE, "utf8").trim();
+  } catch (_) {}
+  return null;
+}
+
+function printModelHelp() {
+  console.log(`\n  ${b("Coding agent model for cost tracking")}\n`);
+  console.log(`  ${dim("Model is detected automatically in this order:")}`);
+  console.log(`  1. STLC_CODING_AGENT_MODEL  env var  ${dim("(explicit override, always wins)")}`);
+  console.log(`  2. ANTHROPIC_MODEL          env var  ${dim("(set automatically by Claude Code ✓ zero config)")}`);
+  console.log(`  3. GITHUB_COPILOT_MODEL     env var  ${dim("(set by Copilot if configured)")}`);
+  console.log(`  4. ~/.qa-stlc/agent-model   file     ${dim("(saved by qa-stlc cost --set-model)")}`);
+  console.log(`  5. claude-sonnet-4-6               ${dim("(default fallback)")}\n`);
+
+  const saved = readModelPref();
+  if (saved) {
+    console.log(`  ${grn("✓")}  Currently saved: ${b(saved)}  ${dim("(~/.qa-stlc/agent-model)")}\n`);
+  }
+
+  console.log(`  ${b("Known models:")}`);
+  for (const [id, rate] of Object.entries(KNOWN_MODELS)) {
+    console.log(`    ${id.padEnd(36)} ${dim(rate)}`);
+  }
+
+  console.log(`\n  ${b("To set for Cursor / Windsurf / any agent:")}`);
+  console.log(`  ${cyn("Option A — save once (recommended):")}`);
+  console.log(`    qa-stlc cost --set-model claude-opus-4-6\n`);
+  console.log(`  ${cyn("Option B — shell profile (applies to all projects):")}`);
+  console.log(`    echo 'export STLC_CODING_AGENT_MODEL=claude-opus-4-6' >> ~/.zshrc\n`);
+  console.log(`  ${cyn("Option C — .mcp.json env block (project-level):")}`);
+  console.log(`    "qa-gherkin-generator": {`);
+  console.log(`      "command": "/path/to/qa-gherkin-generator",`);
+  console.log(`      "env": { "STLC_CODING_AGENT_MODEL": "claude-opus-4-6" }`);
+  console.log(`    }\n`);
+  console.log(`  ${cyn("Option D — .env file in project root:")}`);
+  console.log(`    STLC_CODING_AGENT_MODEL=claude-opus-4-6\n`);
+  console.log(`  ${dim("Claude Code users: no action needed.")}`);
+  console.log(`  ${dim("ANTHROPIC_MODEL is passed through automatically via qa-stlc mcp-config.")}\n`);
+}
+
+// ── Log reading ────────────────────────────────────────────────────────────
+
+function readLogs() {
+  if (!fs.existsSync(LOG_DIR)) return [];
+  return fs.readdirSync(LOG_DIR)
+    .filter((f) => f.startsWith("cost-") && f.endsWith(".jsonl"))
+    .sort()
+    .map((f) => {
+      const file = path.join(LOG_DIR, f);
+      const records = fs.readFileSync(file, "utf8")
+        .split("\n").filter(Boolean).map((l) => JSON.parse(l));
+      return {
+        file,
+        sessionId: f.replace(/^cost-/, "").replace(/\.jsonl$/, ""),
+        records,
+      };
+    });
+}
+
+// ── Printing ───────────────────────────────────────────────────────────────
+
+function printSession(sess) {
+  const { sessionId, records } = sess;
+  if (!records.length) return;
+
+  const byServer = {};
+  let totalCost = 0, totalTokens = 0;
+  for (const r of records) {
+    const k = r.server || "unknown";
+    if (!byServer[k]) byServer[k] = { calls: 0, tokens: 0, cost: 0 };
+    byServer[k].calls++;
+    byServer[k].tokens += r.estimated_tokens || 0;
+    byServer[k].cost   += r.cost_usd || 0;
+    totalCost   += r.cost_usd || 0;
+    totalTokens += r.estimated_tokens || 0;
+  }
+
+  const model  = records[0]?.model || "unknown";
+  const source = records[0]?.model_source || "";
+  const method = records.some((r) => r.token_method === "estimated")
+    ? "estimated (payload chars÷4)" : "exact";
+  const ts    = records[0]?.timestamp?.slice(0, 19).replace("T", " ") || "";
+  const tsEnd = records[records.length - 1]?.timestamp?.slice(0, 19).replace("T", " ") || "";
+
+  console.log(`\n${"═".repeat(68)}`);
+  console.log(b(`  stlc-agents · Cost Report  ·  ${sessionId}`));
+  console.log(`${"═".repeat(68)}`);
+  console.log(dim(`  ${ts} → ${tsEnd}`));
+  console.log(dim(`  Model: ${model}  (detected via: ${source})`));
+  console.log(dim(`  Token method: ${method}`));
+
+  // Per-server
+  console.log(`\n  ${"Server".padEnd(30)} ${"Calls".padStart(6)} ${"~Tokens".padStart(10)} ${"Cost (USD)".padStart(14)}`);
+  console.log(`  ${"─".repeat(60)}`);
+  for (const [svr, d] of Object.entries(byServer)) {
+    console.log(
+      `  ${cyn(svr.padEnd(30))} ${String(d.calls).padStart(6)} ` +
+      `${fmtTok(d.tokens).padStart(10)} ${grn(fmtUsd(d.cost).padStart(14))}`
+    );
+  }
+
+  // Per-step
+  console.log(`\n  ${"Step detail"}`);
+  console.log(`  ${"─".repeat(68)}`);
+  for (const r of records) {
+    console.log(
+      `  ${(r.server || "?").padEnd(26)} ${(r.tool || "?").padEnd(36)} ` +
+      `${fmtTok(r.estimated_tokens || 0).padStart(6)}  ` +
+      `${grn(fmtUsd(r.cost_usd || 0))}  ${fmtMs(r.latency_ms || 0)}  ` +
+      dim(`[${r.token_method || "?"}]`)
+    );
+  }
+
+  // Totals
+  console.log(`\n  ${"─".repeat(68)}`);
+  console.log(`  ${"Total tokens".padEnd(40)} ${fmtTok(totalTokens).padStart(10)}`);
+  console.log(`  ${b("Total cost".padEnd(40))} ${grn(fmtUsd(totalCost))}`);
+  console.log(dim(`  Log: ${sess.file}`));
+  console.log(`${"═".repeat(68)}\n`);
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+module.exports = async function cost(opts) {
+
+  // --set-model: save model preference for Cursor/Windsurf users
+  if (opts.setModel) {
+    const modelId = opts.setModel.trim();
+    saveModelPref(modelId);
+    const rate = KNOWN_MODELS[modelId];
+    console.log(`\n  ${grn("✓")}  Model saved: ${b(modelId)}`);
+    if (rate) console.log(`     Pricing: ${dim(rate)}`);
+    else      console.log(`     ${dim("(unknown model — pricing may show $0.000000, add to pricing.py)")}`);
+    console.log(`     Written to: ${dim(PREF_FILE)}`);
+    console.log(`\n  This preference is used by all stlc-agents servers in all projects.`);
+    console.log(`  Override per-project via STLC_CODING_AGENT_MODEL in .env or .mcp.json.\n`);
+    return;
+  }
+
+  // --model-help: explain how model detection works
+  if (opts.modelHelp) {
+    printModelHelp();
+    return;
+  }
+
+  const sessions = readLogs();
+
+  if (!sessions.length) {
+    console.log(`\n  No cost logs found in ${LOG_DIR}`);
+    console.log(`  Run any qa-stlc MCP tool call to start tracking.\n`);
+    return;
+  }
+
+  if (opts.json) {
+    const all = opts.all ? sessions : [sessions[sessions.length - 1]];
+    console.log(JSON.stringify(all, null, 2));
+    return;
+  }
+
+  if (opts.session) {
+    const found = sessions.find((s) => s.sessionId === opts.session);
+    if (!found) {
+      console.log(`\n  Session not found: ${opts.session}`);
+      console.log(`  Available: ${sessions.map((s) => s.sessionId).join(", ")}\n`);
+      return;
+    }
+    printSession(found);
+    return;
+  }
+
+  if (opts.all) {
+    for (const s of sessions) printSession(s);
+    const allRecords  = sessions.flatMap((s) => s.records);
+    const grandTotal  = allRecords.reduce((a, r) => a + (r.cost_usd || 0), 0);
+    const grandTokens = allRecords.reduce((a, r) => a + (r.estimated_tokens || 0), 0);
+    console.log(`${"═".repeat(68)}`);
+    console.log(b(`  All sessions — grand total`));
+    console.log(`${"═".repeat(68)}`);
+    console.log(`  Sessions    : ${sessions.length}`);
+    console.log(`  Total tokens: ${fmtTok(grandTokens)}`);
+    console.log(b(`  TOTAL COST  : ${grn(fmtUsd(grandTotal))}`));
+    console.log(`${"═".repeat(68)}\n`);
+    return;
+  }
+
+  // Default: last session
+  printSession(sessions[sessions.length - 1]);
+};

package/src/cli/cmd-mcp-config.js

@@ -1,12 +1,40 @@
 /**
- * cmd-mcp-config.js — `qa-stlc mcp-config`
+ * cmd-mcp-config.js — `qa-stlc mcp-config`  (updated with cost tracking env injection)
  *
- * Generates .mcp.json (Claude Code) or .vscode/mcp.json (GitHub Copilot / VS Code).
+ * Change from original: both buildClaudeConfig() and buildVscodeConfig() now
+ * inject STLC cost tracking env vars into every MCP server entry.
+ *
+ * What gets injected and why:
+ *
+ *   STLC_COST_TRACKING       "true" — enables cost tracking (opt-out via "false")
+ *
+ *   ANTHROPIC_MODEL          "${env:ANTHROPIC_MODEL}" — Claude Code sets this
+ *                            automatically on the process that launches Claude.
+ *                            Passing it through to the MCP subprocess lets the
+ *                            cost tracker auto-detect the model without any
+ *                            manual configuration.
+ *
+ *   GITHUB_COPILOT_MODEL     "${env:GITHUB_COPILOT_MODEL}" — VS Code / Copilot
+ *                            may set this; passed through for the same reason.
+ *
+ *   STLC_CODING_AGENT_MODEL  "${env:STLC_CODING_AGENT_MODEL}" — explicit user
+ *                            override. Empty by default; set in shell profile
+ *                            or .env to hard-pin the model regardless of agent.
+ *
+ * The detection order inside cost_tracker.py is:
+ *   STLC_CODING_AGENT_MODEL → ANTHROPIC_MODEL → CLAUDE_MODEL →
+ *   GITHUB_COPILOT_MODEL → ~/.qa-stlc/agent-model → "claude-sonnet-4-6"
+ *
+ * RESULT: zero configuration for Claude Code users — the model is detected
+ * automatically. Copilot / Cursor / Windsurf users set STLC_CODING_AGENT_MODEL
+ * once in their shell profile or run `qa-stlc cost --set-model <model>`.
  */
+
 "use strict";
 
-const path     = require("path");
-const fs       = require("fs");
+const path        = require("path");
+const fs          = require("fs");
+const os          = require("os");
 const { spawnSync } = require("child_process");
 
 const C = {
@@ -15,45 +43,54 @@ const C = {
   yellow: "\x1b[33m", red: "\x1b[31m", dim: "\x1b[2m",
 };
 const ok   = (m) => console.log(`${C.green}✓${C.reset}  ${m}`);
-const info = (m) => console.log(`${C.cyan}→${C.reset}  ${m}`);
 const warn = (m) => console.log(`${C.yellow}⚠${C.reset}  ${m}`);
 
-const os   = require("os");
-const fs_  = fs;  // alias — fs already required above
-
-const PREF_FILE_MCP = require("path").join(os.homedir(), ".qa-stlc", "integration");
+const PREF_FILE_MCP = path.join(os.homedir(), ".qa-stlc", "integration");
 
 function readIntegrationPref() {
   try {
-    if (fs_.existsSync(PREF_FILE_MCP))
-      return fs_.readFileSync(PREF_FILE_MCP, "utf8").trim();
+    if (fs.existsSync(PREF_FILE_MCP))
+      return fs.readFileSync(PREF_FILE_MCP, "utf8").trim();
   } catch (_) {}
   return "ado";
 }
 
-const CWD = process.cwd();
+const CWD    = process.cwd();
 const IS_WIN = process.platform === "win32";
-const EXT = IS_WIN ? ".exe" : "";
+const EXT    = IS_WIN ? ".exe" : "";
 
-const AGENT_NAMES = [
+const AGENT_NAMES    = [
   "qa-test-case-manager",
   "qa-gherkin-generator",
   "qa-playwright-generator",
   "qa-helix-writer",
 ];
-
-// Jira agent — added separately because it needs env var injection
 const JIRA_AGENT_NAME = "qa-jira-manager";
+
+// ── Cost tracking env vars injected into every server entry ───────────────
+//
+// These are passed as env block items in both .mcp.json and .vscode/mcp.json.
+// The "${env:X}" syntax is evaluated by Claude Code / VS Code at server start,
+// substituting the actual value from the coding agent's own environment.
+//
+// ANTHROPIC_MODEL is the key one: Claude Code sets it automatically, so
+// Claude Code users get correct pricing with zero manual configuration.
+const COST_ENV = {
+  // Carry the coding agent's model ID into the MCP subprocess
+  "ANTHROPIC_MODEL":          "${env:ANTHROPIC_MODEL}",
+  "GITHUB_COPILOT_MODEL":     "${env:GITHUB_COPILOT_MODEL}",
+  // Explicit override — user sets this in shell profile if auto-detect is wrong
+  "STLC_CODING_AGENT_MODEL":  "${env:STLC_CODING_AGENT_MODEL}",
+  // Opt-out flag — user sets STLC_COST_TRACKING=false in their shell to silence output
+  "STLC_COST_TRACKING":       "${env:STLC_COST_TRACKING}",
+};
+
 const JIRA_ENV_VARS = {
   JIRA_CLIENT_ID:     "${env:JIRA_CLIENT_ID}",
   JIRA_CLIENT_SECRET: "${env:JIRA_CLIENT_SECRET}",
   JIRA_CLOUD_ID:      "${env:JIRA_CLOUD_ID}",
 };
 
-/**
- * Locate the binary for an agent.
- * Priority: .venv → --python dir → system PATH → python sys.executable dir → macOS framework dirs
- */
 function findBinary(name, pythonBin) {
   // 1. .venv in cwd
   const venvBin = IS_WIN
@@ -67,108 +104,132 @@ function findBinary(name, pythonBin) {
     if (fs.existsSync(candidate)) return candidate;
   }
 
-  // 3. system PATH via which/where
+  // 3. system PATH
   const which = spawnSync(IS_WIN ? "where" : "which", [name], { encoding: "utf8" });
-  if (which.status === 0 && which.stdout.trim()) return which.stdout.trim().split("\n")[0].trim();
+  if (which.status === 0 && which.stdout.trim())
+    return which.stdout.trim().split("\n")[0].trim();
 
-  // 4. ask Python where its own bin dir is (catches framework installs not on PATH)
+  // 4. Python's own bin dir (framework installs not on PATH)
   for (const py of ["python3", "python"]) {
-    const r = spawnSync(py, ["-c", "import sys, os; print(os.path.dirname(sys.executable))"], { encoding: "utf8" });
+    const r = spawnSync(py, ["-c", "import sys,os;print(os.path.dirname(sys.executable))"], { encoding: "utf8" });
     if (r.status === 0 && r.stdout.trim()) {
       const candidate = path.join(r.stdout.trim(), name + EXT);
       if (fs.existsSync(candidate)) return candidate;
     }
   }
 
-  // 5. macOS Python.org framework fallback
+  // 5. macOS framework fallback
   if (!IS_WIN) {
-    const frameworkDirs = [
-      "/Library/Frameworks/Python.framework/Versions/3.13/bin",
-      "/Library/Frameworks/Python.framework/Versions/3.12/bin",
-      "/Library/Frameworks/Python.framework/Versions/3.11/bin",
-      "/Library/Frameworks/Python.framework/Versions/3.10/bin",
-    ];
-    for (const dir of frameworkDirs) {
-      const candidate = path.join(dir, name);
+    for (const v of ["3.13", "3.12", "3.11", "3.10"]) {
+      const candidate = `/Library/Frameworks/Python.framework/Versions/${v}/bin/${name}`;
       if (fs.existsSync(candidate)) return candidate;
     }
   }
-
   return null;
 }
 
+// ── Claude Code config (.mcp.json) ────────────────────────────────────────
+
 function buildClaudeConfig(pythonBin, playwrightPort, integration) {
   const servers = {};
   const missing = [];
   const needsAdo  = !integration || integration === "ado"  || integration === "both";
   const needsJira = integration === "jira" || integration === "both";
-
-  // ADO agents — always included for ado/both; also included for jira because
-  // qa-gherkin-generator, qa-playwright-generator, and qa-helix-writer are shared
-  // by the Jira pipeline (Gherkin → Playwright → Helix steps run the same agents).
   const activeNames = (needsAdo || needsJira) ? AGENT_NAMES : [];
 
   for (const name of activeNames) {
     const bin = findBinary(name, pythonBin);
     if (bin) {
-      servers[name] = { command: bin };
+      // Every server gets the cost tracking env block
+      servers[name] = { command: bin, env: { ...COST_ENV } };
     } else {
       missing.push(name);
-      servers[name] = { command: `/path/to/.venv/bin/${name}`, "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents" };
+      servers[name] = {
+        command: `/path/to/.venv/bin/${name}`,
+        env: { ...COST_ENV },
+        "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents",
+      };
     }
   }
 
-  // Jira agent — only when integration includes jira
   if (needsJira) {
     const jiraBin = findBinary(JIRA_AGENT_NAME, pythonBin);
     if (jiraBin) {
-      servers[JIRA_AGENT_NAME] = { command: jiraBin, env: JIRA_ENV_VARS };
+      servers[JIRA_AGENT_NAME] = {
+        command: jiraBin,
+        env: { ...COST_ENV, ...JIRA_ENV_VARS },
+      };
     } else {
       missing.push(JIRA_AGENT_NAME);
       servers[JIRA_AGENT_NAME] = {
         command: `/path/to/.venv/bin/${JIRA_AGENT_NAME}`,
-        env: JIRA_ENV_VARS,
+        env: { ...COST_ENV, ...JIRA_ENV_VARS },
         "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents",
       };
     }
   }
 
-  servers["playwright"] = {
-    type: "url",
-    url: `ws://localhost:${playwrightPort}`,
-  };
+  servers["playwright"] = { type: "url", url: `ws://localhost:${playwrightPort}` };
 
   return { config: { mcpServers: servers }, missing };
 }
 
+// ── VS Code config (.vscode/mcp.json) ─────────────────────────────────────
+
 function buildVscodeConfig(pythonBin, playwrightPort, integration) {
   const servers = {};
   const missing = [];
   const needsAdo  = !integration || integration === "ado"  || integration === "both";
   const needsJira = integration === "jira" || integration === "both";
-  // Shared agents (Gherkin, Playwright, Helix) are needed by both ADO and Jira pipelines.
   const activeNames = (needsAdo || needsJira) ? AGENT_NAMES : [];
 
   for (const name of activeNames) {
     const bin = findBinary(name, pythonBin);
     if (bin) {
-      servers[name] = { command: bin };
+      servers[name] = {
+        type: "stdio",
+        command: bin,
+        args: [],
+        env: {
+          // Azure DevOps auth passthrough (original)
+          "AZURE_TENANT_ID":     "${env:AZURE_TENANT_ID}",
+          "AZURE_CLIENT_ID":     "${env:AZURE_CLIENT_ID}",
+          "AZURE_CLIENT_SECRET": "${env:AZURE_CLIENT_SECRET}",
+          // Cost tracking passthrough (new)
+          ...COST_ENV,
+        },
+      };
     } else {
       missing.push(name);
-      servers[name] = { command: `/path/to/.venv/bin/${name}`, "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents" };
+      servers[name] = {
+        type: "stdio",
+        command: `/path/to/.venv/bin/${name}`,
+        args: [],
+        env: { ...COST_ENV },
+        "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents",
+      };
     }
   }
 
-  // Jira agent — only when integration includes jira
   if (needsJira) {
-    const jiraBinV = findBinary(JIRA_AGENT_NAME, pythonBin);
-    if (jiraBinV) {
-      servers[JIRA_AGENT_NAME] = { command: jiraBinV, env: JIRA_ENV_VARS };
+    const jiraBin = findBinary(JIRA_AGENT_NAME, pythonBin);
+    if (jiraBin) {
+      servers[JIRA_AGENT_NAME] = {
+        type: "stdio",
+        command: jiraBin,
+        args: [],
+        env: {
+          ...COST_ENV,
+          ...JIRA_ENV_VARS,
+        },
+      };
     } else {
       missing.push(JIRA_AGENT_NAME);
       servers[JIRA_AGENT_NAME] = {
+        type: "stdio",
         command: `/path/to/.venv/bin/${JIRA_AGENT_NAME}`,
-        env: JIRA_ENV_VARS,
+        args: [],
+        env: { ...COST_ENV, ...JIRA_ENV_VARS },
         "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents",
       };
     }
@@ -190,9 +251,13 @@ function printNextSteps(mode, playwrightPort) {
   ${C.dim}headless (CI): npx @playwright/mcp@latest --headless --port ${playwrightPort}${C.reset}
 
   ${isVscode
-    ? `Reload VS Code window — all 5 MCP servers will appear in the MCP panel.`
-    : `In Claude Code, run /mcp to verify all 5 servers are loaded.`
+    ? `Reload VS Code window — all MCP servers will appear in the MCP panel.`
+    : `In Claude Code, run /mcp to verify all servers are loaded.`
   }
+
+  ${C.dim}Cost tracking is active on all servers.
+  Each tool call logs tokens + cost to ~/.qa-stlc/cost-<session>.jsonl
+  View reports: qa-stlc cost${C.reset}
 `);
 }
 
@@ -220,7 +285,7 @@ module.exports = async function mcpConfig(opts) {
     fs.mkdirSync(dir, { recursive: true });
     const out = path.join(dir, "mcp.json");
     fs.writeFileSync(out, JSON.stringify(config, null, 2) + "\n", "utf8");
-    ok(`Written → .vscode/mcp.json`);
+    ok(`Written → .vscode/mcp.json  (cost tracking env vars included)`);
     if (missing.length) {
       warn(`${missing.length} agent(s) not found — run: pip install qa-gentic-stlc-agents`);
       missing.forEach((m) => warn(`  missing: ${m}`));
@@ -230,7 +295,7 @@ module.exports = async function mcpConfig(opts) {
     const { config, missing } = buildClaudeConfig(pythonBin, playwrightPort, integration);
     const out = path.join(CWD, ".mcp.json");
     fs.writeFileSync(out, JSON.stringify(config, null, 2) + "\n", "utf8");
-    ok(`Written → .mcp.json`);
+    ok(`Written → .mcp.json  (cost tracking env vars included)`);
     if (missing.length) {
       warn(`${missing.length} agent(s) not found — run: pip install qa-gentic-stlc-agents`);
       missing.forEach((m) => warn(`  missing: ${m}`));

package/src/stlc_agents/agent_gherkin_generator/server.py

@@ -323,6 +323,55 @@ async def list_tools() -> list[types.Tool]:
                 "required": ["gherkin_content"],
             },
         ),
+
+        # ── NEW: Headless composite — fetch + validate + attach with retry ───
+        types.Tool(
+            name="generate_and_attach_gherkin",
+            description=(
+                "Headless composite tool: fetch work item data, validate Gherkin content, "
+                "and attach to ADO — retrying once internally if validation fails. "
+                "Use this from the pipeline or CI runner instead of calling "
+                "validate_gherkin_content + attach_gherkin_to_feature/work_item separately. "
+                "Accepts pre-generated gherkin_content from the LLM caller. "
+                "If validation fails on the first pass the errors are returned as "
+                "validation_failed (no retry is possible without a new LLM call — "
+                "the pipeline must re-generate and call this tool again). "
+                "Returns {status, gherkin_content, attached} on success, "
+                "or {status: validation_failed, errors, gherkin_content} on failure."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "work_item_id": {
+                        "type": "integer",
+                        "description": "ADO Feature, PBI, or Bug ID",
+                    },
+                    "work_item_title": {
+                        "type": "string",
+                        "description": "Title of the work item (used in filename)",
+                    },
+                    "organization_url": {"type": "string"},
+                    "project_name": {"type": "string"},
+                    "gherkin_content": {
+                        "type": "string",
+                        "description": "Pre-generated .feature file content from LLM caller",
+                    },
+                    "scope": {
+                        "type": "string",
+                        "enum": ["feature", "work_item"],
+                        "description": (
+                            "'feature' attaches to a Feature work item (5–10 scenarios). "
+                            "'work_item' attaches to a PBI or Bug (3–9 scenarios). "
+                            "Default: 'work_item'."
+                        ),
+                    },
+                },
+                "required": [
+                    "work_item_id", "work_item_title", "organization_url",
+                    "project_name", "gherkin_content",
+                ],
+            },
+        ),
     ]
 
 
@@ -416,6 +465,44 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
                 arguments.get("scope", "feature"),
             )
 
+        elif name == "generate_and_attach_gherkin":
+            org = arguments["organization_url"]
+            project = arguments["project_name"]
+            wi_id = arguments["work_item_id"]
+            wi_title = arguments["work_item_title"]
+            gherkin = arguments["gherkin_content"]
+            scope = arguments.get("scope", "work_item")
+
+            # Step 1: validate
+            validation = await asyncio.to_thread(_validate_gherkin, gherkin, scope)
+            if not validation["valid"]:
+                result = {
+                    "status": "validation_failed",
+                    "errors": validation.get("errors", []),
+                    "gherkin_content": gherkin,
+                    "message": (
+                        "Gherkin content failed structural validation. "
+                        "The pipeline must re-generate and call this tool again "
+                        "with corrected content. No file was attached to ADO."
+                    ),
+                }
+            else:
+                # Step 2: attach
+                if scope == "feature":
+                    attach = await asyncio.to_thread(
+                        _attach_feature, org, project, wi_id, wi_title, gherkin
+                    )
+                else:
+                    attach = await asyncio.to_thread(
+                        _attach_wi_file, org, project, wi_id, wi_title, gherkin
+                    )
+                attach["_validation"] = _validate_attach_response(attach, scope)
+                result = {
+                    "status": "ok",
+                    "gherkin_content": gherkin,
+                    "attached": attach,
+                }
+
         else:
             result = {"error": f"Unknown tool: {name}"}
 
@@ -448,7 +535,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
-
-
-    
+    main()