autotel 3.6.0 → 4.0.0

package/dist/yaml-config.js

@@ -1,8 +1,227 @@
-export { hasYamlConfig, loadYamlConfig, loadYamlConfigFromFile } from './chunk-CMHVQR6P.js';
-import './chunk-Q4EULJQY.js';
-import './chunk-DPSA4QLA.js';
-import './chunk-55ER2KD5.js';
-import './chunk-J5QENANM.js';
-import './chunk-HA2WBOGQ.js';
-//# sourceMappingURL=yaml-config.js.map
+import { AdaptiveSampler, AlwaysSampler, NeverSampler, RandomSampler } from "./sampling.js";
+import { t as requireModule } from "./node-require-Db1oDpLj.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+//#region src/yaml-config.ts
+/**
+* YAML configuration loader for autotel
+*
+* Supports:
+* - Auto-discovery of autotel.yaml in cwd
+* - AUTOTEL_CONFIG_FILE env var override
+* - Environment variable substitution: ${env:VAR} and ${env:VAR:-default}
+*
+* @example Auto-discovery
+* ```yaml
+* # autotel.yaml in project root
+* service:
+*   name: my-service
+* exporter:
+*   endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}
+* ```
+*
+* @example Explicit path
+* ```bash
+* AUTOTEL_CONFIG_FILE=./config/otel.yaml tsx --import autotel/auto src/index.ts
+* ```
+*/
+/**
+* Lazy-load yaml parser (optional peer dependency)
+* Only loads when a YAML config file is actually found
+*/
+function loadYamlParser() {
+	try {
+		return requireModule("yaml").parse;
+	} catch {
+		throw new Error("YAML parser not found. Install with: pnpm add yaml");
+	}
+}
+/**
+* Environment variable substitution regex
+* Matches ${env:VAR_NAME} and ${env:VAR_NAME:-default}
+*/
+const ENV_VAR_PATTERN = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+/**
+* Substitute ${env:VAR} and ${env:VAR:-default} in a string
+*
+* @param value - String potentially containing env var references
+* @returns String with env vars substituted
+*
+* @example
+* substituteEnvVars('${env:NODE_ENV:-development}')
+* // Returns 'production' if NODE_ENV=production, else 'development'
+*/
+function substituteEnvVars(value) {
+	return value.replaceAll(ENV_VAR_PATTERN, (_match, varName, defaultValue) => {
+		const envValue = process.env[varName];
+		if (envValue !== void 0) return envValue;
+		if (defaultValue !== void 0) return defaultValue;
+		console.warn(`[autotel] Environment variable ${varName} not set and no default provided`);
+		return "";
+	});
+}
+/**
+* Recursively substitute env vars in an object
+*
+* @param obj - Object to process
+* @returns Object with all string values having env vars substituted
+*/
+function substituteEnvVarsDeep(obj) {
+	if (typeof obj === "string") return substituteEnvVars(obj);
+	if (Array.isArray(obj)) return obj.map((item) => substituteEnvVarsDeep(item));
+	if (obj && typeof obj === "object") {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) result[key] = substituteEnvVarsDeep(value);
+		return result;
+	}
+	return obj;
+}
+/**
+* Find YAML config file path
+*
+* Priority:
+* 1. AUTOTEL_CONFIG_FILE env var (explicit path)
+* 2. autotel.yaml in cwd (convention)
+* 3. autotel.yml in cwd (alternative extension)
+*
+* @returns File path if found, null otherwise
+*/
+function findConfigFile() {
+	const envPath = process.env.AUTOTEL_CONFIG_FILE;
+	if (envPath) {
+		const resolved = path.resolve(envPath);
+		if (existsSync(resolved)) return resolved;
+		console.warn(`[autotel] Config file not found: ${envPath}`);
+		return null;
+	}
+	const conventionPath = path.resolve(process.cwd(), "autotel.yaml");
+	if (existsSync(conventionPath)) return conventionPath;
+	const altPath = path.resolve(process.cwd(), "autotel.yml");
+	if (existsSync(altPath)) return altPath;
+	return null;
+}
+/**
+* Convert YAML config structure to AutotelConfig
+*
+* @param yaml - Parsed and env-substituted YAML config
+* @returns Partial AutotelConfig ready for merging
+*/
+function yamlToAutotelConfig(yaml) {
+	const config = {};
+	if (yaml.service?.name) config.service = yaml.service.name;
+	if (yaml.service?.version) config.version = yaml.service.version;
+	if (yaml.service?.environment) config.environment = yaml.service.environment;
+	if (yaml.exporter?.endpoint) config.endpoint = yaml.exporter.endpoint;
+	if (yaml.exporter?.protocol) config.protocol = yaml.exporter.protocol;
+	if (yaml.exporter?.headers) config.headers = yaml.exporter.headers;
+	if (yaml.resource) config.resourceAttributes = yaml.resource;
+	if (yaml.autoInstrumentations) config.autoInstrumentations = yaml.autoInstrumentations;
+	if (yaml.debug !== void 0) config.debug = yaml.debug;
+	if (yaml.sampling?.preset) {
+		warnOnIgnoredPresetOverrides(yaml.sampling);
+		config.sampling = yaml.sampling.preset;
+	} else {
+		const sampler = createSamplerFromYaml(yaml.sampling);
+		if (sampler) config.sampler = sampler;
+	}
+	return config;
+}
+function createSamplerFromYaml(sampling) {
+	if (!sampling) return void 0;
+	if (sampling.preset) return void 0;
+	const type = sampling.type ?? "adaptive";
+	try {
+		switch (type) {
+			case "adaptive": return new AdaptiveSampler({
+				baselineSampleRate: sampling.baseline_rate,
+				alwaysSampleErrors: sampling.always_sample_errors,
+				alwaysSampleSlow: sampling.always_sample_slow,
+				slowThresholdMs: sampling.slow_threshold_ms
+			});
+			case "always_on": return new AlwaysSampler();
+			case "always_off": return new NeverSampler();
+			case "ratio":
+				if (sampling.ratio === void 0) {
+					console.warn("[autotel] sampling.ratio missing in YAML sampling config. Falling back to adaptive sampler.");
+					return new AdaptiveSampler();
+				}
+				return new RandomSampler(sampling.ratio);
+			default:
+				console.warn(`[autotel] Unknown sampling type "${type}" in YAML config. Falling back to defaults.`);
+				return;
+		}
+	} catch (error) {
+		console.warn(`[autotel] Failed to configure sampling from YAML: ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+}
+function warnOnIgnoredPresetOverrides(sampling) {
+	const ignoredFields = [
+		"type",
+		"ratio",
+		"baseline_rate",
+		"always_sample_errors",
+		"always_sample_slow",
+		"slow_threshold_ms"
+	].filter((field) => sampling[field] !== void 0);
+	if (ignoredFields.length === 0) return;
+	console.warn(`[autotel] sampling.preset="${sampling.preset}" ignores these YAML fields: ${ignoredFields.join(", ")}. Use the programmatic API with sampler or samplingPresets.*(...) for tuned presets.`);
+}
+/**
+* Load and parse YAML config file (auto-discovery)
+*
+* Automatically finds and loads autotel.yaml or uses AUTOTEL_CONFIG_FILE.
+* Returns null if no config file found (not an error - YAML config is optional).
+*
+* @returns Partial AutotelConfig or null if no config file found
+*
+* @example
+* const yamlConfig = loadYamlConfig();
+* if (yamlConfig) {
+*   init({ ...yamlConfig, debug: true });
+* }
+*/
+function loadYamlConfig() {
+	const filePath = findConfigFile();
+	if (!filePath) return null;
+	try {
+		const content = readFileSync(filePath, "utf8");
+		return yamlToAutotelConfig(substituteEnvVarsDeep(loadYamlParser()(content)));
+	} catch (error) {
+		console.error(`[autotel] Failed to load YAML config from ${filePath}:`, error);
+		return null;
+	}
+}
+/**
+* Load YAML config from a specific file path
+*
+* Unlike loadYamlConfig(), this throws if the file cannot be read.
+*
+* @param filePath - Path to YAML config file
+* @returns Partial AutotelConfig
+* @throws Error if file cannot be read or parsed
+*
+* @example
+* import { loadYamlConfigFromFile } from 'autotel/yaml';
+* import { init } from 'autotel';
+*
+* const config = loadYamlConfigFromFile('./config/otel.yaml');
+* init({ ...config, debug: true });
+*/
+function loadYamlConfigFromFile(filePath) {
+	const content = readFileSync(path.resolve(filePath), "utf8");
+	return yamlToAutotelConfig(substituteEnvVarsDeep(loadYamlParser()(content)));
+}
+/**
+* Check if a YAML config file exists (without loading it)
+*
+* @returns true if a config file would be found by loadYamlConfig()
+*/
+function hasYamlConfig() {
+	return findConfigFile() !== null;
+}
+
+//#endregion
+export { hasYamlConfig, loadYamlConfig, loadYamlConfigFromFile };
 //# sourceMappingURL=yaml-config.js.map

package/dist/yaml-config.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"yaml-config.js"}
+{"version":3,"file":"yaml-config.js","names":[],"sources":["../src/yaml-config.ts"],"sourcesContent":["/**\n * YAML configuration loader for autotel\n *\n * Supports:\n * - Auto-discovery of autotel.yaml in cwd\n * - AUTOTEL_CONFIG_FILE env var override\n * - Environment variable substitution: ${env:VAR} and ${env:VAR:-default}\n *\n * @example Auto-discovery\n * ```yaml\n * # autotel.yaml in project root\n * service:\n *   name: my-service\n * exporter:\n *   endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}\n * ```\n *\n * @example Explicit path\n * ```bash\n * AUTOTEL_CONFIG_FILE=./config/otel.yaml tsx --import autotel/auto src/index.ts\n * ```\n */\n\nimport { readFileSync, existsSync } from 'node:fs';\nimport path from 'node:path';\nimport type { AutotelConfig } from './init';\nimport {\n  AdaptiveSampler,\n  AlwaysSampler,\n  NeverSampler,\n  RandomSampler,\n  type SamplingPreset,\n} from './sampling';\n\n/**\n * Lazy-load yaml parser (optional peer dependency)\n * Only loads when a YAML config file is actually found\n */\nimport { requireModule } from './node-require';\n\nfunction loadYamlParser(): (content: string) => unknown {\n  try {\n    const mod = requireModule<{ parse: (content: string) => unknown }>('yaml');\n    return mod.parse;\n  } catch {\n    throw new Error('YAML parser not found. Install with: pnpm add yaml');\n  }\n}\n\n/**\n * YAML config structure\n * Maps to AutotelConfig with user-friendly naming\n */\nexport interface YamlConfig {\n  service?: {\n    name?: string;\n    version?: string;\n    environment?: string;\n  };\n  exporter?: {\n    endpoint?: string;\n    protocol?: 'http' | 'grpc';\n    headers?: Record<string, string>;\n  };\n  resource?: Record<string, string | number | boolean>;\n  sampling?: {\n    preset?: SamplingPreset;\n    type?: 'adaptive' | 'always_on' | 'always_off' | 'ratio';\n    ratio?: number;\n    baseline_rate?: number;\n    always_sample_errors?: boolean;\n    always_sample_slow?: boolean;\n    slow_threshold_ms?: number;\n  };\n  autoInstrumentations?: string[] | Record<string, { enabled?: boolean }>;\n  debug?: boolean;\n}\n\n/**\n * Environment variable substitution regex\n * Matches ${env:VAR_NAME} and ${env:VAR_NAME:-default}\n */\nconst ENV_VAR_PATTERN = /\\$\\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\\}/g;\n\n/**\n * Substitute ${env:VAR} and ${env:VAR:-default} in a string\n *\n * @param value - String potentially containing env var references\n * @returns String with env vars substituted\n *\n * @example\n * substituteEnvVars('${env:NODE_ENV:-development}')\n * // Returns 'production' if NODE_ENV=production, else 'development'\n */\nfunction substituteEnvVars(value: string): string {\n  return value.replaceAll(\n    ENV_VAR_PATTERN,\n    (_match, varName: string, defaultValue?: string) => {\n      const envValue = process.env[varName];\n      if (envValue !== undefined) return envValue;\n      if (defaultValue !== undefined) return defaultValue;\n      console.warn(\n        `[autotel] Environment variable ${varName} not set and no default provided`,\n      );\n      return '';\n    },\n  );\n}\n\n/**\n * Recursively substitute env vars in an object\n *\n * @param obj - Object to process\n * @returns Object with all string values having env vars substituted\n */\nfunction substituteEnvVarsDeep(obj: unknown): unknown {\n  if (typeof obj === 'string') {\n    return substituteEnvVars(obj);\n  }\n  if (Array.isArray(obj)) {\n    return obj.map((item) => substituteEnvVarsDeep(item));\n  }\n  if (obj && typeof obj === 'object') {\n    const result: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(obj)) {\n      result[key] = substituteEnvVarsDeep(value);\n    }\n    return result;\n  }\n  return obj;\n}\n\n/**\n * Find YAML config file path\n *\n * Priority:\n * 1. AUTOTEL_CONFIG_FILE env var (explicit path)\n * 2. autotel.yaml in cwd (convention)\n * 3. autotel.yml in cwd (alternative extension)\n *\n * @returns File path if found, null otherwise\n */\nfunction findConfigFile(): string | null {\n  // Check env var first (explicit takes priority)\n  const envPath = process.env.AUTOTEL_CONFIG_FILE;\n  if (envPath) {\n    const resolved = path.resolve(envPath);\n    if (existsSync(resolved)) return resolved;\n    console.warn(`[autotel] Config file not found: ${envPath}`);\n    return null;\n  }\n\n  // Auto-discover autotel.yaml in cwd\n  const conventionPath = path.resolve(process.cwd(), 'autotel.yaml');\n  if (existsSync(conventionPath)) return conventionPath;\n\n  // Also check .yml extension\n  const altPath = path.resolve(process.cwd(), 'autotel.yml');\n  if (existsSync(altPath)) return altPath;\n\n  return null;\n}\n\n/**\n * Convert YAML config structure to AutotelConfig\n *\n * @param yaml - Parsed and env-substituted YAML config\n * @returns Partial AutotelConfig ready for merging\n */\nfunction yamlToAutotelConfig(yaml: YamlConfig): Partial<AutotelConfig> {\n  const config: Partial<AutotelConfig> = {};\n\n  // Service configuration\n  if (yaml.service?.name) config.service = yaml.service.name;\n  if (yaml.service?.version) config.version = yaml.service.version;\n  if (yaml.service?.environment) config.environment = yaml.service.environment;\n\n  // Exporter configuration\n  if (yaml.exporter?.endpoint) config.endpoint = yaml.exporter.endpoint;\n  if (yaml.exporter?.protocol) config.protocol = yaml.exporter.protocol;\n  if (yaml.exporter?.headers) config.headers = yaml.exporter.headers;\n\n  // Resource attributes (flattened)\n  if (yaml.resource) config.resourceAttributes = yaml.resource;\n\n  // Integrations\n  if (yaml.autoInstrumentations)\n    config.autoInstrumentations = yaml.autoInstrumentations;\n\n  // Debug mode\n  if (yaml.debug !== undefined) config.debug = yaml.debug;\n\n  // Sampling configuration\n  if (yaml.sampling?.preset) {\n    warnOnIgnoredPresetOverrides(yaml.sampling);\n    config.sampling = yaml.sampling.preset;\n  } else {\n    const sampler = createSamplerFromYaml(yaml.sampling);\n    if (sampler) config.sampler = sampler;\n  }\n\n  return config;\n}\n\nfunction createSamplerFromYaml(\n  sampling?: YamlConfig['sampling'],\n): AutotelConfig['sampler'] {\n  if (!sampling) return undefined;\n  if (sampling.preset) return undefined;\n\n  const type = sampling.type ?? 'adaptive';\n\n  try {\n    switch (type) {\n      case 'adaptive': {\n        return new AdaptiveSampler({\n          baselineSampleRate: sampling.baseline_rate,\n          alwaysSampleErrors: sampling.always_sample_errors,\n          alwaysSampleSlow: sampling.always_sample_slow,\n          slowThresholdMs: sampling.slow_threshold_ms,\n        });\n      }\n      case 'always_on': {\n        return new AlwaysSampler();\n      }\n      case 'always_off': {\n        return new NeverSampler();\n      }\n      case 'ratio': {\n        if (sampling.ratio === undefined) {\n          console.warn(\n            '[autotel] sampling.ratio missing in YAML sampling config. Falling back to adaptive sampler.',\n          );\n          return new AdaptiveSampler();\n        }\n        return new RandomSampler(sampling.ratio);\n      }\n      default: {\n        console.warn(\n          `[autotel] Unknown sampling type \"${type}\" in YAML config. Falling back to defaults.`,\n        );\n        return undefined;\n      }\n    }\n  } catch (error) {\n    console.warn(\n      `[autotel] Failed to configure sampling from YAML: ${error instanceof Error ? error.message : String(error)}`,\n    );\n    return undefined;\n  }\n}\n\nfunction warnOnIgnoredPresetOverrides(\n  sampling: NonNullable<YamlConfig['sampling']>,\n): void {\n  const ignoredFields = [\n    'type',\n    'ratio',\n    'baseline_rate',\n    'always_sample_errors',\n    'always_sample_slow',\n    'slow_threshold_ms',\n  ].filter((field) => sampling[field as keyof typeof sampling] !== undefined);\n\n  if (ignoredFields.length === 0) {\n    return;\n  }\n\n  console.warn(\n    `[autotel] sampling.preset=\"${sampling.preset}\" ignores these YAML fields: ${ignoredFields.join(', ')}. ` +\n      'Use the programmatic API with sampler or samplingPresets.*(...) for tuned presets.',\n  );\n}\n\n/**\n * Load and parse YAML config file (auto-discovery)\n *\n * Automatically finds and loads autotel.yaml or uses AUTOTEL_CONFIG_FILE.\n * Returns null if no config file found (not an error - YAML config is optional).\n *\n * @returns Partial AutotelConfig or null if no config file found\n *\n * @example\n * const yamlConfig = loadYamlConfig();\n * if (yamlConfig) {\n *   init({ ...yamlConfig, debug: true });\n * }\n */\nexport function loadYamlConfig(): Partial<AutotelConfig> | null {\n  const filePath = findConfigFile();\n  if (!filePath) return null;\n\n  try {\n    const content = readFileSync(filePath, 'utf8');\n    const parseYaml = loadYamlParser();\n    const rawYaml = parseYaml(content) as YamlConfig;\n    const substituted = substituteEnvVarsDeep(rawYaml) as YamlConfig;\n    return yamlToAutotelConfig(substituted);\n  } catch (error) {\n    console.error(\n      `[autotel] Failed to load YAML config from ${filePath}:`,\n      error,\n    );\n    return null;\n  }\n}\n\n/**\n * Load YAML config from a specific file path\n *\n * Unlike loadYamlConfig(), this throws if the file cannot be read.\n *\n * @param filePath - Path to YAML config file\n * @returns Partial AutotelConfig\n * @throws Error if file cannot be read or parsed\n *\n * @example\n * import { loadYamlConfigFromFile } from 'autotel/yaml';\n * import { init } from 'autotel';\n *\n * const config = loadYamlConfigFromFile('./config/otel.yaml');\n * init({ ...config, debug: true });\n */\nexport function loadYamlConfigFromFile(\n  filePath: string,\n): Partial<AutotelConfig> {\n  const resolved = path.resolve(filePath);\n  const content = readFileSync(resolved, 'utf8');\n  const parseYaml = loadYamlParser();\n  const rawYaml = parseYaml(content) as YamlConfig;\n  const substituted = substituteEnvVarsDeep(rawYaml) as YamlConfig;\n  return yamlToAutotelConfig(substituted);\n}\n\n/**\n * Check if a YAML config file exists (without loading it)\n *\n * @returns true if a config file would be found by loadYamlConfig()\n */\nexport function hasYamlConfig(): boolean {\n  return findConfigFile() !== null;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "3.6.0",
+  "version": "4.0.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -355,7 +355,7 @@
     "pino": "^10.3.1",
     "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "tsup": "^8.5.1",
+    "tsdown": "^0.22.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.1",
@@ -375,9 +375,9 @@
   },
   "homepage": "https://github.com/jagreehal/autotel#readme",
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "ci": "npm run build && npm run check-format && npm run check-exports && npm run lint && npm run test",
-    "dev": "tsup --watch",
+    "dev": "tsdown --watch",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "format": "prettier --write .",

package/skills/analyze-traces/SKILL.md

@@ -90,7 +90,7 @@ Key conventions to recognise:
    - **Sequential awaits that should be parallel** — sibling spans run end-to-end instead of overlapping.
    - **N+1 queries** — many short same-named spans (`SELECT * FROM …`) under one parent.
    - **Cold starts** — `faas.coldstart=true` in Workers or Lambda.
-   - **Tool retries** — gen-ai spans with `gen_ai.response.finish_reason = error` followed by another call.
+   - **Tool retries** — gen-ai spans with `gen_ai.response.finish_reasons` containing `error` followed by another call.
 
 ### "Follow this user across services"
 
@@ -137,21 +137,23 @@ init({ service: 'my-app', debug: 'pretty', spanDumpPath: '.autotel/spans' });
 
 LLM calls produce a parent span (kind `CLIENT`) with children for each tool call:
 
-| Attribute                                                  | Meaning                                  |
-| ---------------------------------------------------------- | ---------------------------------------- |
-| `gen_ai.system`                                            | Provider (`openai`, `anthropic`, …)      |
-| `gen_ai.request.model`                                     | Model id                                 |
-| `gen_ai.usage.input_tokens` / `output_tokens`              | Token count                              |
-| `gen_ai.usage.cache_read_tokens` / `cache_creation_tokens` | Cache hits                               |
-| `gen_ai.response.finish_reason`                            | `stop`, `tool_calls`, `length`, `error`  |
-| `gen_ai.tool.name`                                         | Tool invoked (on tool-call child spans)  |
-| `gen_ai.cost.usd`                                          | Estimated cost (if pricing map provided) |
+| Attribute                                                              | Meaning                                  |
+| ---------------------------------------------------------------------- | ---------------------------------------- |
+| `gen_ai.provider.name` (legacy: `gen_ai.system`)                       | Provider (`openai`, `anthropic`, …)      |
+| `gen_ai.request.model`                                                 | Model id                                 |
+| `gen_ai.usage.input_tokens` / `output_tokens`                          | Token count                              |
+| `gen_ai.usage.cache_read.input_tokens` / `cache_creation.input_tokens` | Cache hits                               |
+| `gen_ai.response.finish_reasons`                                       | `stop`, `tool_calls`, `length`, `error`  |
+| `gen_ai.tool.name`                                                     | Tool invoked (on tool-call child spans)  |
+| `gen_ai.usage.cost.usd`                                                | Estimated cost (if pricing map provided) |
+
+These canonical `gen_ai.*` attributes are emitted by the `autotel-genai` package (third-party instrumentations may still emit the deprecated `gen_ai.system`).
 
 Common findings:
 
-- High `gen_ai.usage.input_tokens` with low `cache_read_tokens` → enable prompt caching.
+- High `gen_ai.usage.input_tokens` with low `gen_ai.usage.cache_read.input_tokens` → enable prompt caching.
 - Many sequential tool-call spans → consider parallel tool calls if the model supports it.
-- `gen_ai.response.finish_reason = length` → bump `max_tokens`.
+- `gen_ai.response.finish_reasons` contains `length` → bump `max_tokens`.
 
 ## When the trace is missing
 

package/skills/review-otel-patterns/SKILL.md

@@ -385,7 +385,9 @@ Compose them at build time with `composeSpanProcessors([...])` — no boilerplat
 
 ## AI SDK integration (gen-ai semantic conventions)
 
-autotel implements the **OTel gen-ai semantic conventions** out of the box. Token usage, tool calls, model info, latency, cost — captured as standard attributes (`gen_ai.usage.input_tokens`, `gen_ai.tool.name`, `gen_ai.response.finish_reason`, …) so any backend that understands OTel can render LLM telemetry without custom mapping.
+autotel implements the **OTel gen-ai semantic conventions** out of the box. Token usage, tool calls, model info, latency, cost — captured as standard attributes (`gen_ai.usage.input_tokens`, `gen_ai.tool.name`, `gen_ai.response.finish_reasons`, …) so any backend that understands OTel can render LLM telemetry without custom mapping.
+
+> Node.js apps get the same canonical `gen_ai.*` conventions (plus cost, metric views, and agent governance) from the `autotel-genai` package — `traceGenAI` / `recordGenAiUsage` from `autotel-genai/trace` and `genAiMetricViews` from `autotel-genai/metrics`. `withAiTelemetry` below is the edge-runtime entry point.
 
 ```typescript
 import { trace } from 'autotel';
@@ -402,7 +404,7 @@ const handler = trace(async (req) => {
 });
 ```
 
-Captured attributes per call: `gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.{input,output,reasoning,cache_read}_tokens`, `gen_ai.response.finish_reason`, `gen_ai.response.id`, plus per-tool spans with `gen_ai.tool.name`, `gen_ai.tool.duration`. Cost estimation comes for free if you pass a pricing map to `withAiTelemetry`.
+Captured attributes per call: `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.usage.input_tokens` / `output_tokens` / `reasoning.output_tokens` / `cache_read.input_tokens`, `gen_ai.response.finish_reasons`, `gen_ai.response.id`, plus per-tool spans with `gen_ai.tool.name`. Cost estimation (`gen_ai.usage.cost.usd`) comes for free if you pass a pricing map to `withAiTelemetry`.
 
 Anti-patterns to detect:
 

package/skills/tune-sampling/SKILL.md

@@ -108,7 +108,12 @@ const tail = new TailSamplingProcessor({
 
     // 4. Always keep AI traces (rare + expensive — full visibility helps)
     if (
-      trace.spans.some((s) => typeof s.attributes['gen_ai.system'] === 'string')
+      trace.spans.some(
+        (s) =>
+          typeof s.attributes['gen_ai.provider.name'] === 'string' ||
+          // legacy: third-party instrumentations may still emit gen_ai.system
+          typeof s.attributes['gen_ai.system'] === 'string',
+      )
     )
       return true;
 
@@ -142,8 +147,8 @@ keep: (trace) => {
   const cost = trace.spans.reduce(
     (acc, s) =>
       acc +
-      (typeof s.attributes['gen_ai.cost.usd'] === 'number'
-        ? (s.attributes['gen_ai.cost.usd'] as number)
+      (typeof s.attributes['gen_ai.usage.cost.usd'] === 'number'
+        ? (s.attributes['gen_ai.usage.cost.usd'] as number)
         : 0),
     0,
   );

package/src/attributes/builders.ts

@@ -38,7 +38,6 @@ import {
   FaaSAttributes,
   FeatureFlagAttributes,
   MessagingAttributes,
-  GenAIAttributes,
   RPCAttributes,
   GraphQLAttributes,
   OTelAttributes,
@@ -477,25 +476,8 @@ export const attrs = {
     },
   },
 
-  genAI: {
-    system: (value: string) => ({ [GenAIAttributes.system]: value }),
-    requestModel: (value: string) => ({
-      [GenAIAttributes.requestModel]: value,
-    }),
-    responseModel: (value: string) => ({
-      [GenAIAttributes.responseModel]: value,
-    }),
-    operationName: (value: 'chat' | 'completion' | 'embedding') => ({
-      [GenAIAttributes.operationName]: value,
-    }),
-    usagePromptTokens: (value: number) => ({
-      [GenAIAttributes.usagePromptTokens]: value,
-    }),
-    usageCompletionTokens: (value: number) => ({
-      [GenAIAttributes.usageCompletionTokens]: value,
-    }),
-    provider: (value: string) => ({ [GenAIAttributes.provider]: value }),
-  },
+  // GenAI/LLM attribute builders moved to the `autotel-genai` package
+  // (canonical `gen_ai.*` semantic conventions).
 
   rpc: {
     system: (value: string) => ({ [RPCAttributes.system]: value }),

package/src/attributes/index.ts

@@ -70,7 +70,6 @@ export type {
   K8sAttrs,
   FaaSAttrs,
   ThreadAttrs,
-  GenAIAttrs,
   RPCAttrs,
   GraphQLAttrs,
   ClientAttrs,

package/src/attributes/registry.ts

@@ -155,15 +155,8 @@ export const MessagingAttributes = {
   consumerGroup: 'messaging.consumer.group' as const,
 } as const;
 
-export const GenAIAttributes = {
-  system: 'gen.ai.system' as const,
-  requestModel: 'gen.ai.request.model' as const,
-  responseModel: 'gen.ai.response.model' as const,
-  operationName: 'gen.ai.operation.name' as const,
-  usagePromptTokens: 'gen.ai.usage.prompt_tokens' as const,
-  usageCompletionTokens: 'gen.ai.usage.completion_tokens' as const,
-  provider: 'gen.ai.provider' as const,
-} as const;
+// GenAI attribute registry moved to the `autotel-genai` package, which uses the
+// canonical `gen_ai.*` namespace (these legacy `gen.ai.*` keys were non-spec).
 
 export const RPCAttributes = {
   system: 'rpc.system' as const,

package/src/attributes/types.ts

@@ -155,14 +155,6 @@ export interface ThreadAttrs {
   name?: string;
 }
 
-export interface GenAIAttrs {
-  system?: string;
-  requestModel?: string;
-  responseModel?: string;
-  operationName?: 'chat' | 'completion' | 'embedding';
-  provider?: string;
-}
-
 export interface RPCAttrs {
   system?: string;
   service?: string;

package/src/index.ts

@@ -136,6 +136,9 @@ export { flush, shutdown } from './shutdown';
 // Request logger
 export {
   getRequestLogger,
+  getRequestLoggerSafe,
+  createNoopRequestLogger,
+  hasRequestContext,
   runWithRequestContext,
   type RequestLogger,
   type RequestLogSnapshot,
@@ -238,43 +241,9 @@ export {
   createObservableGauge,
 } from './metric-helpers';
 
-// LLM-tuned histogram buckets — pass genAiMetricViews() to your
-// MeterProvider so gen_ai.* histograms have useful resolution.
-export {
-  GEN_AI_DURATION_BUCKETS_SECONDS,
-  GEN_AI_TOKEN_USAGE_BUCKETS,
-  GEN_AI_COST_USD_BUCKETS,
-  genAiMetricViews,
-  llmHistogramAdvice,
-} from './gen-ai-metrics';
-
-// OTel GenAI span event helpers — record prompt-sent / response-received
-// / retry / tool-call / stream-first-token as timestamped events aligned
-// with the published GenAI semantic conventions.
-export {
-  recordPromptSent,
-  recordResponseReceived,
-  recordRetry,
-  recordToolCall,
-  recordStreamFirstToken,
-  type PromptSentEvent,
-  type ResponseReceivedEvent,
-  type RetryEvent,
-  type ToolCallEvent,
-  type StreamFirstTokenEvent,
-} from './gen-ai-events';
-
-// Per-model LLM cost estimation — estimate USD cost from token usage and
-// record it as the gen_ai.usage.cost.usd span attribute.
-export {
-  estimateLLMCost,
-  recordLLMCost,
-  MODEL_PRICING,
-  GEN_AI_COST_ATTRIBUTE,
-  type ModelPricing,
-  type TokenUsage,
-  type EstimateCostOptions,
-} from './gen-ai-cost';
+// GenAI / LLM instrumentation (cost, token usage, metric buckets, span event
+// helpers, traceLLM) lives in the dedicated `autotel-genai` package — canonical
+// `gen_ai.*` semantic conventions. Core stays generic and AI-free.
 
 // Tracer helpers for custom spans
 export {
@@ -300,13 +269,11 @@ export {
   getAutotelTracer,
 } from './tracer-provider';
 
-// Semantic convention helpers
+// Semantic convention helpers (GenAI/LLM helpers moved to `autotel-genai`).
 export {
-  traceLLM,
   traceDB,
   traceHTTP,
   traceMessaging,
-  type LLMConfig,
   type DBConfig,
   type HTTPConfig,
   type MessagingConfig,
@@ -386,7 +353,6 @@ export {
   type K8sAttrs,
   type FaaSAttrs,
   type ThreadAttrs,
-  type GenAIAttrs,
   type RPCAttrs,
   type GraphQLAttrs,
   type ClientAttrs,

package/src/request-logger.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import { trace as otelTrace } from '@opentelemetry/api';
-import { getRequestLogger, runWithRequestContext } from './request-logger';
+import {
+  createNoopRequestLogger,
+  getRequestLogger,
+  getRequestLoggerSafe,
+  hasRequestContext,
+  runWithRequestContext,
+} from './request-logger';
 import type { TraceContext } from './trace-context';
 
 function createMockContext(): TraceContext {
@@ -491,3 +497,49 @@ describe('getRequestLogger', () => {
     });
   });
 });
+
+describe('best-effort helpers', () => {
+  it('hasRequestContext is false with no ctx, ALS, or active span', () => {
+    vi.spyOn(otelTrace, 'getActiveSpan').mockReturnValue(undefined);
+    expect(hasRequestContext()).toBe(false);
+  });
+
+  it('hasRequestContext is true when an explicit ctx is passed', () => {
+    vi.spyOn(otelTrace, 'getActiveSpan').mockReturnValue(undefined);
+    expect(hasRequestContext(createMockContext())).toBe(true);
+  });
+
+  it('hasRequestContext is true inside runWithRequestContext', () => {
+    vi.spyOn(otelTrace, 'getActiveSpan').mockReturnValue(undefined);
+    runWithRequestContext(createMockContext(), () => {
+      expect(hasRequestContext()).toBe(true);
+    });
+  });
+
+  it('getRequestLoggerSafe returns null when no context is available', () => {
+    vi.spyOn(otelTrace, 'getActiveSpan').mockReturnValue(undefined);
+    expect(getRequestLoggerSafe()).toBeNull();
+  });
+
+  it('getRequestLoggerSafe returns a working logger when ctx is provided', () => {
+    const ctx = createMockContext();
+    const log = getRequestLoggerSafe(ctx);
+    expect(log).not.toBeNull();
+    log?.set({ user: { id: 'safe-user' } });
+    expect(ctx.setAttributes).toHaveBeenCalledWith({ 'user.id': 'safe-user' });
+  });
+
+  it('createNoopRequestLogger never throws and emits an empty snapshot', () => {
+    const log = createNoopRequestLogger();
+    expect(() => {
+      log.set({ a: 1 });
+      log.info('hi', { b: 2 });
+      log.warn('careful');
+      log.error(new Error('boom'));
+    }).not.toThrow();
+    expect(log.getContext()).toEqual({});
+    const snapshot = log.emitNow();
+    expect(snapshot.traceId).toBe('');
+    expect(snapshot.context).toEqual({});
+  });
+});