@esankhan3/anvil-agent-core 0.1.0

package/dist/telemetry/metrics.js

@@ -0,0 +1,186 @@
+/**
+ * GenAI metrics — emits OTel metrics on every adapter call alongside the
+ * existing trace span. Mirrors the OTel GenAI semconv counters/histograms
+ * so dashboards built against any compliant collector keep working.
+ *
+ * Instruments:
+ *   - gen_ai.client.token.usage   (counter, by io_type ∈ input|output|cache_read|cache_write|reasoning)
+ *   - gen_ai.client.cost_usd      (counter, by component ∈ input|output|cache_read|cache_write|total)
+ *   - gen_ai.client.operation.duration  (histogram, ms)
+ *   - gen_ai.cache.hit_ratio      (gauge per call, 0–1)
+ *
+ * All instruments inherit the shared resource (service.name, anvil.run_id,
+ * etc.) registered in tracer.ts. Metrics shipping is gated on the same
+ * TelemetryConfig as traces — disabled telemetry produces no-op meters.
+ */
+import { metrics, diag, } from '@opentelemetry/api';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { MeterProvider, PeriodicExportingMetricReader, } from '@opentelemetry/sdk-metrics';
+import { OTLPMetricExporter, AggregationTemporalityPreference, } from '@opentelemetry/exporter-metrics-otlp-http';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from '@opentelemetry/semantic-conventions';
+import { hostname } from 'node:os';
+import { loadTelemetryConfig } from './config.js';
+import { VERSION } from '../version.js';
+const METER_NAME = 'anvil.agent-core';
+const EXPORT_INTERVAL_MS = 5_000;
+let _meter = null;
+let _provider = null;
+let _reader = null;
+let _tokenCounter = null;
+let _costCounter = null;
+let _durationHist = null;
+let _cacheHitGauge = null;
+function buildResourceAttrs(config) {
+    const host = hostname();
+    return {
+        [ATTR_SERVICE_NAME]: config.serviceName,
+        [ATTR_SERVICE_VERSION]: VERSION,
+        'service.namespace': 'anvil',
+        'service.instance.id': process.env.ANVIL_INSTANCE_ID ?? `${host}-${process.pid}`,
+        'host.name': host,
+        'deployment.environment': process.env.ANVIL_ENV ?? process.env.DEPLOYMENT_ENVIRONMENT ?? 'local',
+    };
+}
+function normalizeMetricsEndpoint(endpoint) {
+    if (!endpoint)
+        return endpoint;
+    try {
+        const url = new URL(endpoint);
+        if (url.pathname === '' || url.pathname === '/') {
+            url.pathname = '/v1/metrics';
+            return url.toString();
+        }
+        return endpoint;
+    }
+    catch {
+        return endpoint;
+    }
+}
+function ensureMeter() {
+    if (_meter)
+        return _meter;
+    const config = loadTelemetryConfig();
+    // ANVIL_OTEL_METRICS_DISABLED=1 → keep traces but skip metrics export.
+    // Useful when the OTLP backend is traces-only (e.g. Langfuse), where
+    // POSTing metrics produces a periodic AggregateError every export tick.
+    const metricsDisabled = process.env.ANVIL_OTEL_METRICS_DISABLED === '1';
+    if (!config.enabled || config.exporterMode !== 'otlp' || metricsDisabled) {
+        // Use the global no-op MeterProvider when telemetry is disabled or in
+        // console mode (no metrics console exporter wired today).
+        _meter = metrics.getMeter(METER_NAME, VERSION);
+        return _meter;
+    }
+    // Prometheus only accepts CUMULATIVE temporality. The SDK's default
+    // (LOWMEMORY) emits histograms as DELTA, which Prometheus rejects with
+    // "invalid temporality and type combination".
+    const exporter = new OTLPMetricExporter({
+        url: normalizeMetricsEndpoint(config.endpoint),
+        headers: config.headers,
+        temporalityPreference: AggregationTemporalityPreference.CUMULATIVE,
+    });
+    _reader = new PeriodicExportingMetricReader({
+        exporter,
+        exportIntervalMillis: EXPORT_INTERVAL_MS,
+    });
+    _provider = new MeterProvider({
+        resource: resourceFromAttributes(buildResourceAttrs(config)),
+        readers: [_reader],
+    });
+    metrics.setGlobalMeterProvider(_provider);
+    _meter = _provider.getMeter(METER_NAME, VERSION);
+    diag.debug(`[telemetry] meter initialised — endpoint=${config.endpoint ?? 'n/a'} `
+        + `interval=${EXPORT_INTERVAL_MS}ms`);
+    return _meter;
+}
+function instruments() {
+    const meter = ensureMeter();
+    if (!_tokenCounter) {
+        _tokenCounter = meter.createCounter('gen_ai.client.token.usage', {
+            description: 'Tokens consumed by GenAI calls, broken down by io_type',
+            unit: '{token}',
+        });
+    }
+    if (!_costCounter) {
+        _costCounter = meter.createCounter('gen_ai.client.cost_usd', {
+            description: 'Estimated USD cost of GenAI calls, by component',
+            unit: 'USD',
+        });
+    }
+    if (!_durationHist) {
+        _durationHist = meter.createHistogram('gen_ai.client.operation.duration', {
+            description: 'Wall-clock duration of GenAI client operations',
+            unit: 'ms',
+        });
+    }
+    if (!_cacheHitGauge) {
+        _cacheHitGauge = meter.createGauge('gen_ai.cache.hit_ratio', {
+            description: 'Per-call prompt-cache hit ratio (0..1)',
+            unit: '1',
+        });
+    }
+    return {
+        tokens: _tokenCounter,
+        cost: _costCounter,
+        duration: _durationHist,
+        cacheHit: _cacheHitGauge,
+    };
+}
+/** Record one adapter call — emits all 4 instruments with consistent labels.
+ * Safe to call when telemetry is disabled (no-op meter eats the writes). */
+export function recordGenAiCall(m) {
+    const inst = instruments();
+    const baseAttrs = {
+        'gen_ai.system': m.system,
+        'gen_ai.request.model': m.requestModel,
+    };
+    if (m.responseModel)
+        baseAttrs['gen_ai.response.model'] = m.responseModel;
+    if (m.stage)
+        baseAttrs['anvil.stage'] = m.stage;
+    if (m.persona)
+        baseAttrs['anvil.persona'] = m.persona;
+    // Tokens — one data point per io_type so dashboards can slice.
+    inst.tokens.add(m.inputTokens, { ...baseAttrs, io_type: 'input' });
+    inst.tokens.add(m.outputTokens, { ...baseAttrs, io_type: 'output' });
+    if (m.cacheReadTokens > 0) {
+        inst.tokens.add(m.cacheReadTokens, { ...baseAttrs, io_type: 'cache_read' });
+    }
+    if (m.cacheWriteTokens > 0) {
+        inst.tokens.add(m.cacheWriteTokens, { ...baseAttrs, io_type: 'cache_write' });
+    }
+    if (m.reasoningTokens && m.reasoningTokens > 0) {
+        inst.tokens.add(m.reasoningTokens, { ...baseAttrs, io_type: 'reasoning' });
+    }
+    // Cost — separated per component so dashboards can stack a cost graph.
+    inst.cost.add(m.costInputUsd, { ...baseAttrs, component: 'input' });
+    inst.cost.add(m.costOutputUsd, { ...baseAttrs, component: 'output' });
+    inst.cost.add(m.costCacheReadUsd, { ...baseAttrs, component: 'cache_read' });
+    inst.cost.add(m.costCacheWriteUsd, { ...baseAttrs, component: 'cache_write' });
+    inst.cost.add(m.costTotalUsd, { ...baseAttrs, component: 'total' });
+    // Latency.
+    inst.duration.record(m.durationMs, baseAttrs);
+    // Cache hit ratio — denominator is input + cache_read tokens.
+    const denom = m.inputTokens + m.cacheReadTokens;
+    if (denom > 0) {
+        inst.cacheHit.record(m.cacheReadTokens / denom, baseAttrs);
+    }
+}
+/** Force-flush any pending metric data and tear down the provider. */
+export async function shutdownMetrics() {
+    if (!_provider)
+        return;
+    try {
+        await _provider.forceFlush();
+        await _provider.shutdown();
+    }
+    finally {
+        _provider = null;
+        _reader = null;
+        _meter = null;
+        _tokenCounter = null;
+        _costCounter = null;
+        _durationHist = null;
+        _cacheHitGauge = null;
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/telemetry/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/tracer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tracer initialization — lazily registers an OTel TracerProvider on first
+ * call. When telemetry is disabled, returns the API's no-op tracer (zero
+ * overhead, no global state mutation).
+ *
+ * Resource enrichment:
+ *   - service.name / service.version from TelemetryConfig
+ *   - service.namespace = "anvil"
+ *   - service.instance.id = `${hostname}-${pid}` (overridable)
+ *   - host.name from os.hostname()
+ *   - process.pid / process.runtime.{name,version}
+ *   - deployment.environment from ANVIL_ENV (default "local")
+ *   - extra attrs parsed from OTEL_RESOURCE_ATTRIBUTES (k1=v1,k2=v2)
+ *
+ * Graceful shutdown: SIGINT/SIGTERM/beforeExit hooks call `forceFlush()`
+ * + `shutdown()` so trailing spans/metrics aren't lost on `pkill`.
+ */
+import { type Tracer } from '@opentelemetry/api';
+import { type TelemetryConfig } from './config.js';
+export declare function getTracer(): Tracer;
+/** Force-flush any pending spans and tear down the provider. Call once at
+ * graceful shutdown if you can't rely on the auto-installed hooks (e.g.
+ * Lambda runtimes, bespoke shutdown sequences). Also drains the metrics
+ * pipeline so per-run cost/token counters land before exit. Safe to call
+ * multiple times. */
+export declare function shutdownTracer(): Promise<void>;
+/** Test seam — clears the cached tracer + shuts down the provider so the
+ * next getTracer() call rebuilds from a fresh config. Awaitable so tests
+ * can ensure all spans flush before assertion. */
+export declare function resetTracer(): Promise<void>;
+/** Diagnostic — exposes the active TelemetryConfig used at registration time. */
+export declare function getTelemetryConfig(): TelemetryConfig;
+//# sourceMappingURL=tracer.d.ts.map

package/dist/telemetry/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/telemetry/tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAa5B,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AA2ExE,wBAAgB,SAAS,IAAI,MAAM,CAoClC;AAED;;;;qBAIqB;AACrB,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAWpD;AAED;;kDAEkD;AAClD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAYjD;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD"}

package/dist/telemetry/tracer.js

@@ -0,0 +1,162 @@
+/**
+ * Tracer initialization — lazily registers an OTel TracerProvider on first
+ * call. When telemetry is disabled, returns the API's no-op tracer (zero
+ * overhead, no global state mutation).
+ *
+ * Resource enrichment:
+ *   - service.name / service.version from TelemetryConfig
+ *   - service.namespace = "anvil"
+ *   - service.instance.id = `${hostname}-${pid}` (overridable)
+ *   - host.name from os.hostname()
+ *   - process.pid / process.runtime.{name,version}
+ *   - deployment.environment from ANVIL_ENV (default "local")
+ *   - extra attrs parsed from OTEL_RESOURCE_ATTRIBUTES (k1=v1,k2=v2)
+ *
+ * Graceful shutdown: SIGINT/SIGTERM/beforeExit hooks call `forceFlush()`
+ * + `shutdown()` so trailing spans/metrics aren't lost on `pkill`.
+ */
+import { trace, diag, DiagConsoleLogger, DiagLogLevel, } from '@opentelemetry/api';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { BatchSpanProcessor, SimpleSpanProcessor, } from '@opentelemetry/sdk-trace-base';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from '@opentelemetry/semantic-conventions';
+import { hostname } from 'node:os';
+import { loadTelemetryConfig } from './config.js';
+import { buildExporter } from './exporters.js';
+import { shutdownMetrics } from './metrics.js';
+import { VERSION } from '../version.js';
+const TRACER_NAME = 'anvil.agent-core';
+let _tracer = null;
+let _provider = null;
+let _shutdownHooked = false;
+function parseResourceAttrs(raw) {
+    if (!raw)
+        return {};
+    const out = {};
+    for (const pair of raw.split(',')) {
+        const idx = pair.indexOf('=');
+        if (idx <= 0)
+            continue;
+        const key = pair.slice(0, idx).trim();
+        const value = pair.slice(idx + 1).trim();
+        if (key)
+            out[key] = value;
+    }
+    return out;
+}
+function buildResource(config) {
+    const host = hostname();
+    const pid = process.pid;
+    const env = process.env.ANVIL_ENV ?? process.env.DEPLOYMENT_ENVIRONMENT ?? 'local';
+    return {
+        [ATTR_SERVICE_NAME]: config.serviceName,
+        [ATTR_SERVICE_VERSION]: VERSION,
+        'service.namespace': 'anvil',
+        'service.instance.id': process.env.ANVIL_INSTANCE_ID ?? `${host}-${pid}`,
+        'host.name': host,
+        'process.pid': pid,
+        'process.runtime.name': 'nodejs',
+        'process.runtime.version': process.versions.node,
+        'deployment.environment': env,
+        ...parseResourceAttrs(process.env.OTEL_RESOURCE_ATTRIBUTES),
+    };
+}
+function installShutdownHook() {
+    if (_shutdownHooked)
+        return;
+    _shutdownHooked = true;
+    const flush = async () => {
+        try {
+            if (_provider) {
+                await _provider.forceFlush();
+                await _provider.shutdown();
+            }
+            await shutdownMetrics();
+        }
+        catch (err) {
+            diag.warn(`[telemetry] shutdown failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    // beforeExit fires when the event loop empties — best place for clean
+    // shutdown. SIGINT/SIGTERM cover ctrl-c and pkill.
+    process.once('beforeExit', () => { void flush(); });
+    for (const sig of ['SIGINT', 'SIGTERM']) {
+        process.once(sig, () => {
+            void flush().finally(() => {
+                // Re-raise the signal so the process actually exits with the
+                // right code instead of hanging on a successful flush.
+                process.kill(process.pid, sig);
+            });
+        });
+    }
+}
+export function getTracer() {
+    if (_tracer)
+        return _tracer;
+    const config = loadTelemetryConfig();
+    if (!config.enabled) {
+        _tracer = trace.getTracer(TRACER_NAME, VERSION);
+        return _tracer;
+    }
+    // OTEL_LOG_LEVEL surfaces SDK errors (OTLP POST failures etc.) at the
+    // requested level. ERROR is the right default for steady-state ops;
+    // bump to DEBUG/INFO when diagnosing.
+    const logLevel = (process.env.OTEL_LOG_LEVEL ?? 'ERROR').toUpperCase();
+    diag.setLogger(new DiagConsoleLogger(), DiagLogLevel[logLevel] ?? DiagLogLevel.ERROR);
+    // SimpleSpanProcessor ships per-span (instant Jaeger/Tempo arrival) for
+    // dev. Production should set ANVIL_OTEL_BATCH=1 to amortise network IO.
+    const exporter = buildExporter(config);
+    const processor = process.env.ANVIL_OTEL_BATCH === '1'
+        ? new BatchSpanProcessor(exporter)
+        : new SimpleSpanProcessor(exporter);
+    _provider = new NodeTracerProvider({
+        resource: resourceFromAttributes(buildResource(config)),
+        spanProcessors: [processor],
+    });
+    _provider.register();
+    _tracer = trace.getTracer(TRACER_NAME, VERSION);
+    installShutdownHook();
+    diag.debug(`[telemetry] tracer initialised — service=${config.serviceName} `
+        + `mode=${config.exporterMode} endpoint=${config.endpoint ?? 'n/a'}`);
+    return _tracer;
+}
+/** Force-flush any pending spans and tear down the provider. Call once at
+ * graceful shutdown if you can't rely on the auto-installed hooks (e.g.
+ * Lambda runtimes, bespoke shutdown sequences). Also drains the metrics
+ * pipeline so per-run cost/token counters land before exit. Safe to call
+ * multiple times. */
+export async function shutdownTracer() {
+    try {
+        if (_provider) {
+            await _provider.forceFlush();
+            await _provider.shutdown();
+        }
+        await shutdownMetrics();
+    }
+    finally {
+        _provider = null;
+        _tracer = null;
+    }
+}
+/** Test seam — clears the cached tracer + shuts down the provider so the
+ * next getTracer() call rebuilds from a fresh config. Awaitable so tests
+ * can ensure all spans flush before assertion. */
+export async function resetTracer() {
+    if (_provider) {
+        try {
+            await _provider.forceFlush();
+            await _provider.shutdown();
+        }
+        catch {
+            // ignore — best effort
+        }
+        _provider = null;
+    }
+    _tracer = null;
+    trace.disable();
+}
+/** Diagnostic — exposes the active TelemetryConfig used at registration time. */
+export function getTelemetryConfig() {
+    return loadTelemetryConfig();
+}
+//# sourceMappingURL=tracer.js.map

package/dist/telemetry/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../src/telemetry/tracer.ts"],"names":[],"mappings":"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"}

package/dist/tools/__tests__/builtin.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Adversarial tests for `BuiltinToolExecutor`. These tools form a
+ * security boundary — every test here is a known escape vector that
+ * must stay closed.
+ */
+export {};
+//# sourceMappingURL=builtin.test.d.ts.map

package/dist/tools/__tests__/builtin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/builtin.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}