@glasstrace/sdk 1.3.9 → 1.5.0

package/dist/index.cjs

@@ -339,10 +339,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path3) {
-  if (!path3)
+function getElementAtPath(obj, path4) {
+  if (!path4)
     return obj;
-  return path3.reduce((acc, key) => acc?.[key], obj);
+  return path4.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -654,11 +654,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path3, issues) {
+function prefixIssues(path4, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path3);
+    iss.path.unshift(path4);
     return iss;
   });
 }
@@ -901,7 +901,7 @@ function formatError(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path3 = []) => {
+  const processError = (error49, path4 = []) => {
     var _a2, _b;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -911,7 +911,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path3, ...issue2.path];
+        const fullpath = [...path4, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -943,8 +943,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path3 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path3) {
+  const path4 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path4) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -13708,13 +13708,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path3 = ref.slice(1).split("/").filter(Boolean);
-  if (path3.length === 0) {
+  const path4 = ref.slice(1).split("/").filter(Boolean);
+  if (path4.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path3[0] === defsKey) {
-    const key = path3[1];
+  if (path4[0] === defsKey) {
+    const key = path4[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -14563,7 +14563,7 @@ function deriveSessionId(apiKey, origin, date5, windowIndex) {
   const digest = sha256Hex(input).slice(0, 16);
   return SessionIdSchema.parse(digest);
 }
-var DevApiKeySchema, AnonApiKeySchema, SessionIdSchema, BuildHashSchema, SdkDiagnosticCodeSchema, CaptureConfigSchema, SdkCachedConfigSchema, GlasstraceOptionsSchema, GlasstraceEnvVarsSchema, GLASSTRACE_ATTRIBUTE_NAMES, DEFAULT_CAPTURE_CONFIG, MAX_SOURCE_MAP_FILE_PATH_LENGTH, MAX_SOURCE_MAP_FILE_SIZE, MAX_SOURCE_MAP_FILE_COUNT, MAX_PRESIGNED_CLIENT_TOKEN_LENGTH, MAX_PRESIGNED_PATHNAME_LENGTH, ImportGraphPayloadSchema, SdkHealthReportSchema, TierLimitsSchema, SdkInitResponseSchema, DiscoveryResponseSchema, SourceMapUploadResponseSchema, PresignedUploadRequestSchema, PresignedUploadResponseSchema, SourceMapManifestRequestSchema, SourceMapManifestResponseSchema, K;
+var DevApiKeySchema, AnonApiKeySchema, SessionIdSchema, BuildHashSchema, SdkDiagnosticCodeSchema, CaptureConfigSchema, SdkCachedConfigSchema, GlasstraceOptionsSchema, GlasstraceEnvVarsSchema, GLASSTRACE_ATTRIBUTE_NAMES, DEFAULT_CAPTURE_CONFIG, MAX_SOURCE_MAP_FILE_PATH_LENGTH, MAX_SOURCE_MAP_FILE_SIZE, MAX_SOURCE_MAP_FILE_COUNT, MAX_PRESIGNED_CLIENT_TOKEN_LENGTH, MAX_PRESIGNED_PATHNAME_LENGTH, ImportGraphPayloadSchema, SdkHealthReportSchema, TierLimitsSchema, SdkInitResponseSchema, DiscoveryResponseSchema, SourceMapUploadResponseSchema, PresignedUploadRequestSchema, PresignedUploadResponseSchema, SourceMapManifestRequestSchema, SourceMapManifestResponseSchema, K, SIDE_EFFECT_OPERATION_KINDS, SIDE_EFFECT_SEMANTIC_FIELD_KEYS, SIDE_EFFECT_OMISSION_REASONS, SIDE_EFFECT_OPERATION_STATUSES, SIDE_EFFECT_OPERATION_PHASES;
 var init_dist = __esm({
   "../protocol/dist/index.js"() {
     "use strict";
@@ -14591,7 +14591,18 @@ var init_dist = __esm({
       fullConsoleOutput: external_exports.boolean(),
       importGraph: external_exports.boolean(),
       consoleErrors: external_exports.boolean().optional().default(false),
-      errorResponseBodies: external_exports.boolean().optional().default(false)
+      errorResponseBodies: external_exports.boolean().optional().default(false),
+      /**
+       * Account opt-in for side-effect evidence emission (SDK-049).
+       *
+       * When `false` (default), `recordSideEffect()` is a silent no-op:
+       * no allowlist evaluation runs and no `glasstrace.side_effect.*`
+       * attribute reaches the wire. When `true`, allowlisted side-effect
+       * metadata is attached to the active OTel span subject to the
+       * client-side allowlist enforcement layered with the product's
+       * storage-time filter as defense-in-depth.
+       */
+      sideEffectEvidence: external_exports.boolean().optional().default(false)
     });
     SdkCachedConfigSchema = external_exports.object({
       response: external_exports.record(external_exports.string(), external_exports.unknown()),
@@ -14651,7 +14662,37 @@ var init_dist = __esm({
       TRIGGER_TYPE: "glasstrace.trigger.type",
       ELEMENT_FINGERPRINT: "glasstrace.element.fingerprint",
       ELEMENT_CONFIDENCE: "glasstrace.element.confidence",
-      TAB_ID: "glasstrace.tab.id"
+      TAB_ID: "glasstrace.tab.id",
+      // Side-effect evidence (SDK-049 / SCHEMA-036).
+      // Top-level operation attributes attached to the active span when a
+      // side-effect is recorded via `recordSideEffect()`. The wire-string
+      // set aligns verbatim with the product-side filter in
+      // `packages/ingestion/src/services/trace-writer.ts`.
+      SIDE_EFFECT_KIND: "glasstrace.side_effect.kind",
+      SIDE_EFFECT_OPERATION: "glasstrace.side_effect.operation",
+      SIDE_EFFECT_STATUS: "glasstrace.side_effect.status",
+      SIDE_EFFECT_PHASE: "glasstrace.side_effect.phase",
+      // Allowlisted semantic field attributes — one per allowlisted key.
+      // Wire keys are camelCase to match the SCHEMA-036 enum members
+      // exactly; the SDK constant names are SCREAMING_SNAKE per the rest
+      // of GLASSTRACE_ATTRIBUTE_NAMES.
+      SIDE_EFFECT_FIELD_TEMPLATE_KEY: "glasstrace.side_effect.field.templateKey",
+      SIDE_EFFECT_FIELD_PROVIDER_OPERATION: "glasstrace.side_effect.field.providerOperation",
+      SIDE_EFFECT_FIELD_ROLE: "glasstrace.side_effect.field.role",
+      SIDE_EFFECT_FIELD_LOCALE: "glasstrace.side_effect.field.locale",
+      SIDE_EFFECT_FIELD_TIMEZONE: "glasstrace.side_effect.field.timezone",
+      SIDE_EFFECT_FIELD_STATUS: "glasstrace.side_effect.field.status",
+      SIDE_EFFECT_FIELD_PHASE: "glasstrace.side_effect.field.phase",
+      // Omission reason attributes — one per allowlisted reason. The
+      // attribute value carries an integer count; the rejected value is
+      // never echoed.
+      SIDE_EFFECT_OMITTED_PII: "glasstrace.side_effect.omitted.pii",
+      SIDE_EFFECT_OMITTED_SECRET: "glasstrace.side_effect.omitted.secret",
+      SIDE_EFFECT_OMITTED_RAW_PAYLOAD: "glasstrace.side_effect.omitted.raw_payload",
+      SIDE_EFFECT_OMITTED_UNSUPPORTED_KEY: "glasstrace.side_effect.omitted.unsupported_key",
+      SIDE_EFFECT_OMITTED_VALUE_TOO_LONG: "glasstrace.side_effect.omitted.value_too_long",
+      SIDE_EFFECT_OMITTED_NOT_EMITTED: "glasstrace.side_effect.omitted.not_emitted",
+      SIDE_EFFECT_OMITTED_CAPTURE_DISABLED: "glasstrace.side_effect.omitted.capture_disabled"
     };
     DEFAULT_CAPTURE_CONFIG = {
       requestBodies: false,
@@ -14660,7 +14701,8 @@ var init_dist = __esm({
       fullConsoleOutput: false,
       importGraph: false,
       consoleErrors: false,
-      errorResponseBodies: false
+      errorResponseBodies: false,
+      sideEffectEvidence: false
     };
     MAX_SOURCE_MAP_FILE_PATH_LENGTH = 512;
     MAX_SOURCE_MAP_FILE_SIZE = 50 * 1024 * 1024;
@@ -14849,6 +14891,45 @@ var init_dist = __esm({
       3204031479,
       3329325298
     ]);
+    SIDE_EFFECT_OPERATION_KINDS = [
+      "email",
+      "calendar_link",
+      "webhook",
+      "external_api",
+      "queue",
+      "after_callback"
+    ];
+    SIDE_EFFECT_SEMANTIC_FIELD_KEYS = [
+      "templateKey",
+      "providerOperation",
+      "role",
+      "locale",
+      "timezone",
+      "status",
+      "phase"
+    ];
+    SIDE_EFFECT_OMISSION_REASONS = [
+      "pii",
+      "secret",
+      "raw_payload",
+      "unsupported_key",
+      "value_too_long",
+      "not_emitted",
+      "capture_disabled"
+    ];
+    SIDE_EFFECT_OPERATION_STATUSES = [
+      "scheduled",
+      "started",
+      "succeeded",
+      "failed",
+      "unknown"
+    ];
+    SIDE_EFFECT_OPERATION_PHASES = [
+      "request",
+      "post_response",
+      "background",
+      "unknown"
+    ];
   }
 });
 
@@ -16440,10 +16521,10 @@ function sanitize(input) {
 }
 function markerFileExists() {
   try {
-    const fs3 = require("node:fs");
-    const path3 = require("node:path");
-    const markerPath = path3.join(process.cwd(), ".glasstrace", "mcp-connected");
-    return fs3.existsSync(markerPath);
+    const fs4 = require("node:fs");
+    const path4 = require("node:path");
+    const markerPath = path4.join(process.cwd(), ".glasstrace", "mcp-connected");
+    return fs4.existsSync(markerPath);
   } catch {
     return false;
   }
@@ -16592,7 +16673,7 @@ __export(source_map_uploader_exports, {
   uploadToBlob: () => uploadToBlob
 });
 async function discoverSourceMapFiles(buildDir) {
-  const resolvedDir = path2.resolve(buildDir);
+  const resolvedDir = path3.resolve(buildDir);
   const results = [];
   try {
     await walkDirMetadata(resolvedDir, resolvedDir, results);
@@ -16613,18 +16694,18 @@ async function discoverSourceMapFiles(buildDir) {
 async function walkDirMetadata(baseDir, currentDir, results) {
   let entries;
   try {
-    entries = await fs2.readdir(currentDir, { withFileTypes: true });
+    entries = await fs3.readdir(currentDir, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of entries) {
-    const fullPath = path2.join(currentDir, entry.name);
+    const fullPath = path3.join(currentDir, entry.name);
     if (entry.isDirectory()) {
       await walkDirMetadata(baseDir, fullPath, results);
     } else if (entry.isFile() && entry.name.endsWith(".map")) {
       try {
-        const stat2 = await fs2.stat(fullPath);
-        const relativePath = path2.relative(baseDir, fullPath).replace(/\\/g, "/");
+        const stat2 = await fs3.stat(fullPath);
+        const relativePath = path3.relative(baseDir, fullPath).replace(/\\/g, "/");
         const compiledPath = relativePath.replace(/\.map$/, "");
         results.push({
           filePath: compiledPath,
@@ -16637,7 +16718,7 @@ async function walkDirMetadata(baseDir, currentDir, results) {
   }
 }
 async function readSourceMapContent(absolutePath) {
-  return fs2.readFile(absolutePath, "utf-8");
+  return fs3.readFile(absolutePath, "utf-8");
 }
 async function collectSourceMaps(buildDir) {
   const fileInfos = await discoverSourceMapFiles(buildDir);
@@ -16892,12 +16973,12 @@ async function uploadSourceMapsAuto(apiKey, endpoint, buildHash, maps, options)
   );
   return uploadSourceMaps(apiKey, endpoint, buildHash, maps);
 }
-var fs2, path2, crypto2, import_node_child_process, LARGE_FILE_WARNING_BYTES, PRESIGNED_THRESHOLD_BYTES, _blobClientLoader;
+var fs3, path3, crypto2, import_node_child_process, LARGE_FILE_WARNING_BYTES, PRESIGNED_THRESHOLD_BYTES, _blobClientLoader;
 var init_source_map_uploader = __esm({
   "src/source-map-uploader.ts"() {
     "use strict";
-    fs2 = __toESM(require("node:fs/promises"), 1);
-    path2 = __toESM(require("node:path"), 1);
+    fs3 = __toESM(require("node:fs/promises"), 1);
+    path3 = __toESM(require("node:path"), 1);
     crypto2 = __toESM(require("node:crypto"), 1);
     import_node_child_process = require("node:child_process");
     init_console_capture();
@@ -16934,6 +17015,7 @@ __export(src_exports, {
   performInit: () => performInit,
   readAnonKey: () => readAnonKey,
   readEnvVars: () => readEnvVars,
+  recordSideEffect: () => recordSideEffect,
   registerGlasstrace: () => registerGlasstrace,
   resolveConfig: () => resolveConfig,
   saveCachedConfig: () => saveCachedConfig,
@@ -17052,11 +17134,11 @@ var fsPathCache;
 async function loadFsPath() {
   if (fsPathCache !== void 0) return fsPathCache;
   try {
-    const [fs3, path3] = await Promise.all([
+    const [fs4, path4] = await Promise.all([
       import("node:fs/promises"),
       import("node:path")
     ]);
-    fsPathCache = { fs: fs3, path: path3 };
+    fsPathCache = { fs: fs4, path: path4 };
     return fsPathCache;
   } catch {
     fsPathCache = null;
@@ -17577,35 +17659,35 @@ function atomicWriteFileSync(targetPath, payload, options = {}) {
 function atomicWriteFileSyncWithTmp(targetPath, tmpPath, payload, options = {}) {
   const mode = options.mode ?? 384;
   const encoding = options.encoding ?? "utf-8";
-  const fs3 = loadFsSync();
+  const fs4 = loadFsSync();
   let fd = null;
   try {
     if (typeof payload === "string") {
-      fs3.writeFileSync(tmpPath, payload, { encoding, mode });
+      fs4.writeFileSync(tmpPath, payload, { encoding, mode });
     } else {
-      fs3.writeFileSync(tmpPath, payload, { mode });
+      fs4.writeFileSync(tmpPath, payload, { mode });
     }
-    fs3.chmodSync(tmpPath, mode);
-    fd = fs3.openSync(tmpPath, "r");
-    fs3.fsyncSync(fd);
-    fs3.closeSync(fd);
+    fs4.chmodSync(tmpPath, mode);
+    fd = fs4.openSync(tmpPath, "r");
+    fs4.fsyncSync(fd);
+    fs4.closeSync(fd);
     fd = null;
-    fs3.renameSync(tmpPath, targetPath);
+    fs4.renameSync(tmpPath, targetPath);
   } catch (err) {
     if (fd !== null) {
       try {
-        fs3.closeSync(fd);
+        fs4.closeSync(fd);
       } catch {
       }
     }
-    removeTmpResidueSync(fs3, tmpPath);
+    removeTmpResidueSync(fs4, tmpPath);
     throw err;
   }
-  fsyncParentDirSyncWithFs(targetPath, fs3);
+  fsyncParentDirSyncWithFs(targetPath, fs4);
 }
-function removeTmpResidueSync(fs3, tmpPath) {
+function removeTmpResidueSync(fs4, tmpPath) {
   try {
-    fs3.unlinkSync(tmpPath);
+    fs4.unlinkSync(tmpPath);
     return;
   } catch (err) {
     const code = errnoCodeOf(err);
@@ -17614,16 +17696,16 @@ function removeTmpResidueSync(fs3, tmpPath) {
     }
   }
   try {
-    fs3.rmdirSync(tmpPath);
+    fs4.rmdirSync(tmpPath);
   } catch {
   }
 }
-function fsyncParentDirSyncWithFs(targetPath, fs3) {
+function fsyncParentDirSyncWithFs(targetPath, fs4) {
   const parent = parentDir(targetPath);
   let fd = null;
   try {
-    fd = fs3.openSync(parent, "r");
-    fs3.fsyncSync(fd);
+    fd = fs4.openSync(parent, "r");
+    fs4.fsyncSync(fd);
   } catch (err) {
     const code = errnoCodeOf(err);
     if (code !== void 0 && PARENT_FSYNC_SWALLOWED_CODES.has(code)) {
@@ -17633,7 +17715,7 @@ function fsyncParentDirSyncWithFs(targetPath, fs3) {
   } finally {
     if (fd !== null) {
       try {
-        fs3.closeSync(fd);
+        fs4.closeSync(fd);
       } catch {
       }
     }
@@ -17654,11 +17736,11 @@ var fsPathCache2;
 async function loadFsPath2() {
   if (fsPathCache2 !== void 0) return fsPathCache2;
   try {
-    const [fs3, path3] = await Promise.all([
+    const [fs4, path4] = await Promise.all([
       import("node:fs/promises"),
       import("node:path")
     ]);
-    fsPathCache2 = { fs: fs3, path: path3 };
+    fsPathCache2 = { fs: fs4, path: path4 };
     return fsPathCache2;
   } catch {
     fsPathCache2 = null;
@@ -17944,11 +18026,11 @@ var fsPathAsyncCache;
 async function loadFsPathAsync() {
   if (fsPathAsyncCache !== void 0) return fsPathAsyncCache;
   try {
-    const [fs3, path3] = await Promise.all([
+    const [fs4, path4] = await Promise.all([
       import("node:fs/promises"),
       import("node:path")
     ]);
-    fsPathAsyncCache = { fs: fs3, path: path3 };
+    fsPathAsyncCache = { fs: fs4, path: path4 };
     return fsPathAsyncCache;
   } catch {
     fsPathAsyncCache = null;
@@ -17957,9 +18039,9 @@ async function loadFsPathAsync() {
 }
 function loadFsSyncOrNull() {
   try {
-    const fs3 = require("node:fs");
-    const path3 = require("node:path");
-    return { readFileSync: fs3.readFileSync, join: path3.join };
+    const fs4 = require("node:fs");
+    const path4 = require("node:path");
+    return { readFileSync: fs4.readFileSync, join: path4.join };
   } catch {
     return null;
   }
@@ -20427,7 +20509,7 @@ function appendRootPathToUrlIfNeeded(url2) {
     return void 0;
   }
 }
-function appendResourcePathToUrl(url2, path3) {
+function appendResourcePathToUrl(url2, path4) {
   try {
     new URL(url2);
   } catch {
@@ -20437,11 +20519,11 @@ function appendResourcePathToUrl(url2, path3) {
   if (!url2.endsWith("/")) {
     url2 = url2 + "/";
   }
-  url2 += path3;
+  url2 += path4;
   try {
     new URL(url2);
   } catch {
-    diag2.warn(`Configuration: Provided URL appended with '${path3}' is not a valid URL, using 'undefined' instead of '${url2}'`);
+    diag2.warn(`Configuration: Provided URL appended with '${path4}' is not a valid URL, using 'undefined' instead of '${url2}'`);
     return void 0;
   }
   return url2;
@@ -22647,6 +22729,171 @@ function writeStateNow() {
   }
 }
 
+// src/agent-detection/upgrade-notice.ts
+var fs2 = __toESM(require("node:fs"), 1);
+var path2 = __toESM(require("node:path"), 1);
+
+// src/agent-detection/inject.ts
+var HTML_START_RE = /^<!--\s*glasstrace:mcp:start(?:\s+v=([^\s>]+))?\s*-->$/;
+var HTML_END = "<!-- glasstrace:mcp:end -->";
+var HASH_START_RE = /^#\s*glasstrace:mcp:start(?:\s+v=(\S+))?$/;
+var HASH_END = "# glasstrace:mcp:end";
+function parseStartMarkerLine(line) {
+  const trimmed = line.trim();
+  const html = HTML_START_RE.exec(trimmed);
+  if (html !== null) {
+    return { kind: "html", stamp: html[1] ?? null };
+  }
+  const hash2 = HASH_START_RE.exec(trimmed);
+  if (hash2 !== null) {
+    return { kind: "hash", stamp: hash2[1] ?? null };
+  }
+  return null;
+}
+function isEndMarker(line) {
+  const trimmed = line.trim();
+  return trimmed === HTML_END || trimmed === HASH_END;
+}
+function isEndMarkerLine(line) {
+  return isEndMarker(line);
+}
+
+// src/agent-detection/upgrade-notice.ts
+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 stat2 = fs2.statSync(filePath);
+    if (!stat2.isFile()) return "absent";
+    if (stat2.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) + "...";
@@ -22675,9 +22922,13 @@ function registerGlasstrace(options) {
       return;
     }
     setCoreState(CoreState.REGISTERING);
+    maybeWarnStaleAgentInstructions({
+      projectRoot: process.cwd(),
+      sdkVersion: "1.5.0"
+    });
     startRuntimeStateWriter({
       projectRoot: process.cwd(),
-      sdkVersion: "1.3.9"
+      sdkVersion: "1.5.0"
     });
     const config2 = resolveConfig(options);
     if (config2.verbose) {
@@ -22844,8 +23095,8 @@ async function backgroundInit(config2, anonKeyForInit, generation) {
   if (config2.verbose) {
     console.info("[glasstrace] Background init firing.");
   }
-  const healthReport = collectHealthReport("1.3.9");
-  const initResult = await performInit(config2, anonKeyForInit, "1.3.9", healthReport);
+  const healthReport = collectHealthReport("1.5.0");
+  const initResult = await performInit(config2, anonKeyForInit, "1.5.0", healthReport);
   if (generation !== registrationGeneration) return;
   const currentState = getCoreState();
   if (currentState === CoreState.SHUTTING_DOWN || currentState === CoreState.SHUTDOWN) {
@@ -22868,7 +23119,7 @@ async function backgroundInit(config2, anonKeyForInit, generation) {
   }
   maybeInstallConsoleCapture();
   if (didLastInitSucceed()) {
-    startHeartbeat(config2, anonKeyForInit, "1.3.9", generation, (newApiKey, accountId) => {
+    startHeartbeat(config2, anonKeyForInit, "1.5.0", generation, (newApiKey, accountId) => {
       setAuthState(AuthState.CLAIMING);
       emitLifecycleEvent("auth:claim_started", { accountId });
       setResolvedApiKey(newApiKey);
@@ -23160,6 +23411,284 @@ function firstToken(value) {
   }
   return void 0;
 }
+
+// src/side-effect/allowlist.ts
+init_dist();
+var MAX_SIDE_EFFECT_OPERATION_LABEL_LENGTH = 96;
+var MAX_SIDE_EFFECT_FIELD_VALUE_LENGTH = 80;
+var MAX_SIDE_EFFECT_OPERATIONS_PER_SPAN = 5;
+var OPERATION_KIND_SET = new Set(
+  SIDE_EFFECT_OPERATION_KINDS
+);
+var SEMANTIC_FIELD_KEY_SET = new Set(
+  SIDE_EFFECT_SEMANTIC_FIELD_KEYS
+);
+var OPERATION_STATUS_SET = new Set(
+  SIDE_EFFECT_OPERATION_STATUSES
+);
+var OPERATION_PHASE_SET = new Set(
+  SIDE_EFFECT_OPERATION_PHASES
+);
+var OMISSION_REASON_SET = new Set(
+  SIDE_EFFECT_OMISSION_REASONS
+);
+var TOKEN_REGEX = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+var LOCALE_REGEX = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$/;
+var TIMEZONE_REGEX = /^(?:UTC|GMT|[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+){1,3})$/;
+var URL_SCHEME = /:\/\//;
+var URL_SCHEME_RELATIVE = /^\/\//;
+var EMAIL_LIKE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i;
+var QUERY_LIKE = /\?/;
+var FRAGMENT_LIKE = /#/;
+var HEADER_LIKE = /\b(authorization|set-cookie|cookie)\b\s*[:=]/i;
+var HEADER_TOKEN_LIKE = /\b(authorization|set-cookie|cookie)\b\s+\S+=/i;
+var BEARER_LIKE = /bearer\s+\S+/i;
+var TOKEN_KV_LIKE = /["']?(password|passwd|token|api[_-]?key|secret|client_secret)["']?\s*[:=]/i;
+var PROSE_LIKE = /[\r\n\t]|\s{2,}/;
+var UUID_LIKE = /[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/i;
+var GT_KEY_LIKE = /gt_(dev|anon|live)_[A-Za-z0-9_-]+/;
+function detectUnsafePattern(value) {
+  if (value.trim() !== value) return "raw_payload";
+  if (PROSE_LIKE.test(value)) return "raw_payload";
+  if (URL_SCHEME.test(value)) return "raw_payload";
+  if (URL_SCHEME_RELATIVE.test(value)) return "raw_payload";
+  if (QUERY_LIKE.test(value)) return "raw_payload";
+  if (FRAGMENT_LIKE.test(value)) return "raw_payload";
+  if (BEARER_LIKE.test(value)) return "secret";
+  if (HEADER_TOKEN_LIKE.test(value)) return "secret";
+  if (TOKEN_KV_LIKE.test(value)) return "secret";
+  if (HEADER_LIKE.test(value)) return "secret";
+  if (UUID_LIKE.test(value)) return "secret";
+  if (GT_KEY_LIKE.test(value)) return "secret";
+  if (EMAIL_LIKE.test(value)) return "pii";
+  return null;
+}
+function passesFieldValidator(key, value) {
+  if (key === "locale") return LOCALE_REGEX.test(value);
+  if (key === "timezone") return TIMEZONE_REGEX.test(value);
+  return TOKEN_REGEX.test(value);
+}
+function checkOperationLabel(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return { accepted: false, reason: "raw_payload" };
+  }
+  if (value.length > MAX_SIDE_EFFECT_OPERATION_LABEL_LENGTH) {
+    return { accepted: false, reason: "value_too_long" };
+  }
+  const unsafe = detectUnsafePattern(value);
+  if (unsafe) {
+    return { accepted: false, reason: unsafe };
+  }
+  if (!TOKEN_REGEX.test(value)) {
+    return { accepted: false, reason: "raw_payload" };
+  }
+  return { accepted: true, value };
+}
+function checkSemanticFieldValue(key, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return { accepted: false, reason: "raw_payload" };
+  }
+  if (value.length > MAX_SIDE_EFFECT_FIELD_VALUE_LENGTH) {
+    return { accepted: false, reason: "value_too_long" };
+  }
+  const unsafe = detectUnsafePattern(value);
+  if (unsafe) {
+    return { accepted: false, reason: unsafe };
+  }
+  if (!passesFieldValidator(key, value)) {
+    return { accepted: false, reason: "raw_payload" };
+  }
+  return { accepted: true, value };
+}
+function checkSemanticFieldKey(key) {
+  return typeof key === "string" && SEMANTIC_FIELD_KEY_SET.has(key);
+}
+function checkOperationKind(kind) {
+  return typeof kind === "string" && OPERATION_KIND_SET.has(kind);
+}
+function checkOperationStatus(status) {
+  return typeof status === "string" && OPERATION_STATUS_SET.has(status);
+}
+function checkOperationPhase(phase) {
+  return typeof phase === "string" && OPERATION_PHASE_SET.has(phase);
+}
+
+// src/side-effect/emit.ts
+init_esm();
+init_dist();
+var spanState = /* @__PURE__ */ new WeakMap();
+function getOrCreateState(span) {
+  let state = spanState.get(span);
+  if (!state) {
+    state = { operationsRecorded: 0, omissions: /* @__PURE__ */ new Map() };
+    spanState.set(span, state);
+  }
+  return state;
+}
+function getRecordingActiveSpan() {
+  let span;
+  try {
+    span = trace.getActiveSpan();
+  } catch {
+    return void 0;
+  }
+  if (!span) return void 0;
+  try {
+    if (typeof span.isRecording === "function" && !span.isRecording()) {
+      return void 0;
+    }
+  } catch {
+    return void 0;
+  }
+  return span;
+}
+function recordOmissionOnActiveSpan(reason) {
+  const span = getRecordingActiveSpan();
+  if (!span) return;
+  recordOmissionOnSpan(span, reason);
+}
+function recordOmissionOnSpan(span, reason) {
+  const state = getOrCreateState(span);
+  const previous = state.omissions.get(reason) ?? 0;
+  const next = previous + 1;
+  state.omissions.set(reason, next);
+  const attribute = OMISSION_ATTRIBUTE_BY_REASON[reason];
+  try {
+    span.setAttribute(attribute, next);
+  } catch {
+  }
+}
+var OMISSION_ATTRIBUTE_BY_REASON = {
+  pii: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_OMITTED_PII,
+  secret: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_OMITTED_SECRET,
+  raw_payload: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_OMITTED_RAW_PAYLOAD,
+  unsupported_key: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_OMITTED_UNSUPPORTED_KEY,
+  value_too_long: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_OMITTED_VALUE_TOO_LONG,
+  not_emitted: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_OMITTED_NOT_EMITTED,
+  capture_disabled: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_OMITTED_CAPTURE_DISABLED
+};
+var FIELD_ATTRIBUTE_BY_KEY = {
+  templateKey: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_FIELD_TEMPLATE_KEY,
+  providerOperation: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_FIELD_PROVIDER_OPERATION,
+  role: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_FIELD_ROLE,
+  locale: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_FIELD_LOCALE,
+  timezone: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_FIELD_TIMEZONE,
+  status: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_FIELD_STATUS,
+  phase: GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_FIELD_PHASE
+};
+function attachOperation(input) {
+  const span = getRecordingActiveSpan();
+  if (!span) return { kind: "no_active_span" };
+  const state = getOrCreateState(span);
+  if (state.operationsRecorded >= MAX_SIDE_EFFECT_OPERATIONS_PER_SPAN) {
+    return { kind: "over_budget", span };
+  }
+  state.operationsRecorded += 1;
+  try {
+    span.setAttribute(GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_KIND, input.kind);
+    span.setAttribute(
+      GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_OPERATION,
+      input.operation
+    );
+    if (input.status !== void 0) {
+      span.setAttribute(
+        GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_STATUS,
+        input.status
+      );
+    }
+    if (input.phase !== void 0) {
+      span.setAttribute(
+        GLASSTRACE_ATTRIBUTE_NAMES.SIDE_EFFECT_PHASE,
+        input.phase
+      );
+    }
+  } catch {
+  }
+  return { kind: "attached", span };
+}
+function attachField(span, key, value) {
+  const attribute = FIELD_ATTRIBUTE_BY_KEY[key];
+  try {
+    span.setAttribute(attribute, value);
+  } catch {
+  }
+}
+function recordOmission(span, reason) {
+  recordOmissionOnSpan(span, reason);
+}
+
+// src/side-effect/index.ts
+function recordSideEffect(input) {
+  try {
+    runRecordSideEffect(input);
+  } catch {
+  }
+}
+function runRecordSideEffect(input) {
+  if (!input || typeof input !== "object") return;
+  let captureEnabled;
+  try {
+    captureEnabled = getActiveConfig().sideEffectEvidence === true;
+  } catch {
+    captureEnabled = false;
+  }
+  if (!captureEnabled) {
+    return;
+  }
+  const candidate = input;
+  if (!checkOperationKind(candidate.kind)) {
+    return;
+  }
+  const labelOutcome = checkOperationLabel(candidate.operation);
+  if (!labelOutcome.accepted) {
+    recordOmissionOnActiveSpan(labelOutcome.reason);
+    return;
+  }
+  let acceptedStatus;
+  if (candidate.status !== void 0) {
+    if (checkOperationStatus(candidate.status)) {
+      acceptedStatus = candidate.status;
+    } else {
+      recordOmissionOnActiveSpan("unsupported_key");
+    }
+  }
+  let acceptedPhase;
+  if (candidate.phase !== void 0) {
+    if (checkOperationPhase(candidate.phase)) {
+      acceptedPhase = candidate.phase;
+    } else {
+      recordOmissionOnActiveSpan("unsupported_key");
+    }
+  }
+  const outcome = attachOperation({
+    kind: candidate.kind,
+    operation: labelOutcome.value,
+    status: acceptedStatus,
+    phase: acceptedPhase
+  });
+  if (outcome.kind === "no_active_span") {
+    return;
+  }
+  if (outcome.kind === "over_budget") {
+    recordOmission(outcome.span, "value_too_long");
+    return;
+  }
+  const fields = candidate.fields;
+  if (fields && typeof fields === "object") {
+    for (const [rawKey, rawValue] of Object.entries(fields)) {
+      if (!checkSemanticFieldKey(rawKey)) {
+        recordOmission(outcome.span, "unsupported_key");
+        continue;
+      }
+      const valueOutcome = checkSemanticFieldValue(rawKey, rawValue);
+      if (!valueOutcome.accepted) {
+        recordOmission(outcome.span, valueOutcome.reason);
+        continue;
+      }
+      attachField(outcome.span, rawKey, valueOutcome.value);
+    }
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   GlasstraceExporter,
@@ -23185,6 +23714,7 @@ function firstToken(value) {
   performInit,
   readAnonKey,
   readEnvVars,
+  recordSideEffect,
   registerGlasstrace,
   resolveConfig,
   saveCachedConfig,