@glasstrace/sdk 1.10.1 → 1.11.0

package/dist/cli/mcp-add.cjs

@@ -14277,33 +14277,61 @@ var AGENT_RULES = [
   },
   {
     name: "codex",
+    // Codex 2026 default discovery is `AGENTS.override.md` → `AGENTS.md` →
+    // opt-in `project_doc_fallback_filenames`; `codex.md` is NOT in the
+    // default fallback list. Detection requires Codex-specific markers
+    // (`codex.md` legacy, `.codex/` config dir) — `AGENTS.md` is NOT
+    // included as a marker because the SDK now writes `AGENTS.md`
+    // broadly via the multi-target dispatcher's companion writes; if
+    // `AGENTS.md` were a Codex marker, every project with the SDK's
+    // own companion AGENTS.md would re-classify as Codex on subsequent
+    // detect runs and trigger unintended `.codex/config.toml` writes
+    // (Codex P1 + Copilot P1 review of Wave 18 PR #274). The canonical
+    // write destination remains AGENTS.md regardless of which marker
+    // classified the project.
     markers: ["codex.md", ".codex"],
     mcpConfigPath: (dir) => (0, import_node_path.join)(dir, ".codex", "config.toml"),
-    infoFilePath: (dir) => (0, import_node_path.join)(dir, "codex.md"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, "AGENTS.md"),
     cliBinary: "codex",
     registrationCommand: "npx glasstrace mcp add --agent codex"
   },
   {
     name: "gemini",
-    markers: [".gemini"],
+    markers: [".gemini", "GEMINI.md"],
     mcpConfigPath: (dir) => (0, import_node_path.join)(dir, ".gemini", "settings.json"),
-    infoFilePath: () => null,
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, "GEMINI.md"),
     cliBinary: "gemini",
     registrationCommand: "npx glasstrace mcp add --agent gemini"
   },
   {
     name: "cursor",
+    // `.cursor/rules/*.mdc` is the current canonical format per Cursor's
+    // 2026 docs. `.cursorrules` (single file) is supported-but-deprecated
+    // and stays as a transitional fallback that the multi-target write
+    // helper writes unconditionally alongside the .mdc canonical.
     markers: [".cursor", ".cursorrules"],
     mcpConfigPath: (dir) => (0, import_node_path.join)(dir, ".cursor", "mcp.json"),
-    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".cursorrules"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".cursor", "rules", "glasstrace.mdc"),
     cliBinary: null,
     registrationCommand: "npx glasstrace mcp add --agent cursor"
   },
   {
     name: "windsurf",
-    markers: [".windsurfrules", ".windsurf"],
+    // Windsurf's current canonical workspace-rules format is
+    // `.windsurf/rules/*.md`. AGENTS.md is a parallel cross-tool
+    // mechanism Windsurf also reads BUT is NOT included as a Windsurf
+    // detection marker — the SDK writes `AGENTS.md` broadly via the
+    // multi-target dispatcher's companion writes, so treating
+    // `AGENTS.md` as a Windsurf marker would re-classify every
+    // SDK-managed project as Windsurf and cause `glasstrace uninit`
+    // to mutate the global `~/.codeium/windsurf/mcp_config.json` for
+    // non-Windsurf projects (Codex P1 + Copilot P1 review of Wave 18
+    // PR #274). The single-file `.windsurfrules` is the deprecated
+    // legacy form — recognized as a marker so legacy projects classify
+    // correctly, but the SDK no longer writes to it.
+    markers: [".windsurf", ".windsurfrules"],
     mcpConfigPath: () => (0, import_node_path.join)((0, import_node_os.homedir)(), ".codeium", "windsurf", "mcp_config.json"),
-    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".windsurfrules"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".windsurf", "rules", "glasstrace.md"),
     cliBinary: null,
     registrationCommand: "npx glasstrace mcp add --agent windsurf"
   }
@@ -14390,10 +14418,7 @@ async function detectAgents(projectRoot) {
       continue;
     }
     seenAgents.add(rule.name);
-    let infoFilePath = rule.infoFilePath(foundDir);
-    if (infoFilePath !== null && !await pathExists(infoFilePath)) {
-      infoFilePath = null;
-    }
+    const infoFilePath = rule.infoFilePath(foundDir);
     const cliAvailable = rule.cliBinary ? await isCliAvailable(rule.cliBinary) : false;
     detected.push({
       name: rule.name,
@@ -14406,7 +14431,7 @@ async function detectAgents(projectRoot) {
   detected.push({
     name: "generic",
     mcpConfigPath: (0, import_node_path.join)(resolvedRoot, ".glasstrace", "mcp.json"),
-    infoFilePath: null,
+    infoFilePath: (0, import_node_path.join)(resolvedRoot, "AGENTS.md"),
     cliAvailable: false,
     registrationCommand: null
   });
@@ -14436,7 +14461,13 @@ function buildAgentInstructionBody() {
     "1. Start with `find_trace_candidates`. Pass whatever route or procedure name is natural \u2014 the server normalizes vocabulary and, on miss, returns close matches and a sample of routes actually present in the window.",
     "2. Take the highest-confidence candidate's `suggestedFollowups` and pass them straight to `get_trace` or `get_root_cause`.",
     "3. For side-effect bugs, read `sideEffectSummary` in the `get_trace` / `get_root_cause` response. The allowlisted fields (`templateKey`, `providerOperation`, `role`, `locale`, `timezone`, `status`, `phase`) are the ones that disambiguate payload bugs.",
-    "4. If a tool returns empty, READ the response's `closeMatches`, `recentRoutesSample`, and `recoveryActions` before pivoting to source. Empty results carry `notAbsenceProof: true` \u2014 they are never proof the bug did not occur.",
+    "4. If a tool returns empty, READ the response's empty-result envelope before pivoting to source \u2014 each field disambiguates a different reason for the empty result:",
+    "   - `closeMatches` / `recentRoutesSample` \u2014 your filter vocabulary doesn't match server-side names; the server returns the closest known names + a sample of routes actually present.",
+    '   - `windowActivity` \u2014 load-bearing four-way distinguisher. `totalTracesInWindow === 0` AND `totalTracesInTenantEver > 0` means "your time window missed the activity"; `totalTracesInTenantEver === 0` means "this tenant has never produced traces" (SDK not registered, or never hit); `captureConfigBlocksRequest === true` means "the SDK\'s capture config dropped this route"; otherwise the empty result is a vocabulary miss \u2014 see `closeMatches`.',
+    "   - `humanReadable` \u2014 prose guidance written for the agent.",
+    "   - `recoveryActions` \u2014 concrete next-call shapes.",
+    "   - `diagnosticValue` / `recommendedNextStep` \u2014 whether to keep searching or stop.",
+    "   Empty results carry `notAbsenceProof: true` \u2014 they are never proof the bug did not occur.",
     "",
     "### Tools",
     "- `find_trace_candidates` \u2014 discovery, vocabulary-tolerant filter",
@@ -14580,34 +14611,75 @@ function generateInfoSection(agent, endpoint, sdkVersion) {
   }
   const content = buildAgentInstructionBody();
   switch (agent.name) {
-    case "claude": {
-      const m = htmlMarkers(sdkVersion);
-      return `${m.start}
-${content}${m.end}
-`;
-    }
-    case "codex": {
+    case "claude":
+    case "codex":
+    case "gemini":
+    case "windsurf":
+    case "generic": {
       const m = htmlMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
     }
     case "cursor": {
-      const m = hashMarkers(sdkVersion);
+      const m = htmlMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
     }
-    case "gemini":
-    case "windsurf":
-    case "generic":
-      return "";
     default: {
       const _exhaustive = agent.name;
       throw new Error(`Unknown agent: ${_exhaustive}`);
     }
   }
 }
+function generateInfoSectionForCursorrulesLegacy(endpoint, sdkVersion) {
+  if (!endpoint || endpoint.trim() === "") {
+    throw new Error("endpoint must not be empty");
+  }
+  if (!sdkVersion || sdkVersion.trim() === "") {
+    throw new Error("sdkVersion must not be empty");
+  }
+  if (!SDK_VERSION_STAMP_PATTERN.test(sdkVersion)) {
+    throw new Error(
+      "sdkVersion must match [A-Za-z0-9.+\\-]+ (semver-shaped, no whitespace, no angle brackets)"
+    );
+  }
+  const content = buildAgentInstructionBody();
+  const m = hashMarkers(sdkVersion);
+  return `${m.start}
+${content}${m.end}
+`;
+}
+function generateInfoSectionForCursorMdc(endpoint, sdkVersion) {
+  if (!endpoint || endpoint.trim() === "") {
+    throw new Error("endpoint must not be empty");
+  }
+  if (!sdkVersion || sdkVersion.trim() === "") {
+    throw new Error("sdkVersion must not be empty");
+  }
+  if (!SDK_VERSION_STAMP_PATTERN.test(sdkVersion)) {
+    throw new Error(
+      "sdkVersion must match [A-Za-z0-9.+\\-]+ (semver-shaped, no whitespace, no angle brackets)"
+    );
+  }
+  const content = buildAgentInstructionBody();
+  const m = htmlMarkers(sdkVersion);
+  return [
+    "---",
+    "description: Glasstrace MCP runtime debugging tools \u2014 runtime evidence the agent reads when source alone cannot resolve a bug",
+    "alwaysApply: true",
+    "---",
+    "",
+    `${m.start}
+${content}${m.end}
+`
+  ].join("\n");
+}
+
+// src/agent-detection/inject-all-targets.ts
+var import_promises3 = require("node:fs/promises");
+var import_node_path3 = require("node:path");
 
 // src/agent-detection/inject.ts
 var import_promises2 = require("node:fs/promises");
@@ -14682,71 +14754,6 @@ function findMarkerBoundaries(lines) {
   }
   return null;
 }
-async function injectInfoSection(agent, content, projectRoot) {
-  if (agent.infoFilePath === null) {
-    return;
-  }
-  if (content === "") {
-    return;
-  }
-  const filePath = agent.infoFilePath;
-  let existingContent = null;
-  try {
-    existingContent = await (0, import_promises2.readFile)(filePath, "utf-8");
-  } catch (err) {
-    const code = err.code;
-    if (code !== "ENOENT") {
-      if (isPermissionError(err)) {
-        process.stderr.write(
-          `Warning: cannot read info file ${filePath}: permission denied
-`
-        );
-        return;
-      }
-      throw err;
-    }
-  }
-  if (existingContent === null) {
-    try {
-      await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(filePath), { recursive: true });
-      await (0, import_promises2.writeFile)(filePath, content, "utf-8");
-    } catch (err) {
-      if (isPermissionError(err)) {
-        process.stderr.write(
-          `Warning: cannot write info file ${filePath}: permission denied
-`
-        );
-        return;
-      }
-      throw err;
-    }
-    return;
-  }
-  const lines = existingContent.split("\n");
-  const boundaries = findMarkerBoundaries(lines);
-  let newContent;
-  if (boundaries !== null) {
-    const before = lines.slice(0, boundaries.startIdx);
-    const after = lines.slice(boundaries.endIdx + 1);
-    const contentWithoutTrailingNewline = content.endsWith("\n") ? content.slice(0, -1) : content;
-    newContent = [...before, contentWithoutTrailingNewline, ...after].join("\n");
-  } else {
-    const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
-    newContent = existingContent + separator + content;
-  }
-  try {
-    await (0, import_promises2.writeFile)(filePath, newContent, "utf-8");
-  } catch (err) {
-    if (isPermissionError(err)) {
-      process.stderr.write(
-        `Warning: cannot write info file ${filePath}: permission denied
-`
-      );
-      return;
-    }
-    throw err;
-  }
-}
 async function updateGitignore(paths, projectRoot) {
   const gitignorePath = (0, import_node_path2.join)(projectRoot, ".gitignore");
   const relativePaths = paths.filter((p) => !(0, import_node_path2.isAbsolute)(p));
@@ -14794,6 +14801,228 @@ async function updateGitignore(paths, projectRoot) {
   }
 }
 
+// src/agent-detection/inject-all-targets.ts
+async function injectAllTargets(agents, endpoint, sdkVersion, projectRoot) {
+  const writtenAgentsMd = /* @__PURE__ */ new Set();
+  for (const agent of agents) {
+    const targets = computeTargets(agent, projectRoot);
+    for (const target of targets) {
+      if (target.isAgentsMdCompanion) {
+        if (writtenAgentsMd.has(target.path)) {
+          continue;
+        }
+        writtenAgentsMd.add(target.path);
+      }
+      let createContent;
+      let managedSectionOnly;
+      if (target.kind === "cursor-mdc") {
+        createContent = generateInfoSectionForCursorMdc(endpoint, sdkVersion);
+        managedSectionOnly = generateInfoSection(agent, endpoint, sdkVersion);
+      } else if (target.kind === "cursorrules-legacy") {
+        createContent = generateInfoSectionForCursorrulesLegacy(
+          endpoint,
+          sdkVersion
+        );
+        managedSectionOnly = createContent;
+      } else {
+        createContent = generateInfoSection(agent, endpoint, sdkVersion);
+        managedSectionOnly = createContent;
+      }
+      if (managedSectionOnly === "") continue;
+      await writeManagedSectionToTarget(
+        target.path,
+        createContent,
+        managedSectionOnly
+      );
+    }
+  }
+}
+function foundDirFromAgent(agent) {
+  if (agent.infoFilePath === null) return null;
+  switch (agent.name) {
+    case "claude":
+    case "codex":
+    case "gemini":
+    case "generic":
+      return (0, import_node_path3.dirname)(agent.infoFilePath);
+    case "cursor":
+      return (0, import_node_path3.dirname)((0, import_node_path3.dirname)((0, import_node_path3.dirname)(agent.infoFilePath)));
+    case "windsurf":
+      return (0, import_node_path3.dirname)((0, import_node_path3.dirname)((0, import_node_path3.dirname)(agent.infoFilePath)));
+  }
+}
+function computeTargets(agent, projectRoot) {
+  const targets = [];
+  const foundDir = foundDirFromAgent(agent) ?? projectRoot;
+  switch (agent.name) {
+    case "claude": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: (0, import_node_path3.join)(foundDir, "AGENTS.md"),
+        kind: "agents-md-companion",
+        isAgentsMdCompanion: true
+      });
+      return targets;
+    }
+    case "codex": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: true
+        });
+      }
+      return targets;
+    }
+    case "gemini": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: (0, import_node_path3.join)(foundDir, "AGENTS.md"),
+        kind: "agents-md-companion",
+        isAgentsMdCompanion: true
+      });
+      return targets;
+    }
+    case "cursor": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "cursor-mdc",
+          isAgentsMdCompanion: false
+        });
+        targets.push({
+          path: (0, import_node_path3.join)(foundDir, ".cursorrules"),
+          kind: "cursorrules-legacy",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: (0, import_node_path3.join)(foundDir, "AGENTS.md"),
+        kind: "agents-md-companion",
+        isAgentsMdCompanion: true
+      });
+      return targets;
+    }
+    case "windsurf": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: (0, import_node_path3.join)(foundDir, "AGENTS.md"),
+        kind: "agents-md-companion",
+        isAgentsMdCompanion: true
+      });
+      return targets;
+    }
+    case "generic": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: true
+        });
+      }
+      return targets;
+    }
+    default: {
+      const _exhaustive = agent.name;
+      throw new Error(`Unknown agent: ${_exhaustive}`);
+    }
+  }
+}
+async function writeManagedSectionToTarget(filePath, createContent, managedSectionOnly) {
+  let existingContent = null;
+  try {
+    existingContent = await (0, import_promises3.readFile)(filePath, "utf-8");
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") {
+      emitTargetWarning(filePath, "read", err);
+      return;
+    }
+  }
+  if (existingContent === null) {
+    try {
+      await (0, import_promises3.mkdir)((0, import_node_path3.dirname)(filePath), { recursive: true });
+      await (0, import_promises3.writeFile)(filePath, createContent, "utf-8");
+    } catch (err) {
+      emitTargetWarning(filePath, "write", err);
+      return;
+    }
+    return;
+  }
+  const lines = existingContent.split("\n");
+  const boundaries = findMarkerBoundaries(lines);
+  let newContent;
+  if (boundaries !== null) {
+    const before = lines.slice(0, boundaries.startIdx);
+    const after = lines.slice(boundaries.endIdx + 1);
+    const contentWithoutTrailingNewline = managedSectionOnly.endsWith("\n") ? managedSectionOnly.slice(0, -1) : managedSectionOnly;
+    newContent = [...before, contentWithoutTrailingNewline, ...after].join(
+      "\n"
+    );
+  } else {
+    const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+    newContent = existingContent + separator + managedSectionOnly;
+  }
+  try {
+    await (0, import_promises3.writeFile)(filePath, newContent, "utf-8");
+  } catch (err) {
+    emitTargetWarning(filePath, "write", err);
+  }
+}
+function emitTargetWarning(filePath, op, err) {
+  const code = err.code;
+  let qualifier;
+  switch (code) {
+    case "EACCES":
+    case "EPERM":
+      qualifier = "permission denied";
+      break;
+    case "EROFS":
+      qualifier = "filesystem read-only";
+      break;
+    case "ENOSPC":
+      qualifier = "disk full";
+      break;
+    case "ENAMETOOLONG":
+      qualifier = "path too long";
+      break;
+    case "ENOTDIR":
+      qualifier = "not a directory";
+      break;
+    case "EISDIR":
+      qualifier = "is a directory";
+      break;
+    default:
+      qualifier = "I/O error";
+      break;
+  }
+  try {
+    process.stderr.write(
+      `Warning: cannot ${op} info file ${filePath}: ${qualifier}
+`
+    );
+  } catch {
+  }
+}
+
 // src/cli/constants.ts
 function formatAgentName(name) {
   const displayNames = {
@@ -14949,14 +15178,9 @@ async function mcpAdd(options) {
   const bearer = resolved.effective.key;
   for (const agent of targetAgents) {
     const name = formatAgentName(agent.name);
-    const sdkVersion = true ? "1.10.1" : "0.0.0-dev";
     if (agent.name !== "generic") {
       const cliSuccess = await registerViaCli(agent, bearer);
       if (cliSuccess) {
-        const infoContent = generateInfoSection(agent, MCP_ENDPOINT, sdkVersion);
-        if (infoContent !== "") {
-          await injectInfoSection(agent, infoContent, projectRoot);
-        }
         results.push({
           agent: agent.name,
           success: true,
@@ -14971,10 +15195,6 @@ async function mcpAdd(options) {
         const configContent = generateMcpConfig(agent, MCP_ENDPOINT, bearer);
         await writeMcpConfig(agent, configContent, projectRoot);
         if (fs.existsSync(agent.mcpConfigPath)) {
-          const infoContent = generateInfoSection(agent, MCP_ENDPOINT, sdkVersion);
-          if (infoContent !== "") {
-            await injectInfoSection(agent, infoContent, projectRoot);
-          }
           results.push({
             agent: agent.name,
             success: true,
@@ -15007,6 +15227,34 @@ async function mcpAdd(options) {
       message: `${name}: No registration method available`
     });
   }
+  const successfulAgentNames = new Set(
+    results.filter((r) => r.success).map((r) => r.agent)
+  );
+  const agentsWithMcpReady = targetAgents.filter(
+    (a) => successfulAgentNames.has(a.name)
+  );
+  const detectedNonGenericMcpAdd = targetAgents.filter(
+    (a) => a.name !== "generic"
+  );
+  const nonGenericReadyMcpAdd = agentsWithMcpReady.filter(
+    (a) => a.name !== "generic"
+  );
+  const dispatchSetMcpAdd = detectedNonGenericMcpAdd.length === 0 ? agentsWithMcpReady : nonGenericReadyMcpAdd;
+  if (dispatchSetMcpAdd.length > 0) {
+    const sdkVersion = true ? "1.11.0" : "0.0.0-dev";
+    try {
+      await injectAllTargets(
+        dispatchSetMcpAdd,
+        MCP_ENDPOINT,
+        sdkVersion,
+        projectRoot
+      );
+    } catch (injectErr) {
+      messages.push(
+        `Warning: Failed to write some agent-instruction files: ${injectErr instanceof Error ? injectErr.message : String(injectErr)}`
+      );
+    }
+  }
   await updateGitignore(
     [".mcp.json", ".cursor/mcp.json", ".gemini/settings.json", ".codex/config.toml"],
     projectRoot