@glasstrace/sdk 1.4.0 → 1.5.0

package/README.md

@@ -98,6 +98,62 @@ total cap). HTTP 4xx/5xx and malformed responses are surfaced
 immediately. Set `GLASSTRACE_SKIP_INIT_VERIFY=1` to skip verification
 for offline installs.
 
+## Refreshing agent instruction guidance
+
+`glasstrace init` and `glasstrace mcp add` write a managed Glasstrace
+MCP section into your project's agent instruction file (CLAUDE.md /
+codex.md / .cursorrules). The section opens with a cost-aware
+cross-tool decision paragraph telling your AI agent **when** Glasstrace
+MCP is worth calling and **which** tool is the cheapest first call for
+each symptom class.
+
+The managed section's start marker carries an SDK version stamp, e.g.
+`<!-- glasstrace:mcp:start v=1.5.0 -->`. When you upgrade
+`@glasstrace/sdk`, run:
+
+```bash
+npx glasstrace upgrade-instructions
+```
+
+The command refreshes every detected agent instruction file in one
+run. Files outside the markers are untouched; files without a
+Glasstrace managed section are left alone. The command is idempotent
+— re-running produces byte-for-byte identical output.
+
+`npx glasstrace mcp add` performs the same managed-section refresh
+when run with `--force` (or against a project whose marker file has
+shifted credentials), so either command is a valid upgrade path.
+
+### Stale-section warning at SDK init
+
+When the running SDK detects that an agent instruction file's stamp
+is strictly older than the running version, it writes a single
+stderr line at `registerGlasstrace()` time pointing at the upgrade
+command. Constraints:
+
+- Stderr only, never stdout. Tracing behaviour is unaffected.
+- At most one warning per process boot, even when multiple
+  `registerGlasstrace()` calls happen (test runners, hot reload).
+- Node-only — no-op on Edge / browser runtimes. Never throws.
+- Does not mutate any file at runtime; the user opts in by running
+  the upgrade command.
+- Suppressed by setting one of:
+
+  ```bash
+  GLASSTRACE_DISABLE_UPGRADE_NOTICE=1
+  GLASSTRACE_DISABLE_UPGRADE_NOTICE=true
+  GLASSTRACE_DISABLE_UPGRADE_NOTICE=yes
+  ```
+
+  (case-insensitive). Any other value, including unset, leaves the
+  warning enabled.
+
+Legacy unstamped managed sections (written by `@glasstrace/sdk`
+versions before 1.5.0) trigger no warning — those projects receive
+the refreshed text on their next `mcp add` or
+`upgrade-instructions` run, and the upgrade replaces the legacy
+block in place rather than appending a duplicate.
+
 ## Server Action detection (Next.js)
 
 Next.js does not emit a dedicated OTel span for Server Actions. The SDK

package/dist/{chunk-JZ475QRH.js → chunk-D3QXU2VM.js}

@@ -252,28 +252,39 @@ function generateMcpConfig(agent, endpoint, bearer) {
     }
   }
 }
-function htmlMarkers() {
+var SDK_VERSION_STAMP_PATTERN = /^[A-Za-z0-9.+-]+$/;
+function htmlMarkers(sdkVersion) {
   return {
-    start: "<!-- glasstrace:mcp:start -->",
+    start: `<!-- glasstrace:mcp:start v=${sdkVersion} -->`,
     end: "<!-- glasstrace:mcp:end -->"
   };
 }
-function hashMarkers() {
+function hashMarkers(sdkVersion) {
   return {
-    start: "# glasstrace:mcp:start",
+    start: `# glasstrace:mcp:start v=${sdkVersion}`,
     end: "# glasstrace:mcp:end"
   };
 }
-function generateInfoSection(agent, endpoint) {
+function generateInfoSection(agent, 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 = [
     "",
     "## Glasstrace MCP Integration",
     "",
     `Glasstrace is configured as an MCP server at: ${endpoint}`,
     "",
+    "Glasstrace MCP is available when runtime evidence would materially reduce uncertainty. Use it when there is a failing request, stack trace, unclear runtime behavior, race/data-flow symptom, side effect, or performance issue that source inspection alone does not explain. For a current error, `get_latest_error` or `get_error_list` is usually the cheapest orientation call. For a known route/procedure with no exact error, use `find_trace_candidates` and follow returned exact `get_trace` or `get_root_cause` arguments only if the candidates look relevant. Do not call trace tools for trivial source-local fixes. Treat **no candidates** or **no_traces_found** as a scoped retrieval result, not proof the bug is absent.",
+    "",
     "Available tools:",
     "- `get_latest_error` - Get the most recent error trace from the current session",
     "- `find_trace_candidates` - First-contact route/procedure/URL candidate selection when you have a route fragment, tRPC procedure, method, status, or rough recent activity window but not the exact trace ID. Returns candidate traces plus suggested `get_trace` / `get_root_cause` follow-up call arguments. Candidate discovery, not root-cause proof.",
@@ -283,24 +294,24 @@ function generateInfoSection(agent, endpoint) {
     "- `get_test_suggestions` - Get test suggestions based on recent errors",
     "- `get_session_timeline` - Get the timeline of all traces in the current session",
     "",
-    "To reconfigure, run: `npx glasstrace mcp add`",
+    "To refresh this managed section after a `@glasstrace/sdk` upgrade, run: `npx glasstrace upgrade-instructions`. To reconfigure MCP credentials, run: `npx glasstrace mcp add`.",
     ""
   ].join("\n");
   switch (agent.name) {
     case "claude": {
-      const m = htmlMarkers();
+      const m = htmlMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
     }
     case "codex": {
-      const m = htmlMarkers();
+      const m = htmlMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
     }
     case "cursor": {
-      const m = hashMarkers();
+      const m = hashMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
@@ -316,189 +327,9 @@ ${content}${m.end}
   }
 }
 
-// src/agent-detection/inject.ts
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname as dirname2, isAbsolute, join as join2 } from "node:path";
-var HTML_START = "<!-- glasstrace:mcp:start -->";
-var HTML_END = "<!-- glasstrace:mcp:end -->";
-var HASH_START = "# glasstrace:mcp:start";
-var HASH_END = "# glasstrace:mcp:end";
-function isPermissionError(err) {
-  const code = err.code;
-  return code === "EACCES" || code === "EPERM" || code === "EROFS";
-}
-async function writeMcpConfig(agent, content, projectRoot) {
-  if (agent.mcpConfigPath === null) {
-    return;
-  }
-  const configPath = agent.mcpConfigPath;
-  const parentDir = dirname2(configPath);
-  try {
-    await mkdir(parentDir, { recursive: true });
-  } catch (err) {
-    if (isPermissionError(err)) {
-      process.stderr.write(
-        `Warning: cannot create directory ${parentDir}: permission denied
-`
-      );
-      return;
-    }
-    throw err;
-  }
-  try {
-    await writeFile(configPath, content, { mode: 384 });
-  } catch (err) {
-    if (isPermissionError(err)) {
-      process.stderr.write(
-        `Warning: cannot write config file ${configPath}: permission denied
-`
-      );
-      return;
-    }
-    throw err;
-  }
-  try {
-    await chmod(configPath, 384);
-  } catch {
-  }
-}
-function findMarkerBoundaries(lines) {
-  let startIdx = -1;
-  let endIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    const trimmed = lines[i].trim();
-    if (trimmed === HTML_START || trimmed === HASH_START) {
-      startIdx = i;
-    } else if (trimmed === HTML_END || trimmed === HASH_END) {
-      if (startIdx !== -1) {
-        endIdx = i;
-        break;
-      }
-    }
-  }
-  if (startIdx === -1 || endIdx === -1) {
-    return null;
-  }
-  return { startIdx, endIdx };
-}
-async function injectInfoSection(agent, content, projectRoot) {
-  if (agent.infoFilePath === null) {
-    return;
-  }
-  if (content === "") {
-    return;
-  }
-  const filePath = agent.infoFilePath;
-  let existingContent = null;
-  try {
-    existingContent = await 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 mkdir(dirname2(filePath), { recursive: true });
-      await 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 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 = join2(projectRoot, ".gitignore");
-  const relativePaths = paths.filter((p) => !isAbsolute(p));
-  if (relativePaths.length === 0) {
-    return;
-  }
-  let existingContent = "";
-  try {
-    existingContent = await readFile(gitignorePath, "utf-8");
-  } catch (err) {
-    const code = err.code;
-    if (code !== "ENOENT") {
-      if (isPermissionError(err)) {
-        process.stderr.write(
-          `Warning: cannot read .gitignore: permission denied
-`
-        );
-        return;
-      }
-      throw err;
-    }
-  }
-  const existingLines = existingContent.split("\n").map((line) => line.trim()).filter((line) => line !== "");
-  const existingSet = new Set(existingLines);
-  const toAdd = relativePaths.map((p) => p.trim().replace(/\\/g, "/")).filter((p) => p !== "" && !existingSet.has(p));
-  if (toAdd.length === 0) {
-    return;
-  }
-  let updatedContent = existingContent;
-  if (updatedContent.length > 0 && !updatedContent.endsWith("\n")) {
-    updatedContent += "\n";
-  }
-  updatedContent += toAdd.join("\n") + "\n";
-  try {
-    await writeFile(gitignorePath, updatedContent, "utf-8");
-  } catch (err) {
-    if (isPermissionError(err)) {
-      process.stderr.write(
-        `Warning: cannot write .gitignore: permission denied
-`
-      );
-      return;
-    }
-    throw err;
-  }
-}
-
 export {
   detectAgents,
   generateMcpConfig,
-  generateInfoSection,
-  writeMcpConfig,
-  injectInfoSection,
-  updateGitignore
+  generateInfoSection
 };
-//# sourceMappingURL=chunk-JZ475QRH.js.map
+//# sourceMappingURL=chunk-D3QXU2VM.js.map

package/dist/chunk-D3QXU2VM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent-detection/detect.ts","../src/agent-detection/configs.ts"],"sourcesContent":["import { execFile } from \"node:child_process\";\nimport { access, stat } from \"node:fs/promises\";\nimport { dirname, join, resolve } from \"node:path\";\nimport { homedir } from \"node:os\";\nimport { constants } from \"node:fs\";\n\n/**\n * Describes an AI coding agent detected in a project.\n */\nexport interface DetectedAgent {\n  name: \"claude\" | \"codex\" | \"gemini\" | \"cursor\" | \"windsurf\" | \"generic\";\n  mcpConfigPath: string | null;\n  infoFilePath: string | null;\n  cliAvailable: boolean;\n  registrationCommand: string | null;\n}\n\ntype AgentName = DetectedAgent[\"name\"];\n\ninterface AgentRule {\n  name: AgentName;\n  /** Paths relative to a search directory that indicate this agent is present. */\n  markers: string[];\n  /** Function to compute the MCP config path given the directory where markers were found. */\n  mcpConfigPath: (markerDir: string) => string;\n  /** Function to compute the info file path, or null. */\n  infoFilePath: (markerDir: string) => string | null;\n  /** CLI binary name to check in PATH, or null if no CLI exists. */\n  cliBinary: string | null;\n  /** Registration command template, or null. */\n  registrationCommand: string | null;\n}\n\nconst AGENT_RULES: AgentRule[] = [\n  {\n    name: \"claude\",\n    markers: [\".claude\", \"CLAUDE.md\"],\n    mcpConfigPath: (dir) => join(dir, \".mcp.json\"),\n    infoFilePath: (dir) => join(dir, \"CLAUDE.md\"),\n    cliBinary: \"claude\",\n    registrationCommand: \"npx glasstrace mcp add --agent claude\",\n  },\n  {\n    name: \"codex\",\n    markers: [\"codex.md\", \".codex\"],\n    mcpConfigPath: (dir) => join(dir, \".codex\", \"config.toml\"),\n    infoFilePath: (dir) => join(dir, \"codex.md\"),\n    cliBinary: \"codex\",\n    registrationCommand: \"npx glasstrace mcp add --agent codex\",\n  },\n  {\n    name: \"gemini\",\n    markers: [\".gemini\"],\n    mcpConfigPath: (dir) => join(dir, \".gemini\", \"settings.json\"),\n    infoFilePath: () => null,\n    cliBinary: \"gemini\",\n    registrationCommand: \"npx glasstrace mcp add --agent gemini\",\n  },\n  {\n    name: \"cursor\",\n    markers: [\".cursor\", \".cursorrules\"],\n    mcpConfigPath: (dir) => join(dir, \".cursor\", \"mcp.json\"),\n    infoFilePath: (dir) => join(dir, \".cursorrules\"),\n    cliBinary: null,\n    registrationCommand: \"npx glasstrace mcp add --agent cursor\",\n  },\n  {\n    name: \"windsurf\",\n    markers: [\".windsurfrules\", \".windsurf\"],\n    mcpConfigPath: () =>\n      join(homedir(), \".codeium\", \"windsurf\", \"mcp_config.json\"),\n    infoFilePath: (dir) => join(dir, \".windsurfrules\"),\n    cliBinary: null,\n    registrationCommand: \"npx glasstrace mcp add --agent windsurf\",\n  },\n];\n\n/**\n * Checks whether a path exists and is accessible, following symlinks.\n * Returns false on permission errors or missing paths.\n *\n * @param mode - The access mode to check (defaults to R_OK for marker detection).\n */\nasync function pathExists(\n  path: string,\n  mode: number = constants.R_OK,\n): Promise<boolean> {\n  try {\n    await access(path, mode);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Finds the git root directory by walking up from the given path.\n * Returns the starting directory if no `.git` is found.\n */\nasync function findGitRoot(startDir: string): Promise<string> {\n  let current = resolve(startDir);\n\n  while (true) {\n    if (await pathExists(join(current, \".git\"), constants.F_OK)) {\n      return current;\n    }\n    const parent = dirname(current);\n    if (parent === current) {\n      // Reached filesystem root without finding .git\n      break;\n    }\n    current = parent;\n  }\n\n  return resolve(startDir);\n}\n\n/**\n * Returns true if a CLI binary is available on PATH.\n * Uses `which` on Unix and `where` on Windows, via execFile (no shell injection).\n */\nfunction isCliAvailable(binary: string): Promise<boolean> {\n  return new Promise((resolve) => {\n    const command = process.platform === \"win32\" ? \"where\" : \"which\";\n    execFile(command, [binary], (error) => {\n      resolve(error === null);\n    });\n  });\n}\n\n/**\n * Detects AI coding agents present in a project by scanning for marker\n * files and directories. Walks up from projectRoot to the git root to\n * support monorepo layouts.\n *\n * Always includes a \"generic\" fallback entry.\n *\n * @param projectRoot - Absolute or relative path to the project directory.\n * @returns Array of detected agents, with generic always last.\n * @throws If projectRoot does not exist or is not a directory.\n */\nexport async function detectAgents(\n  projectRoot: string,\n): Promise<DetectedAgent[]> {\n  const resolvedRoot = resolve(projectRoot);\n\n  // Validate projectRoot exists and is a directory\n  let rootStat;\n  try {\n    rootStat = await stat(resolvedRoot);\n  } catch (err) {\n    const code = (err as NodeJS.ErrnoException).code;\n    throw new Error(\n      `projectRoot does not exist: ${resolvedRoot}` +\n        (code ? ` (${code})` : \"\"),\n    );\n  }\n\n  if (!rootStat.isDirectory()) {\n    throw new Error(`projectRoot is not a directory: ${resolvedRoot}`);\n  }\n\n  const gitRoot = await findGitRoot(resolvedRoot);\n\n  // Collect unique directories to search: projectRoot and every ancestor up to gitRoot\n  const searchDirs: string[] = [];\n  let current = resolvedRoot;\n  while (true) {\n    searchDirs.push(current);\n    if (current === gitRoot) {\n      break;\n    }\n    const parent = dirname(current);\n    if (parent === current) {\n      break;\n    }\n    current = parent;\n  }\n\n  const detected: DetectedAgent[] = [];\n  const seenAgents = new Set<AgentName>();\n\n  for (const rule of AGENT_RULES) {\n    let foundDir: string | null = null;\n\n    // Check each search directory for markers\n    for (const dir of searchDirs) {\n      let markerFound = false;\n      for (const marker of rule.markers) {\n        if (await pathExists(join(dir, marker))) {\n          markerFound = true;\n          break;\n        }\n      }\n      if (markerFound) {\n        foundDir = dir;\n        break;\n      }\n    }\n\n    if (foundDir === null) {\n      continue;\n    }\n\n    if (seenAgents.has(rule.name)) {\n      continue;\n    }\n    seenAgents.add(rule.name);\n\n    // Determine info file path — only include if the file actually exists\n    let infoFilePath = rule.infoFilePath(foundDir);\n    if (infoFilePath !== null && !(await pathExists(infoFilePath))) {\n      infoFilePath = null;\n    }\n\n    const cliAvailable = rule.cliBinary\n      ? await isCliAvailable(rule.cliBinary)\n      : false;\n\n    detected.push({\n      name: rule.name,\n      mcpConfigPath: rule.mcpConfigPath(foundDir),\n      infoFilePath,\n      cliAvailable,\n      registrationCommand: rule.registrationCommand,\n    });\n  }\n\n  // Always include generic fallback\n  detected.push({\n    name: \"generic\",\n    mcpConfigPath: join(resolvedRoot, \".glasstrace\", \"mcp.json\"),\n    infoFilePath: null,\n    cliAvailable: false,\n    registrationCommand: null,\n  });\n\n  return detected;\n}\n","import type { DetectedAgent } from \"./detect.js\";\n\n/**\n * Generates the MCP server configuration content for a given agent.\n *\n * The output is the full file content suitable for writing to the agent's\n * MCP config file. The bearer token is intentionally embedded here for\n * agents whose schemas inline the Authorization header — Codex is the\n * exception and uses `bearer_token_env_var` so the actual token never\n * appears in TOML.\n *\n * @param agent - The detected agent to generate config for.\n * @param endpoint - The Glasstrace MCP endpoint URL.\n * @param bearer - The credential to embed in the Authorization header\n *   (anon key or dev key, depending on the project's resolved\n *   credential source). Empty values throw.\n * @returns The formatted configuration string.\n * @throws If endpoint or bearer is empty.\n */\nexport function generateMcpConfig(\n  agent: DetectedAgent,\n  endpoint: string,\n  bearer: string,\n): string {\n  if (!endpoint || endpoint.trim() === \"\") {\n    throw new Error(\"endpoint must not be empty\");\n  }\n  if (!bearer || bearer.trim() === \"\") {\n    throw new Error(\"bearer must not be empty\");\n  }\n\n  switch (agent.name) {\n    case \"claude\":\n      return JSON.stringify(\n        {\n          mcpServers: {\n            glasstrace: {\n              type: \"http\",\n              url: endpoint,\n              headers: {\n                Authorization: `Bearer ${bearer}`,\n              },\n            },\n          },\n        },\n        null,\n        2,\n      );\n\n    case \"codex\": {\n      // Escape TOML basic string special characters in the endpoint value.\n      // TOML requires backslashes, quotes, and control characters to be escaped.\n      const safeEndpoint = endpoint\n        .replace(/\\\\/g, \"\\\\\\\\\")\n        .replace(/\"/g, '\\\\\"')\n        .replace(/\\n/g, \"\\\\n\")\n        .replace(/\\r/g, \"\\\\r\")\n        .replace(/\\t/g, \"\\\\t\");\n      return [\n        \"[mcp_servers.glasstrace]\",\n        `url = \"${safeEndpoint}\"`,\n        `bearer_token_env_var = \"GLASSTRACE_API_KEY\"`,\n        \"\",\n      ].join(\"\\n\");\n    }\n\n    case \"gemini\":\n      return JSON.stringify(\n        {\n          mcpServers: {\n            glasstrace: {\n              httpUrl: endpoint,\n              headers: {\n                Authorization: `Bearer ${bearer}`,\n              },\n            },\n          },\n        },\n        null,\n        2,\n      );\n\n    case \"cursor\":\n      return JSON.stringify(\n        {\n          mcpServers: {\n            glasstrace: {\n              url: endpoint,\n              headers: {\n                Authorization: `Bearer ${bearer}`,\n              },\n            },\n          },\n        },\n        null,\n        2,\n      );\n\n    case \"windsurf\":\n      return JSON.stringify(\n        {\n          mcpServers: {\n            glasstrace: {\n              serverUrl: endpoint,\n              headers: {\n                Authorization: `Bearer ${bearer}`,\n              },\n            },\n          },\n        },\n        null,\n        2,\n      );\n\n    case \"generic\":\n      return JSON.stringify(\n        {\n          mcpServers: {\n            glasstrace: {\n              type: \"http\",\n              url: endpoint,\n              headers: {\n                Authorization: `Bearer ${bearer}`,\n              },\n            },\n          },\n        },\n        null,\n        2,\n      );\n\n    default: {\n      const _exhaustive: never = agent.name;\n      throw new Error(`Unknown agent: ${_exhaustive}`);\n    }\n  }\n}\n\n/**\n * Strict pattern accepted as the value substituted into a `v=<sdkVersion>`\n * marker stamp. Covers the SDK's own published versions\n * (e.g. `1.4.0`, `0.0.0-canary-20260508120000`, `1.4.0+build.42`) without\n * admitting whitespace, angle-brackets, or terminal control sequences\n * that could be smuggled into the agent instruction file via a\n * malformed callsite.\n *\n * The stamp is the SDK semver string and nothing else (DISC-1592 / SDK-050\n * Required Semantics Item 1: \"the stamp encodes only the SDK semver\n * string ... it must not embed user-controlled or environment-derived\n * content\"). Reject anything outside this charset at the render site\n * rather than relying on the upstream `__SDK_VERSION__` define being\n * well-formed.\n */\nconst SDK_VERSION_STAMP_PATTERN = /^[A-Za-z0-9.+-]+$/;\n\n/**\n * Marker pair used to delimit the Glasstrace section in agent info files.\n */\ninterface MarkerPair {\n  start: string;\n  end: string;\n}\n\nfunction htmlMarkers(sdkVersion: string): MarkerPair {\n  return {\n    start: `<!-- glasstrace:mcp:start v=${sdkVersion} -->`,\n    end: \"<!-- glasstrace:mcp:end -->\",\n  };\n}\n\nfunction hashMarkers(sdkVersion: string): MarkerPair {\n  return {\n    start: `# glasstrace:mcp:start v=${sdkVersion}`,\n    end: \"# glasstrace:mcp:end\",\n  };\n}\n\n/**\n * Generates informational content for an agent's instruction file.\n *\n * This content is designed to be appended to or inserted into agent-specific\n * instruction files (CLAUDE.md, .cursorrules, codex.md). It contains ONLY\n * the endpoint URL, tool descriptions, and setup instructions. Auth tokens\n * are NEVER included in this output.\n *\n * The rendered block opens with a cost-aware cross-tool decision paragraph\n * (DISC-1593 / SDK-050) telling the user's AI agent **when** Glasstrace\n * MCP is worth calling at all and **which** tool is the cheapest first\n * call for each symptom class. The start marker carries a `v=<sdkVersion>`\n * stamp (DISC-1592 / SDK-050) so a later `glasstrace upgrade-instructions`\n * run — and the SDK's stale-section warning at init — can detect that\n * the file was rendered by an older SDK and refresh the block.\n *\n * @param agent - The detected agent to generate info for.\n * @param endpoint - The Glasstrace MCP endpoint URL.\n * @param sdkVersion - The SDK semver string to embed in the start marker\n *   (e.g. `1.4.0`, `0.0.0-canary-20260508120000`). Must match\n *   `[A-Za-z0-9.+\\-]+`; arbitrary or empty values throw.\n * @returns The formatted info section string, or empty string for agents without a supported info file format.\n * @throws If endpoint is empty, or if sdkVersion is empty or contains\n *   characters outside the accepted stamp charset.\n */\nexport function generateInfoSection(\n  agent: DetectedAgent,\n  endpoint: string,\n  sdkVersion: string,\n): string {\n  if (!endpoint || endpoint.trim() === \"\") {\n    throw new Error(\"endpoint must not be empty\");\n  }\n  if (!sdkVersion || sdkVersion.trim() === \"\") {\n    throw new Error(\"sdkVersion must not be empty\");\n  }\n  if (!SDK_VERSION_STAMP_PATTERN.test(sdkVersion)) {\n    throw new Error(\n      \"sdkVersion must match [A-Za-z0-9.+\\\\-]+ (semver-shaped, no whitespace, no angle brackets)\",\n    );\n  }\n\n  // Cost-aware cross-tool decision paragraph (DISC-1593 / SDK-050\n  // Required Semantics §1). Load-bearing semantics:\n  //   1. Frame Glasstrace MCP as conditionally worth calling.\n  //   2. Name cheapest-orientation routing per symptom class.\n  //   3. Restate the no-candidates / no_traces_found \"scoped retrieval\n  //      result, not absence of the bug\" contract.\n  //   4. List the conditions that justify calling Glasstrace MCP at all.\n  // Wording aligned with MCP-025's planned `recoveryActions` so the two\n  // surfaces do not contradict each other.\n  const content = [\n    \"\",\n    \"## Glasstrace MCP Integration\",\n    \"\",\n    `Glasstrace is configured as an MCP server at: ${endpoint}`,\n    \"\",\n    \"Glasstrace MCP is available when runtime evidence would materially reduce uncertainty. Use it when there is a failing request, stack trace, unclear runtime behavior, race/data-flow symptom, side effect, or performance issue that source inspection alone does not explain. For a current error, `get_latest_error` or `get_error_list` is usually the cheapest orientation call. For a known route/procedure with no exact error, use `find_trace_candidates` and follow returned exact `get_trace` or `get_root_cause` arguments only if the candidates look relevant. Do not call trace tools for trivial source-local fixes. Treat **no candidates** or **no_traces_found** as a scoped retrieval result, not proof the bug is absent.\",\n    \"\",\n    \"Available tools:\",\n    \"- `get_latest_error` - Get the most recent error trace from the current session\",\n    \"- `find_trace_candidates` - First-contact route/procedure/URL candidate selection when you have a route fragment, tRPC procedure, method, status, or rough recent activity window but not the exact trace ID. Returns candidate traces plus suggested `get_trace` / `get_root_cause` follow-up call arguments. Candidate discovery, not root-cause proof.\",\n    \"- `get_error_list` - List recent errors with filtering and pagination\",\n    \"- `get_trace` - Get a specific trace by ID or URL pattern\",\n    \"- `get_root_cause` - Get the root cause analysis for a specific error trace (requires a `traceId` from `get_latest_error`, `get_error_list`, or `get_trace`)\",\n    \"- `get_test_suggestions` - Get test suggestions based on recent errors\",\n    \"- `get_session_timeline` - Get the timeline of all traces in the current session\",\n    \"\",\n    \"To refresh this managed section after a `@glasstrace/sdk` upgrade, run: `npx glasstrace upgrade-instructions`. To reconfigure MCP credentials, run: `npx glasstrace mcp add`.\",\n    \"\",\n  ].join(\"\\n\");\n\n  switch (agent.name) {\n    case \"claude\": {\n      const m = htmlMarkers(sdkVersion);\n      return `${m.start}\\n${content}${m.end}\\n`;\n    }\n\n    case \"codex\": {\n      const m = htmlMarkers(sdkVersion);\n      return `${m.start}\\n${content}${m.end}\\n`;\n    }\n\n    case \"cursor\": {\n      const m = hashMarkers(sdkVersion);\n      return `${m.start}\\n${content}${m.end}\\n`;\n    }\n\n    case \"gemini\":\n    case \"windsurf\":\n    case \"generic\":\n      return \"\";\n\n    default: {\n      const _exhaustive: never = agent.name;\n      throw new Error(`Unknown agent: ${_exhaustive}`);\n    }\n  }\n}\n"],"mappings":"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","names":["resolve"]}

package/dist/{chunk-VQDYXXVS.js → chunk-N3XIVM2U.js}

@@ -49,6 +49,10 @@ import {
   GLASSTRACE_ATTRIBUTE_NAMES,
   deriveSessionId
 } from "./chunk-4WI7B5FQ.js";
+import {
+  isEndMarkerLine,
+  parseStartMarkerLine
+} from "./chunk-ZBQQXVHD.js";
 import {
   __require
 } from "./chunk-NSBPE2FW.js";
@@ -3553,7 +3557,7 @@ function appendRootPathToUrlIfNeeded(url) {
     return void 0;
   }
 }
-function appendResourcePathToUrl(url, path2) {
+function appendResourcePathToUrl(url, path3) {
   try {
     new URL(url);
   } catch {
@@ -3563,11 +3567,11 @@ function appendResourcePathToUrl(url, path2) {
   if (!url.endsWith("/")) {
     url = url + "/";
   }
-  url += path2;
+  url += path3;
   try {
     new URL(url);
   } catch {
-    diag.warn(`Configuration: Provided URL appended with '${path2}' is not a valid URL, using 'undefined' instead of '${url}'`);
+    diag.warn(`Configuration: Provided URL appended with '${path3}' is not a valid URL, using 'undefined' instead of '${url}'`);
     return void 0;
   }
   return url;
@@ -4267,6 +4271,144 @@ function writeStateNow() {
   }
 }
 
+// src/agent-detection/upgrade-notice.ts
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+var warningEmitted = false;
+var AGENT_INSTRUCTION_FILES = [
+  "CLAUDE.md",
+  "codex.md",
+  ".cursorrules"
+];
+function parseSemver(input) {
+  const plusIdx = input.indexOf("+");
+  const core = plusIdx === -1 ? input : input.slice(0, plusIdx);
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(core);
+  if (m === null) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] ?? null
+  };
+}
+function comparePrerelease(a, b) {
+  const ap = a.split(".");
+  const bp = b.split(".");
+  const len = Math.min(ap.length, bp.length);
+  for (let i = 0; i < len; i++) {
+    const x = ap[i];
+    const y = bp[i];
+    const xNumeric = /^\d+$/.test(x);
+    const yNumeric = /^\d+$/.test(y);
+    if (xNumeric && yNumeric) {
+      const xv = Number(x);
+      const yv = Number(y);
+      if (xv !== yv) return xv < yv ? -1 : 1;
+    } else if (xNumeric) {
+      return -1;
+    } else if (yNumeric) {
+      return 1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return ap.length - bp.length;
+}
+function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (pa === null || pb === null) return null;
+  if (pa.major !== pb.major) return pa.major - pb.major;
+  if (pa.minor !== pb.minor) return pa.minor - pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch - pb.patch;
+  if (pa.prerelease === null && pb.prerelease === null) return 0;
+  if (pa.prerelease === null) return 1;
+  if (pb.prerelease === null) return -1;
+  return comparePrerelease(pa.prerelease, pb.prerelease);
+}
+function isOptedOut() {
+  const raw = process.env.GLASSTRACE_DISABLE_UPGRADE_NOTICE;
+  if (typeof raw !== "string") return false;
+  const trimmed = raw.trim().toLowerCase();
+  return trimmed === "1" || trimmed === "true" || trimmed === "yes";
+}
+function isQuietCiContext() {
+  const stderrIsTty = process.stderr.isTTY === true;
+  if (stderrIsTty) return false;
+  return process.env.CI === "true";
+}
+var MAX_AGENT_FILE_BYTES = 5 * 1024 * 1024;
+function inspectFile(filePath, runningSdkVersion) {
+  let content;
+  try {
+    const stat = fs2.statSync(filePath);
+    if (!stat.isFile()) return "absent";
+    if (stat.size > MAX_AGENT_FILE_BYTES) return "absent";
+    content = fs2.readFileSync(filePath, "utf-8");
+  } catch {
+    return "absent";
+  }
+  const lines = content.split("\n");
+  let lastStart = null;
+  let foundEnd = false;
+  for (const line of lines) {
+    const parsed = parseStartMarkerLine(line);
+    if (parsed !== null) {
+      lastStart = parsed;
+      continue;
+    }
+    if (lastStart !== null && isEndMarkerLine(line)) {
+      foundEnd = true;
+      break;
+    }
+  }
+  if (lastStart === null || !foundEnd) {
+    return "no-section";
+  }
+  if (lastStart.stamp === null) {
+    return "no-stamp";
+  }
+  const cmp = compareSemver(lastStart.stamp, runningSdkVersion);
+  if (cmp === null) {
+    return "unknown-stamp";
+  }
+  return cmp < 0 ? "stale" : "current";
+}
+function maybeWarnStaleAgentInstructions(options) {
+  try {
+    if (warningEmitted) return;
+    if (typeof process === "undefined" || typeof process.versions?.node !== "string" || typeof process.env !== "object" || process.env === null) {
+      return;
+    }
+    if (isOptedOut()) return;
+    if (isQuietCiContext()) return;
+    if (parseSemver(options.sdkVersion) === null) return;
+    const staleFiles = [];
+    for (const fileName of AGENT_INSTRUCTION_FILES) {
+      const fullPath = path2.join(options.projectRoot, fileName);
+      const state = inspectFile(fullPath, options.sdkVersion);
+      if (state === "stale") {
+        staleFiles.push(fileName);
+      }
+    }
+    if (staleFiles.length === 0) return;
+    const fileList = staleFiles.join(", ");
+    const message = `[glasstrace] Glasstrace managed MCP section in ${fileList} was rendered by an older @glasstrace/sdk; run \`npx glasstrace upgrade-instructions\` to refresh (silence with GLASSTRACE_DISABLE_UPGRADE_NOTICE=1).
+`;
+    warningEmitted = true;
+    if (options.stderrWrite !== void 0) {
+      options.stderrWrite(message);
+      return;
+    }
+    try {
+      process.stderr.write(message);
+    } catch {
+    }
+  } catch {
+  }
+}
+
 // src/register.ts
 function maskKey(key) {
   if (key.length <= 12) return key.slice(0, 4) + "...";
@@ -4295,9 +4437,13 @@ function registerGlasstrace(options) {
       return;
     }
     setCoreState(CoreState.REGISTERING);
+    maybeWarnStaleAgentInstructions({
+      projectRoot: process.cwd(),
+      sdkVersion: "1.5.0"
+    });
     startRuntimeStateWriter({
       projectRoot: process.cwd(),
-      sdkVersion: "1.4.0"
+      sdkVersion: "1.5.0"
     });
     const config = resolveConfig(options);
     if (config.verbose) {
@@ -4464,8 +4610,8 @@ async function backgroundInit(config, anonKeyForInit, generation) {
   if (config.verbose) {
     console.info("[glasstrace] Background init firing.");
   }
-  const healthReport = collectHealthReport("1.4.0");
-  const initResult = await performInit(config, anonKeyForInit, "1.4.0", healthReport);
+  const healthReport = collectHealthReport("1.5.0");
+  const initResult = await performInit(config, anonKeyForInit, "1.5.0", healthReport);
   if (generation !== registrationGeneration) return;
   const currentState = getCoreState();
   if (currentState === CoreState.SHUTTING_DOWN || currentState === CoreState.SHUTDOWN) {
@@ -4488,7 +4634,7 @@ async function backgroundInit(config, anonKeyForInit, generation) {
   }
   maybeInstallConsoleCapture();
   if (didLastInitSucceed()) {
-    startHeartbeat(config, anonKeyForInit, "1.4.0", generation, (newApiKey, accountId) => {
+    startHeartbeat(config, anonKeyForInit, "1.5.0", generation, (newApiKey, accountId) => {
       setAuthState(AuthState.CLAIMING);
       emitLifecycleEvent("auth:claim_started", { accountId });
       setResolvedApiKey(newApiKey);
@@ -4888,4 +5034,4 @@ export {
   withGlasstraceConfig,
   captureError
 };
-//# sourceMappingURL=chunk-VQDYXXVS.js.map
+//# sourceMappingURL=chunk-N3XIVM2U.js.map