agentic-pi 0.2.3 → 0.2.5

package/dist/telemetry/mapper.js

@@ -0,0 +1,334 @@
+/**
+ * Translates Pi's raw session event stream into an OpenTelemetry span tree
+ * plus metrics.
+ *
+ * Span tree (one-shot run → short-lived, so a real root span is correct):
+ *
+ *   agentic_pi.session                 (root)
+ *   └── agentic_pi.turn                 (per turn_start/turn_end)
+ *       ├── chat <model>                (per assistant message_start→message_end)
+ *       └── execute_tool <name>         (per tool_execution_start→end, keyed by toolCallId)
+ *
+ * Spans and metrics are both sourced from the SAME per-message / per-tool
+ * events (never from the aggregate session stats), so they agree and nothing
+ * is double-counted. Aggregate stats only decorate the root span.
+ *
+ * Every public method is defensive: missing/out-of-order pairs warn once and
+ * never throw — a telemetry glitch must never break the run.
+ */
+import { SpanKind, SpanStatusCode, ValueType, trace, } from "@opentelemetry/api";
+import { AgenticPi, GenAI, MetricName, SpanName, TokenType } from "./semconv.js";
+import { redact } from "./config.js";
+export class SpanMapper {
+    d;
+    now;
+    inst;
+    rootSpan;
+    rootCtx;
+    turnSpan;
+    turnCtx;
+    turnIndex = 0;
+    llm;
+    toolSpans = new Map();
+    ended = false;
+    warnedUnknownTool = false;
+    constructor(deps) {
+        this.d = deps;
+        this.now = deps.now ?? (() => Date.now());
+        this.inst = this.buildInstruments(deps.meter);
+    }
+    onEvent(event) {
+        if (this.ended)
+            return;
+        try {
+            this.ensureRoot();
+            switch (event.type) {
+                case "turn_start":
+                    this.onTurnStart();
+                    break;
+                case "turn_end":
+                    this.onTurnEnd();
+                    break;
+                case "message_start":
+                    this.onMessageStart(event.message);
+                    break;
+                case "message_end":
+                    this.onMessageEnd(event.message);
+                    break;
+                case "tool_execution_start":
+                    this.onToolStart(event.toolCallId, event.toolName, event.args);
+                    break;
+                case "tool_execution_end":
+                    this.onToolEnd(event.toolCallId, event.toolName, event.result, event.isError);
+                    break;
+                case "agent_end":
+                    this.onAgentEnd();
+                    break;
+                default:
+                    break;
+            }
+        }
+        catch (err) {
+            this.d.onWarn(`telemetry: failed to map ${event.type}: ${err.message}`);
+        }
+    }
+    /** Decorate the root span with terminal aggregate stats (reconciliation only). */
+    recordSessionStats(stats) {
+        if (this.ended)
+            return;
+        const root = this.rootSpan;
+        if (!root)
+            return;
+        if (typeof stats.cost === "number")
+            root.setAttribute(AgenticPi.COST_USD, stats.cost);
+        if (typeof stats.tokens?.total === "number") {
+            root.setAttribute(AgenticPi.TOTAL_TOKENS, stats.tokens.total);
+        }
+    }
+    /** Mark the root span as errored (called before shutdown on the fatal path). */
+    recordFatal(err) {
+        if (this.ended)
+            return;
+        this.ensureRoot();
+        this.rootSpan?.recordException(err);
+        this.rootSpan?.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+    }
+    /** Close any still-open spans (ERROR) and end the root. Idempotent. */
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        const abandon = (s) => {
+            if (!s)
+                return;
+            s.setStatus({ code: SpanStatusCode.ERROR, message: "span not closed before shutdown" });
+            s.end();
+        };
+        for (const { span } of this.toolSpans.values())
+            abandon(span);
+        this.toolSpans.clear();
+        abandon(this.llm?.span);
+        this.llm = undefined;
+        abandon(this.turnSpan);
+        this.turnSpan = undefined;
+        this.turnCtx = undefined;
+        // Root may already carry an OK/ERROR status from agent_end / recordFatal;
+        // end() without overriding so a clean run stays clean.
+        this.rootSpan?.end();
+        this.rootSpan = undefined;
+    }
+    // ── event handlers ────────────────────────────────────────────────
+    ensureRoot() {
+        if (this.rootSpan)
+            return;
+        this.rootCtx = this.d.rootParentContext;
+        this.rootSpan = this.d.tracer.startSpan(SpanName.SESSION, {
+            kind: SpanKind.INTERNAL,
+            attributes: {
+                [GenAI.CONVERSATION_ID]: this.d.sessionId,
+                [GenAI.SYSTEM]: this.d.genAiSystem,
+                [GenAI.REQUEST_MODEL]: this.d.requestModel,
+                [AgenticPi.SANDBOX_BACKEND]: this.d.sandboxBackend,
+            },
+        }, this.rootCtx);
+    }
+    parentCtx() {
+        return this.turnCtx ?? trace.setSpan(this.rootCtx, this.rootSpan);
+    }
+    onTurnStart() {
+        if (this.turnSpan)
+            this.abandonTurn();
+        const idx = this.turnIndex++;
+        const parent = trace.setSpan(this.rootCtx, this.rootSpan);
+        this.turnSpan = this.d.tracer.startSpan(SpanName.TURN, { kind: SpanKind.INTERNAL, attributes: { [AgenticPi.TURN_INDEX]: idx } }, parent);
+        this.turnCtx = trace.setSpan(parent, this.turnSpan);
+        this.inst.turns.add(1);
+    }
+    onTurnEnd() {
+        // Close a dangling LLM span first so it nests inside the turn.
+        if (this.llm) {
+            this.llm.span.end();
+            this.llm = undefined;
+        }
+        this.turnSpan?.end();
+        this.turnSpan = undefined;
+        this.turnCtx = undefined;
+    }
+    onMessageStart(message) {
+        if (message.role !== "assistant")
+            return;
+        const model = message.model ?? this.d.requestModel;
+        const span = this.d.tracer.startSpan(SpanName.llm(model), {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                [GenAI.OPERATION_NAME]: "chat",
+                [GenAI.SYSTEM]: message.provider ?? this.d.genAiSystem,
+                [GenAI.REQUEST_MODEL]: model,
+            },
+        }, this.parentCtx());
+        this.llm = { span, startMs: this.now() };
+    }
+    onMessageEnd(message) {
+        if (message.role !== "assistant")
+            return;
+        // message_start may have been missed; open a zero-duration span now.
+        if (!this.llm) {
+            const model = message.model ?? this.d.requestModel;
+            this.llm = {
+                span: this.d.tracer.startSpan(SpanName.llm(model), { kind: SpanKind.CLIENT }, this.parentCtx()),
+                startMs: this.now(),
+            };
+        }
+        const { span, startMs } = this.llm;
+        const system = message.provider ?? this.d.genAiSystem;
+        const model = message.model ?? this.d.requestModel;
+        const usage = message.usage;
+        span.setAttribute(GenAI.RESPONSE_MODEL, message.responseModel ?? model);
+        if (message.responseId)
+            span.setAttribute(GenAI.RESPONSE_ID, message.responseId);
+        if (message.stopReason)
+            span.setAttribute(GenAI.RESPONSE_FINISH_REASONS, [message.stopReason]);
+        if (usage) {
+            const dims = { [GenAI.SYSTEM]: system, [GenAI.REQUEST_MODEL]: model };
+            this.setAndMeasureToken(span, GenAI.USAGE_INPUT_TOKENS, usage.input, TokenType.INPUT, dims);
+            this.setAndMeasureToken(span, GenAI.USAGE_OUTPUT_TOKENS, usage.output, TokenType.OUTPUT, dims);
+            this.setAndMeasureToken(span, AgenticPi.CACHE_READ_TOKENS, usage.cacheRead, TokenType.CACHE_READ, dims);
+            this.setAndMeasureToken(span, AgenticPi.CACHE_WRITE_TOKENS, usage.cacheWrite, TokenType.CACHE_WRITE, dims);
+            const cost = usage.cost?.total;
+            if (typeof cost === "number") {
+                span.setAttribute(AgenticPi.COST_USD, cost);
+                this.inst.cost.record(cost, dims);
+            }
+        }
+        const content = redact(this.assistantText(message), this.d.includeContent);
+        if (content !== undefined)
+            span.setAttribute(GenAI.COMPLETION, content);
+        const durationS = (this.now() - startMs) / 1000;
+        this.inst.llmDuration.record(durationS, {
+            [GenAI.SYSTEM]: system,
+            [GenAI.REQUEST_MODEL]: model,
+        });
+        span.end();
+        this.llm = undefined;
+    }
+    onToolStart(toolCallId, toolName, args) {
+        const span = this.d.tracer.startSpan(SpanName.tool(toolName), {
+            kind: SpanKind.INTERNAL,
+            attributes: { [GenAI.TOOL_NAME]: toolName, [GenAI.TOOL_CALL_ID]: toolCallId },
+        }, this.parentCtx());
+        const argStr = redact(args, this.d.includeContent);
+        if (argStr !== undefined)
+            span.setAttribute(AgenticPi.TOOL_ARGUMENTS, argStr);
+        this.toolSpans.set(toolCallId, { span, startMs: this.now() });
+        this.inst.toolInvocations.add(1, { [GenAI.TOOL_NAME]: toolName });
+    }
+    onToolEnd(toolCallId, toolName, result, isError) {
+        let entry = this.toolSpans.get(toolCallId);
+        if (!entry) {
+            if (!this.warnedUnknownTool) {
+                this.warnedUnknownTool = true;
+                this.d.onWarn(`telemetry: tool_execution_end for unknown toolCallId ${toolCallId}`);
+            }
+            entry = {
+                span: this.d.tracer.startSpan(SpanName.tool(toolName), {
+                    kind: SpanKind.INTERNAL,
+                    attributes: { [GenAI.TOOL_NAME]: toolName, [GenAI.TOOL_CALL_ID]: toolCallId },
+                }, this.parentCtx()),
+                startMs: this.now(),
+            };
+        }
+        const { span, startMs } = entry;
+        span.setAttribute(AgenticPi.TOOL_IS_ERROR, isError);
+        const resultStr = redact(result, this.d.includeContent);
+        if (resultStr !== undefined)
+            span.setAttribute(AgenticPi.TOOL_RESULT, resultStr);
+        if (isError) {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            this.inst.toolFailures.add(1, { [GenAI.TOOL_NAME]: toolName });
+        }
+        this.inst.toolDuration.record((this.now() - startMs) / 1000, { [GenAI.TOOL_NAME]: toolName });
+        span.end();
+        this.toolSpans.delete(toolCallId);
+    }
+    onAgentEnd() {
+        if (this.llm) {
+            this.llm.span.end();
+            this.llm = undefined;
+        }
+        if (this.turnSpan)
+            this.abandonTurn();
+        // Mark success but DO NOT end the root span yet: getSessionStats() runs
+        // after prompt() returns (i.e. after this event), and recordSessionStats()
+        // needs the root span still open to attach aggregate totals. end() — called
+        // from shutdown() — closes it, preserving this OK status.
+        this.rootSpan?.setStatus({ code: SpanStatusCode.OK });
+    }
+    // ── helpers ───────────────────────────────────────────────────────
+    setAndMeasureToken(span, attrKey, value, tokenType, dims) {
+        if (typeof value !== "number" || value === 0)
+            return;
+        span.setAttribute(attrKey, value);
+        this.inst.tokens.record(value, { ...dims, [GenAI.TOKEN_TYPE]: tokenType });
+    }
+    abandonTurn() {
+        this.turnSpan?.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: "turn not closed before next turn_start",
+        });
+        this.turnSpan?.end();
+        this.turnSpan = undefined;
+        this.turnCtx = undefined;
+    }
+    assistantText(message) {
+        const content = message.content;
+        if (typeof content === "string")
+            return content;
+        if (!Array.isArray(content))
+            return undefined;
+        const text = content
+            .filter((c) => typeof c === "object" && c !== null && c.type === "text")
+            .map((c) => c.text ?? "")
+            .join("");
+        return text.length > 0 ? text : undefined;
+    }
+    buildInstruments(meter) {
+        return {
+            tokens: meter.createHistogram(MetricName.LLM_TOKENS, {
+                description: "Number of tokens used per LLM request, by token type.",
+                unit: "{token}",
+                valueType: ValueType.INT,
+            }),
+            llmDuration: meter.createHistogram(MetricName.LLM_DURATION, {
+                description: "Duration of LLM requests.",
+                unit: "s",
+                valueType: ValueType.DOUBLE,
+            }),
+            cost: meter.createHistogram(MetricName.COST, {
+                description: "Estimated cost per LLM request in USD.",
+                unit: "{usd}",
+                valueType: ValueType.DOUBLE,
+            }),
+            toolDuration: meter.createHistogram(MetricName.TOOL_DURATION, {
+                description: "Duration of tool executions.",
+                unit: "s",
+                valueType: ValueType.DOUBLE,
+            }),
+            toolInvocations: meter.createCounter(MetricName.TOOL_INVOCATIONS, {
+                description: "Count of tool invocations.",
+                unit: "{call}",
+                valueType: ValueType.INT,
+            }),
+            toolFailures: meter.createCounter(MetricName.TOOL_FAILURES, {
+                description: "Count of tool invocations that returned an error.",
+                unit: "{call}",
+                valueType: ValueType.INT,
+            }),
+            turns: meter.createCounter(MetricName.TURNS, {
+                description: "Count of agent turns.",
+                unit: "{turn}",
+                valueType: ValueType.INT,
+            }),
+        };
+    }
+}
+//# sourceMappingURL=mapper.js.map

package/dist/telemetry/mapper.js.map

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

package/dist/telemetry/sdk.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OpenTelemetry SDK construction. Imported dynamically (only on the enabled
+ * path) so the heavy `@opentelemetry/sdk-*` packages stay off the default
+ * code path.
+ *
+ * Diagnostics from the SDK and OTLP exporters are routed to `onWarn` via a
+ * custom `DiagLogger` that NEVER touches the console — this, plus using the
+ * granular SDK packages (not `@opentelemetry/sdk-node`, whose auto-config can
+ * log to stdout), is what keeps the `run()` no-stdout contract intact even
+ * when the collector is unreachable.
+ */
+import type { CreateTelemetryDeps, TelemetryHandle } from "./index.js";
+export declare function startTelemetrySdk(deps: CreateTelemetryDeps): TelemetryHandle;

package/dist/telemetry/sdk.js

@@ -0,0 +1,147 @@
+/**
+ * OpenTelemetry SDK construction. Imported dynamically (only on the enabled
+ * path) so the heavy `@opentelemetry/sdk-*` packages stay off the default
+ * code path.
+ *
+ * Diagnostics from the SDK and OTLP exporters are routed to `onWarn` via a
+ * custom `DiagLogger` that NEVER touches the console — this, plus using the
+ * granular SDK packages (not `@opentelemetry/sdk-node`, whose auto-config can
+ * log to stdout), is what keeps the `run()` no-stdout contract intact even
+ * when the collector is unreachable.
+ */
+import { DiagLogLevel, ROOT_CONTEXT, defaultTextMapGetter, diag, } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { defaultResource, detectResources, envDetector, resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { SpanMapper } from "./mapper.js";
+import { DEFAULT_SERVICE_NAME, GenAI } from "./semconv.js";
+const SHUTDOWN_TIMEOUT_MS = 5000;
+const INSTRUMENTATION_SCOPE = "agentic-pi";
+/** Route SDK/exporter diagnostics to onWarn — never to the console. */
+class OnWarnDiagLogger {
+    onWarn;
+    constructor(onWarn) {
+        this.onWarn = onWarn;
+    }
+    error(message) {
+        this.onWarn(`otel: ${message}`);
+    }
+    warn(message) {
+        this.onWarn(`otel: ${message}`);
+    }
+    info() { }
+    debug() { }
+    verbose() { }
+}
+export function startTelemetrySdk(deps) {
+    const env = deps.env ?? process.env;
+    const onWarn = deps.onWarn;
+    diag.setLogger(new OnWarnDiagLogger(onWarn), DiagLogLevel.WARN);
+    const { provider, modelId } = splitModel(deps.model);
+    const serviceName = deps.config.serviceName ?? DEFAULT_SERVICE_NAME;
+    if (!hasOtlpTarget(env, deps.config.endpoint)) {
+        onWarn("telemetry: enabled but no OTLP endpoint configured (set OTEL_EXPORTER_OTLP_ENDPOINT or --otel-endpoint); spans/metrics will not be exported");
+    }
+    const resource = defaultResource()
+        .merge(detectResources({ detectors: [envDetector] }))
+        .merge(resourceFromAttributes({
+        "service.name": serviceName,
+        [GenAI.SYSTEM]: provider,
+    }));
+    const traceUrl = signalUrl(deps.config.endpoint, "v1/traces");
+    const metricUrl = signalUrl(deps.config.endpoint, "v1/metrics");
+    const tracerProvider = new NodeTracerProvider({
+        resource,
+        spanProcessors: env.OTEL_TRACES_EXPORTER === "none"
+            ? []
+            : [new BatchSpanProcessor(new OTLPTraceExporter(traceUrl ? { url: traceUrl } : {}))],
+    });
+    const meterProvider = new MeterProvider({
+        resource,
+        readers: env.OTEL_METRICS_EXPORTER === "none"
+            ? []
+            : [
+                new PeriodicExportingMetricReader({
+                    exporter: new OTLPMetricExporter(metricUrl ? { url: metricUrl } : {}),
+                }),
+            ],
+    });
+    // We deliberately do NOT register these providers globally: agentic-pi may
+    // run multiple sessions in-process (library mode), and a global install
+    // would leak state across runs. Spans are created from this tracer with
+    // explicit parent contexts instead.
+    const tracer = tracerProvider.getTracer(INSTRUMENTATION_SCOPE);
+    const meter = meterProvider.getMeter(INSTRUMENTATION_SCOPE);
+    const rootParentContext = resolveInboundContext(env);
+    const mapper = new SpanMapper({
+        tracer,
+        meter,
+        rootParentContext,
+        sessionId: deps.sessionId,
+        genAiSystem: provider,
+        requestModel: modelId,
+        sandboxBackend: deps.sandboxBackend,
+        includeContent: deps.config.includeContent,
+        onWarn,
+    });
+    return {
+        status: "configured",
+        onEvent: (event) => mapper.onEvent(event),
+        recordSessionStats: (stats) => mapper.recordSessionStats(stats),
+        recordFatal: (err) => mapper.recordFatal(err),
+        shutdown: async () => {
+            mapper.end();
+            await withTimeout(Promise.allSettled([tracerProvider.shutdown(), meterProvider.shutdown()]), SHUTDOWN_TIMEOUT_MS, onWarn);
+            diag.disable();
+        },
+    };
+}
+function resolveInboundContext(env) {
+    const traceparent = env.TRACEPARENT;
+    if (!traceparent)
+        return ROOT_CONTEXT;
+    const carrier = { traceparent };
+    if (env.TRACESTATE)
+        carrier.tracestate = env.TRACESTATE;
+    return new W3CTraceContextPropagator().extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
+}
+function splitModel(spec) {
+    const i = spec.indexOf("/");
+    if (i < 0)
+        return { provider: "unknown", modelId: spec };
+    return { provider: spec.slice(0, i), modelId: spec.slice(i + 1) };
+}
+function hasOtlpTarget(env, endpoint) {
+    return Boolean(endpoint ||
+        env.OTEL_EXPORTER_OTLP_ENDPOINT ||
+        env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
+        env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT);
+}
+/** Build a per-signal URL from the --otel-endpoint base (env is handled by the exporter). */
+function signalUrl(base, suffix) {
+    if (!base)
+        return undefined;
+    return `${base.replace(/\/+$/, "")}/${suffix}`;
+}
+async function withTimeout(promise, ms, onWarn) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            onWarn(`telemetry: exporter flush timed out after ${ms}ms; proceeding`);
+            resolve();
+        }, ms);
+        timer.unref?.();
+    });
+    try {
+        await Promise.race([promise.then(() => undefined), timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=sdk.js.map

package/dist/telemetry/sdk.js.map

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

package/dist/telemetry/semconv.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Centralized OpenTelemetry attribute keys, span names, and metric names.
+ *
+ * Single source of truth so the still-evolving GenAI semantic conventions
+ * (`gen_ai.*`) are pinned in exactly one place. We hand-define the `gen_ai.*`
+ * keys as literals rather than importing them from
+ * `@opentelemetry/semantic-conventions/incubating`, because that incubating
+ * export path is unstable across minor releases — depending on the runtime
+ * values, not the package's export surface, keeps us insulated from churn.
+ */
+/** Stable GenAI semantic-convention attribute keys. */
+export declare const GenAI: {
+    readonly SYSTEM: "gen_ai.system";
+    readonly OPERATION_NAME: "gen_ai.operation.name";
+    readonly CONVERSATION_ID: "gen_ai.conversation.id";
+    readonly REQUEST_MODEL: "gen_ai.request.model";
+    readonly RESPONSE_MODEL: "gen_ai.response.model";
+    readonly RESPONSE_ID: "gen_ai.response.id";
+    readonly RESPONSE_FINISH_REASONS: "gen_ai.response.finish_reasons";
+    readonly USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly TOOL_NAME: "gen_ai.tool.name";
+    readonly TOOL_CALL_ID: "gen_ai.tool.call.id";
+    /** Metric-only dimension: which token bucket a measurement belongs to. */
+    readonly TOKEN_TYPE: "gen_ai.token.type";
+    /** Content-gated span attributes (only set when includeContent is on). */
+    readonly PROMPT: "gen_ai.prompt";
+    readonly COMPLETION: "gen_ai.completion";
+};
+/**
+ * agentic-pi-specific attribute keys, namespaced under `agentic_pi.*` to
+ * avoid colliding with any future standard key. Used where no stable GenAI
+ * equivalent exists yet (cache tokens, cost, tool error/args/result).
+ */
+export declare const AgenticPi: {
+    readonly CACHE_READ_TOKENS: "agentic_pi.usage.cache_read_tokens";
+    readonly CACHE_WRITE_TOKENS: "agentic_pi.usage.cache_write_tokens";
+    readonly COST_USD: "agentic_pi.usage.cost_usd";
+    readonly TOTAL_TOKENS: "agentic_pi.usage.total_tokens";
+    readonly TOOL_IS_ERROR: "agentic_pi.tool.is_error";
+    readonly TURN_INDEX: "agentic_pi.turn.index";
+    readonly SANDBOX_BACKEND: "agentic_pi.sandbox.backend";
+    /** Content-gated tool span attributes. */
+    readonly TOOL_ARGUMENTS: "agentic_pi.tool.arguments";
+    readonly TOOL_RESULT: "agentic_pi.tool.result";
+};
+/** Metric dimension value for {@link GenAI.TOKEN_TYPE}. */
+export declare const TokenType: {
+    readonly INPUT: "input";
+    readonly OUTPUT: "output";
+    readonly CACHE_READ: "cache_read";
+    readonly CACHE_WRITE: "cache_write";
+};
+/** Span names. Tool/LLM names embed the tool/model per GenAI span-naming guidance. */
+export declare const SpanName: {
+    readonly SESSION: "agentic_pi.session";
+    readonly TURN: "agentic_pi.turn";
+    readonly tool: (toolName: string) => string;
+    readonly llm: (model: string) => string;
+};
+/** Metric instrument names. */
+export declare const MetricName: {
+    readonly LLM_TOKENS: "gen_ai.client.token.usage";
+    readonly LLM_DURATION: "gen_ai.client.operation.duration";
+    readonly COST: "agentic_pi.cost.usd";
+    readonly TOOL_DURATION: "agentic_pi.tool.duration";
+    readonly TOOL_INVOCATIONS: "agentic_pi.tool.invocations";
+    readonly TOOL_FAILURES: "agentic_pi.tool.failures";
+    readonly TURNS: "agentic_pi.turns";
+};
+/** Default OTEL resource service name when neither flag nor env overrides it. */
+export declare const DEFAULT_SERVICE_NAME = "agentic-pi";