@gajae-code/agent-core 0.1.1

package/dist/types/telemetry.d.ts

@@ -0,0 +1,588 @@
+/**
+ * OpenTelemetry instrumentation for the agent loop.
+ *
+ * Implements the OpenTelemetry GenAI semantic conventions
+ * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `pi.gen_ai.*`
+ * extension attributes for run summaries, dashboard summaries, and cost hints
+ * that are useful to downstream observability UIs.
+ *
+ * Span hierarchy emitted by the loop:
+ *
+ *   invoke_agent {agent.name}         (one per runLoop, gen_ai.operation.name=invoke_agent)
+ *   ├── chat {model}                  (one per LLM call, gen_ai.operation.name=chat)
+ *   ├── execute_tool {tool.name}      (one per tool call, gen_ai.operation.name=execute_tool)
+ *   └── ...
+ *
+ * The `handoff` operation is emitted via the public {@link recordHandoff}
+ * helper for hosts that route work between named agents.
+ *
+ * Activation is opt-in: callers pass an {@link AgentTelemetryConfig} on
+ * `AgentLoopConfig.telemetry`. When unset, every helper short-circuits and
+ * the loop performs zero tracer lookups. When set but no OTEL SDK is
+ * registered, `@opentelemetry/api` returns a no-op tracer and all calls are
+ * cheap pass-throughs.
+ */
+import { type Api, type AssistantMessage, type Context, type Message, type Model, type ServiceTier, type SimpleStreamOptions, type StopReason, type ToolChoice, type Usage } from "@gajae-code/ai";
+import { type Attributes, type AttributeValue, type Span, SpanKind, SpanStatusCode, type Tracer, trace } from "@opentelemetry/api";
+import { AgentRunCollector, type AgentRunCoverage, type AgentRunSummary, type ToolStatus } from "./run-collector";
+import type { AgentTool } from "./types";
+/** Default tracer name. Override via {@link AgentTelemetryConfig.tracerName}. */
+export declare const DEFAULT_TRACER_NAME = "@gajae-code/agent-core";
+/**
+ * GenAI semantic-convention attribute keys grouped by operation. Hoisted so
+ * call sites stay typo-proof and easy to grep.
+ */
+export declare const enum GenAIAttr {
+    ProviderName = "gen_ai.provider.name",
+    OperationName = "gen_ai.operation.name",
+    ConversationId = "gen_ai.conversation.id",
+    OutputType = "gen_ai.output.type",
+    AgentId = "gen_ai.agent.id",
+    AgentName = "gen_ai.agent.name",
+    AgentDescription = "gen_ai.agent.description",
+    RequestModel = "gen_ai.request.model",
+    RequestMaxTokens = "gen_ai.request.max_tokens",
+    RequestTemperature = "gen_ai.request.temperature",
+    RequestTopP = "gen_ai.request.top_p",
+    RequestTopK = "gen_ai.request.top_k",
+    RequestFrequencyPenalty = "gen_ai.request.frequency_penalty",
+    RequestPresencePenalty = "gen_ai.request.presence_penalty",
+    RequestStopSequences = "gen_ai.request.stop_sequences",
+    RequestSeed = "gen_ai.request.seed",
+    RequestChoiceCount = "gen_ai.request.choice.count",
+    RequestStream = "gen_ai.request.stream",
+    ResponseModel = "gen_ai.response.model",
+    ResponseId = "gen_ai.response.id",
+    ResponseFinishReasons = "gen_ai.response.finish_reasons",
+    ResponseTimeToFirstChunk = "gen_ai.response.time_to_first_chunk",
+    UsageInputTokens = "gen_ai.usage.input_tokens",
+    UsageOutputTokens = "gen_ai.usage.output_tokens",
+    UsageCacheReadInputTokens = "gen_ai.usage.cache_read.input_tokens",
+    UsageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens",
+    UsageReasoningOutputTokens = "gen_ai.usage.reasoning.output_tokens",
+    ToolCallId = "gen_ai.tool.call.id",
+    ToolName = "gen_ai.tool.name",
+    ToolDescription = "gen_ai.tool.description",
+    ToolType = "gen_ai.tool.type",
+    ToolCallArguments = "gen_ai.tool.call.arguments",
+    ToolCallResult = "gen_ai.tool.call.result",
+    ToolDefinitions = "gen_ai.tool.definitions",
+    InputMessages = "gen_ai.input.messages",
+    OutputMessages = "gen_ai.output.messages",
+    SystemInstructions = "gen_ai.system_instructions",
+    ErrorType = "error.type"
+}
+/** OpenAI semantic-convention attribute keys. */
+export declare const enum OpenAIAttr {
+    RequestServiceTier = "openai.request.service_tier",
+    ResponseServiceTier = "openai.response.service_tier"
+}
+/** Project extension attributes. Kept out of the reserved `gen_ai.*` namespace. */
+export declare const enum PiGenAIAttr {
+    AgentStepNumber = "pi.gen_ai.agent.step.number",
+    AgentStepCount = "pi.gen_ai.agent.step.count",
+    RequestReasoningEffort = "pi.gen_ai.request.reasoning.effort",
+    RequestToolChoice = "pi.gen_ai.request.tool.choice",
+    RequestAvailableTools = "pi.gen_ai.request.available_tools",
+    RequestMessages = "pi.gen_ai.request.messages",
+    ResponseText = "pi.gen_ai.response.text",
+    ResponseToolCalls = "pi.gen_ai.response.tool_calls",
+    UsageTotalTokens = "pi.gen_ai.usage.total_tokens",
+    UsageServerSideTools = "pi.gen_ai.usage.server_tool_requests",
+    CostEstimatedUsd = "pi.gen_ai.cost.estimated_usd",
+    CostInputUsd = "pi.gen_ai.cost.input_usd",
+    CostOutputUsd = "pi.gen_ai.cost.output_usd",
+    CostUnavailableReason = "pi.gen_ai.cost.unavailable_reason",
+    ToolStatus = "pi.gen_ai.tool.status",
+    ToolCallIntent = "pi.gen_ai.tool.call.intent",
+    HandoffFromAgentName = "pi.gen_ai.handoff.from_agent.name",
+    HandoffFromAgentId = "pi.gen_ai.handoff.from_agent.id",
+    HandoffToAgentName = "pi.gen_ai.handoff.to_agent.name",
+    HandoffToAgentId = "pi.gen_ai.handoff.to_agent.id",
+    OneshotKind = "pi.gen_ai.oneshot.kind",
+    GatewayName = "pi.gen_ai.gateway.name",
+    GatewayEndpoint = "pi.gen_ai.gateway.endpoint",
+    GatewayCallId = "pi.gen_ai.gateway.call_id",
+    GatewayRoutedTo = "pi.gen_ai.gateway.routed_to"
+}
+/** GenAI operation names — values for {@link GenAIAttr.OperationName}. */
+export declare const GenAIOperation: {
+    readonly Chat: "chat";
+    readonly ExecuteTool: "execute_tool";
+    readonly InvokeAgent: "invoke_agent";
+    readonly Handoff: "handoff";
+    readonly GenerateContent: "generate_content";
+    readonly TextCompletion: "text_completion";
+    readonly CreateAgent: "create_agent";
+    readonly Embeddings: "embeddings";
+};
+export type GenAIOperationName = (typeof GenAIOperation)[keyof typeof GenAIOperation];
+/** Identifies which agent span a callback is reporting on. */
+export type TelemetrySpanKind = "invoke_agent" | "chat" | "execute_tool" | "handoff";
+/**
+ * Aggregated usage + cost surface passed to {@link AgentTelemetryConfig.costEstimator}.
+ * Mirrors the bucketed shape we already emit as span attributes so the
+ * estimator never has to re-derive cache-read vs cache-write breakdowns.
+ */
+export interface ChatUsageSnapshot {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly cachedInputTokens: number | undefined;
+    readonly cacheWriteTokens: number | undefined;
+    readonly reasoningOutputTokens: number | undefined;
+}
+/** Context passed to the cost estimator. */
+export interface CostEstimatorContext {
+    readonly provider: string;
+    readonly model: string;
+    readonly serviceTier: ServiceTier | undefined;
+    readonly usage: ChatUsageSnapshot;
+}
+/**
+ * Cost estimator result.
+ *   { usd: number }                — cost is known; emitted as pi.gen_ai.cost.estimated_usd
+ *   { unavailable: string }        — cost is intentionally unknown; emitted as
+ *                                    pi.gen_ai.cost.unavailable_reason
+ *   undefined                      — no opinion; nothing emitted
+ */
+export type CostEstimate = {
+    readonly usd: number;
+    readonly inputUsd?: number;
+    readonly outputUsd?: number;
+} | {
+    readonly unavailable: string;
+};
+export interface CostDelta {
+    readonly conversationId: string | undefined;
+    readonly agent: AgentIdentity | undefined;
+    readonly stepNumber: number | undefined;
+    readonly provider: string;
+    readonly model: string;
+    readonly serviceTier: ServiceTier | undefined;
+    readonly usage: ChatUsageSnapshot;
+    readonly costUsd: number | undefined;
+    readonly inputUsd: number | undefined;
+    readonly outputUsd: number | undefined;
+    readonly costUnavailableReason: string | undefined;
+}
+/**
+ * Event fired for every chat step that produced usage, regardless of whether
+ * a {@link AgentTelemetryConfig.costEstimator} is configured. Use this to
+ * forward token usage to metrics pipelines or dashboards without taking a
+ * dependency on the cost estimator path.
+ */
+export interface ChatUsageEvent {
+    readonly span: Span;
+    readonly agent: AgentIdentity | undefined;
+    readonly conversationId: string | undefined;
+    readonly stepNumber: number | undefined;
+    readonly model: string;
+    readonly provider: string | undefined;
+    readonly serviceTier: ServiceTier | undefined;
+    readonly usage: ChatUsageSnapshot;
+    readonly cost: CostEstimate | undefined;
+    /** Resolved dynamic attributes for this chat span (from `resolveAttributes`). */
+    readonly attributes: Attributes | undefined;
+    /**
+     * Response headers captured from the upstream HTTP response, with keys
+     * lowercased (mirrors {@link ProviderResponseMetadata.headers}). `undefined`
+     * when the provider transport did not surface headers (non-HTTP providers,
+     * mocked streams, requests that aborted before headers arrived).
+     *
+     * Use this to reconcile gateway-issued ids (e.g. `x-litellm-call-id`) with
+     * downstream billing / spend dashboards. Known gateway patterns are also
+     * auto-stamped on the chat span as `pi.gen_ai.gateway.*` attributes.
+     */
+    readonly headers: Readonly<Record<string, string>> | undefined;
+}
+export type TelemetryContentCapture = boolean | "none" | "summary" | "full";
+export type ResolvedTelemetryContentCapture = "none" | "summary" | "full";
+export interface TelemetryContentSerializer {
+    readonly requestMessages?: (request: ChatRequestSnapshot) => string | undefined;
+    readonly responseText?: (message: AssistantMessage) => string | undefined;
+    readonly responseToolCalls?: (message: AssistantMessage) => string | undefined;
+    readonly toolCallArguments?: (args: unknown) => string | undefined;
+    readonly toolCallResult?: (result: unknown) => string | undefined;
+}
+/** Identity recorded on every invoke_agent and on emitted handoff spans. */
+export interface AgentIdentity {
+    readonly id?: string;
+    readonly name?: string;
+    readonly description?: string;
+}
+export interface AgentTelemetryWarning {
+    readonly code: "resolve_attributes_failed" | "content_serializer_failed" | "on_cost_delta_failed" | "on_chat_usage_failed" | "cost_estimator_failed" | "on_run_end_failed" | "on_span_start_failed" | "on_span_end_failed" | "normalize_agent_name_failed" | "normalize_provider_failed" | "on_telemetry_warning_failed";
+    readonly message: string;
+    readonly error?: unknown;
+}
+/** Context passed to attribute resolvers and lifecycle hooks. */
+export interface TelemetryAttributeContext {
+    readonly kind: TelemetrySpanKind;
+    readonly model: Model | undefined;
+    readonly agent: AgentIdentity | undefined;
+    readonly conversationId: string | undefined;
+    /** Per-step number on chat spans (0-indexed); undefined on other kinds. */
+    readonly stepNumber?: number;
+    /** Tool call info on execute_tool spans. */
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+}
+/** Context passed to {@link AgentTelemetryConfig.onSpanStart} / `onSpanEnd`. */
+export interface TelemetryHookContext extends TelemetryAttributeContext {
+    readonly span: Span;
+}
+/**
+ * Opt-in OpenTelemetry configuration accepted by the agent loop.
+ *
+ * All fields are optional. Passing the empty object `{}` enables
+ * instrumentation with sensible defaults. Pass `undefined` (or omit the
+ * `telemetry` field entirely) to disable everything — the loop performs zero
+ * tracer lookups in that case.
+ */
+export interface AgentTelemetryConfig {
+    /**
+     * Override the tracer instance. When omitted, the loop calls
+     * `trace.getTracer(tracerName ?? DEFAULT_TRACER_NAME)` lazily on first use.
+     */
+    readonly tracer?: Tracer;
+    /** Override the tracer name passed to `trace.getTracer`. */
+    readonly tracerName?: string;
+    /**
+     * Capture request/response content. `true` preserves the historical full
+     * payload capture; `"summary"` emits bounded dashboard-friendly summaries;
+     * `"full"` emits both summaries and full OTEL message payloads.
+     *
+     * Defaults to the value of the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`
+     * env var (`true`/`1`/`yes` => `"full"`, `"summary"` => `"summary"`).
+     */
+    readonly captureMessageContent?: TelemetryContentCapture;
+    /** Extra attributes merged onto every emitted span. */
+    readonly attributes?: Attributes;
+    /**
+     * Attribute resolver merged onto every emitted span after static
+     * `attributes` and before span-specific attributes. Use this for ambient
+     * run, tenant, deployment, or request metadata.
+     */
+    readonly resolveAttributes?: (ctx: TelemetryAttributeContext) => Attributes | undefined;
+    /** Agent identity stamped onto invoke_agent + propagated to children. */
+    readonly agent?: AgentIdentity;
+    /**
+     * Conversation identifier. When omitted, the loop falls back to
+     * `AgentLoopConfig.sessionId` for the `gen_ai.conversation.id` attribute.
+     */
+    readonly conversationId?: string;
+    /**
+     * Per-step cost estimator. Synchronous on purpose — runs inside the chat
+     * span's finish path. Return `undefined` to emit no cost attribute.
+     */
+    readonly costEstimator?: (input: CostEstimatorContext) => CostEstimate | undefined;
+    /** Called after cost estimation for a chat step. */
+    readonly onCostDelta?: (delta: CostDelta) => void;
+    /**
+     * Fired once per chat step that produced usage, regardless of whether a
+     * {@link costEstimator} is configured. Use this for usage-only metrics
+     * pipelines (token counters, cache-hit ratios) without paying the cost of
+     * estimating dollars per call.
+     *
+     * **Non-fatal.** Synchronous and asynchronous failures are caught, surfaced
+     * via {@link onTelemetryWarning}, and swallowed.
+     */
+    readonly onChatUsage?: (event: ChatUsageEvent) => void | Promise<void>;
+    /** Override provider labels before they are emitted or passed to cost hooks. */
+    readonly normalizeProvider?: (provider: string | undefined) => string | undefined;
+    /** Override agent names before they are emitted on spans. */
+    readonly normalizeAgentName?: (name: string | undefined) => string | undefined;
+    /** Override the default bounded JSON serializers used by summary capture. */
+    readonly contentSerializer?: TelemetryContentSerializer;
+    /**
+     * Called immediately after a span starts. Use to stamp request-side
+     * context (user id, deployment id, route name) without forking the loop.
+     */
+    readonly onSpanStart?: (ctx: TelemetryHookContext) => void;
+    /**
+     * Called just before `span.end()`. Use to stamp response-side context
+     * that depends on the final result.
+     */
+    readonly onSpanEnd?: (ctx: TelemetryHookContext) => void;
+    /**
+     * Fired once per `invoke_agent`, immediately after the run-level summary
+     * is built and aggregate attributes are stamped on the `invoke_agent`
+     * span. Use this to persist, log, or forward the {@link AgentRunSummary} /
+     * {@link AgentRunCoverage} value without parsing OTEL spans.
+     *
+     * **Non-fatal.** Exceptions thrown from this callback are caught, logged
+     * via `console.warn`, and swallowed — a misbehaving telemetry consumer can
+     * NEVER turn a successful agent run into a failed one.
+     */
+    readonly onRunEnd?: (summary: AgentRunSummary, coverage: AgentRunCoverage) => void;
+    /** Receives non-fatal telemetry callback failures and host-defined warnings. */
+    readonly onTelemetryWarning?: (warning: AgentTelemetryWarning) => void;
+}
+/**
+ * Public handle used internally to thread the resolved tracer + config
+ * through the loop. Constructed once per `agentLoop` invocation.
+ */
+export interface AgentTelemetry {
+    readonly config: AgentTelemetryConfig;
+    readonly tracer: Tracer;
+    readonly captureMessageContent: boolean;
+    readonly contentCapture: ResolvedTelemetryContentCapture;
+    readonly conversationId: string | undefined;
+    readonly agent: AgentIdentity | undefined;
+    /** Per-invocation event collector. See {@link AgentRunCollector}. */
+    readonly collector: AgentRunCollector;
+}
+/** Lazily resolve the {@link AgentTelemetry} handle. Returns `undefined` when disabled. */
+export declare function resolveTelemetry(config: AgentTelemetryConfig | undefined, sessionId: string | undefined): AgentTelemetry | undefined;
+export declare function recordTelemetryWarning(telemetry: AgentTelemetry | undefined, warning: AgentTelemetryWarning): void;
+/**
+ * Start the outer `invoke_agent` span that wraps a full `runLoop` invocation.
+ * Returns `undefined` when telemetry is disabled.
+ */
+export declare function startInvokeAgentSpan(telemetry: AgentTelemetry | undefined, model: Model): Span | undefined;
+/** Stamp the final step count on the `invoke_agent` span. */
+export declare function applyInvokeAgentFinish(span: Span | undefined, stepCount: number): void;
+/**
+ * Start a `chat` span representing one provider call. Parented under the
+ * supplied `invoke_agent` span (or whatever is active if none is passed).
+ */
+export declare function startChatSpan(telemetry: AgentTelemetry | undefined, model: Model, options: {
+    readonly parent?: Span;
+    readonly stepNumber: number;
+    readonly request: ChatRequestSnapshot;
+}): Span | undefined;
+/** Mutable snapshot of every request-side field worth recording. */
+export interface ChatRequestSnapshot {
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly topK?: number;
+    readonly frequencyPenalty?: number;
+    readonly presencePenalty?: number;
+    readonly stopSequences?: readonly string[];
+    readonly seed?: number;
+    readonly serviceTier?: ServiceTier;
+    readonly reasoningEffort?: string;
+    readonly toolChoice?: ToolChoice;
+    readonly tools?: readonly {
+        readonly name: string;
+    }[];
+    readonly systemPrompt?: readonly string[];
+    readonly messages?: readonly Message[];
+}
+/**
+ * Stamp the final response onto a chat span, fire the cost estimator hook,
+ * and end the span. No-op when `span` is undefined.
+ */
+export declare function finishChatSpan(telemetry: AgentTelemetry | undefined, span: Span | undefined, message: AssistantMessage, options: {
+    readonly stepNumber: number;
+    readonly serviceTier?: ServiceTier;
+    readonly responseHeaders?: Readonly<Record<string, string>>;
+    readonly baseUrl?: string;
+}): Promise<void>;
+/**
+ * Record a chat that failed before producing a final `AssistantMessage`
+ * (e.g. the provider stream threw mid-iteration). Mirrors `finishChatSpan`'s
+ * span-end side effects and pushes a failed `ChatRecord` to the collector so
+ * the run summary still reflects the failed step.
+ */
+export declare function failChatSpan(telemetry: AgentTelemetry | undefined, span: Span | undefined, options: {
+    readonly errorObject: unknown;
+    readonly errorType?: string;
+    readonly responseHeaders?: Readonly<Record<string, string>>;
+    readonly baseUrl?: string;
+}): void;
+/**
+ * Result of {@link detectGatewayFromHeaders}. `callId` and `routedTo` are
+ * populated only when the gateway surfaces them; consumers should treat
+ * `undefined` as "unknown for this gateway" rather than "no value".
+ */
+export interface GatewayHeaderDetection {
+    readonly name: string;
+    readonly callId: string | undefined;
+    readonly routedTo: string | undefined;
+}
+/**
+ * Identify a known LLM gateway / proxy from response headers (LiteLLM,
+ * Helicone, Portkey). Returns `undefined` when no recognizable pattern is
+ * present so direct-API traffic stays unaffected.
+ *
+ * Header keys are matched case-insensitively against the lowercased map that
+ * {@link ProviderResponseMetadata.headers} produces.
+ */
+export declare function detectGatewayFromHeaders(headers: Readonly<Record<string, string>> | undefined): GatewayHeaderDetection | undefined;
+export interface ManualChatToolCallTelemetry {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly input?: unknown;
+}
+export interface ManualChatTelemetryOptions {
+    readonly span?: Span;
+    readonly parent?: Span;
+    readonly model: Model;
+    readonly usage?: Usage;
+    readonly finishReason?: StopReason;
+    readonly serviceTier?: ServiceTier;
+    readonly stepNumber?: number;
+    readonly responseId?: string;
+    readonly responseModel?: string;
+    readonly responseText?: string;
+    readonly responseToolCalls?: readonly ManualChatToolCallTelemetry[];
+    readonly attributes?: Attributes;
+    readonly responseHeaders?: Readonly<Record<string, string>>;
+    readonly endSpan?: boolean;
+}
+export declare function recordManualChatTelemetry(telemetry: AgentTelemetry | undefined, options: ManualChatTelemetryOptions): Promise<Span | undefined>;
+/**
+ * Options accepted by {@link instrumentedCompleteSimple}. Mirrors the
+ * `streamAssistantResponse` chat-span lifecycle for oneshot LLM calls
+ * (compaction summaries, handoff document, branch summary, inspect_image).
+ */
+export interface InstrumentedChatSpanOptions {
+    readonly telemetry: AgentTelemetry | undefined;
+    /** Optional explicit parent span. Defaults to `context.active()`. */
+    readonly parent?: Span;
+    /** Step index recorded on the span; defaults to `-1` for non-loop calls. */
+    readonly stepNumber?: number;
+    /**
+     * Tag stamped onto `pi.gen_ai.oneshot.kind`. Values used by the agent:
+     * `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`,
+     * `handoff`, `branch_summary`, `inspect_image`. Free-form to allow callers
+     * outside this package to add new kinds without bumping the helper.
+     */
+    readonly oneshotKind?: string;
+    /** Extra span attributes applied verbatim. */
+    readonly attributes?: Attributes;
+    /**
+     * Override for the underlying {@link completeSimple} call. Defaults to
+     * `completeSimple` from `@gajae-code/ai`. Use to retain a test injection
+     * seam while still going through the chat-span lifecycle.
+     */
+    readonly completeImpl?: <TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions) => Promise<AssistantMessage>;
+}
+/**
+ * Wrap a {@link completeSimple} round-trip with the same chat-span lifecycle
+ * the agent loop uses for streamed turns: `startChatSpan` → run inside the
+ * active span → `finishChatSpan` on success, `failChatSpan` on throw.
+ *
+ * Short-circuits when `telemetry` is `undefined` so cost / overhead stays at
+ * zero for installations without an OTEL SDK.
+ */
+export declare function instrumentedCompleteSimple<TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions, span: InstrumentedChatSpanOptions): Promise<AssistantMessage>;
+/**
+ * Start an `execute_tool` span representing one tool invocation. Parented
+ * under the supplied `invoke_agent` span by default — pass `parent` to
+ * override.
+ */
+export declare function startExecuteToolSpan(telemetry: AgentTelemetry | undefined, options: {
+    readonly tool: AgentTool | undefined;
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly args: unknown;
+    readonly parent?: Span;
+}): Span | undefined;
+/**
+ * End an `execute_tool` span. Pass `status` to specify the terminal status
+ * explicitly (`"ok" | "error" | "skipped" | "blocked" | "timeout" |
+ * "aborted"`); when omitted, `status` is derived from `isError`. Passing
+ * `errorObject` (the thrown value) additionally records an exception with
+ * stack.
+ */
+export declare function finishExecuteToolSpan(telemetry: AgentTelemetry | undefined, span: Span | undefined, options: {
+    readonly result?: unknown;
+    readonly isError: boolean;
+    readonly status?: ToolStatus;
+    readonly errorMessage?: string;
+    readonly errorObject?: unknown;
+    readonly toolCallId: string;
+    readonly toolName: string;
+}): void;
+/** Span attribute carrying the terminal {@link ToolStatus}. */
+export declare const EXECUTE_TOOL_STATUS_ATTR = PiGenAIAttr.ToolStatus;
+/**
+ * Record a tool that bypassed the span lifecycle entirely (pre-run
+ * interrupt, post-execution tail sweep for calls that never produced a
+ * result message). The LLM still asked for the tool, so it counts toward
+ * coverage and toward the relevant `tools.<status>` counter; no span is
+ * emitted because the loop never started one.
+ */
+export declare function recordSkippedTool(telemetry: AgentTelemetry | undefined, options: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly status: Extract<ToolStatus, "skipped" | "aborted" | "error">;
+}): void;
+/**
+ * End an `invoke_agent` span. Snapshots the run collector, stamps aggregate
+ * `gen_ai.agent.*` attributes on the span, fires the non-fatal
+ * {@link AgentTelemetryConfig.onRunEnd} hook, then records any uncaught
+ * error and ends the span.
+ */
+export declare function finishInvokeAgentSpan(telemetry: AgentTelemetry | undefined, span: Span | undefined, options: {
+    readonly stepCount: number;
+    readonly errorObject?: unknown;
+}): {
+    readonly summary: AgentRunSummary;
+    readonly coverage: AgentRunCoverage;
+} | undefined;
+/**
+ * Invoke {@link AgentTelemetryConfig.onRunEnd} on `telemetry` if set. Throws
+ are caught and logged via `console.warn` — telemetry callbacks NEVER turn a
+ * successful agent run into a failed one. Idempotent at the call site via
+ * {@link AgentRunCollector.markRunEnded}; callers must check that before
+ * calling this helper.
+ */
+export declare function fireOnRunEnd(telemetry: AgentTelemetry, summary: AgentRunSummary, coverage: AgentRunCoverage): void;
+/** Aggregate `pi.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
+export declare const enum PiGenAIAggregateAttr {
+    ChatsCount = "pi.gen_ai.agent.chats.count",
+    ChatsTotalLatencyMs = "pi.gen_ai.agent.chats.total_latency_ms",
+    ChatsStopReasonPrefix = "pi.gen_ai.agent.chats.stop_reason.",
+    ToolsCount = "pi.gen_ai.agent.tools.count",
+    ToolsOkCount = "pi.gen_ai.agent.tools.ok.count",
+    ToolsErrorCount = "pi.gen_ai.agent.tools.error.count",
+    ToolsSkippedCount = "pi.gen_ai.agent.tools.skipped.count",
+    ToolsBlockedCount = "pi.gen_ai.agent.tools.blocked.count",
+    ToolsTimeoutCount = "pi.gen_ai.agent.tools.timeout.count",
+    ToolsAbortedCount = "pi.gen_ai.agent.tools.aborted.count",
+    ToolsTotalLatencyMs = "pi.gen_ai.agent.tools.total_latency_ms",
+    ToolsInvoked = "pi.gen_ai.agent.tools.invoked",
+    ToolsAvailable = "pi.gen_ai.agent.tools.available",
+    ToolsUnused = "pi.gen_ai.agent.tools.unused",
+    UsageInputTokensTotal = "pi.gen_ai.agent.usage.input_tokens.total",
+    UsageOutputTokensTotal = "pi.gen_ai.agent.usage.output_tokens.total",
+    UsageCacheReadInputTokensTotal = "pi.gen_ai.agent.usage.cache_read.input_tokens.total",
+    UsageCacheCreationInputTokensTotal = "pi.gen_ai.agent.usage.cache_creation.input_tokens.total",
+    UsageReasoningOutputTokensTotal = "pi.gen_ai.agent.usage.reasoning.output_tokens.total",
+    UsageTotalTokensTotal = "pi.gen_ai.agent.usage.total_tokens.total",
+    CostEstimatedUsdTotal = "pi.gen_ai.agent.cost.estimated_usd.total",
+    ErrorsCount = "pi.gen_ai.agent.errors.count"
+}
+/**
+ * Run `fn` with `span` activated on the OTEL context. Spans created
+ * downstream (provider HTTP clients, MCP tools, user code) attach as
+ * children. No-op when `span` is undefined.
+ *
+ * Required because `tracer.startSpan` creates the span object but does not
+ * activate it — without this wrapper, downstream spans attach to whatever
+ * context was active before and the parent linkage we advertise is lost.
+ */
+export declare function runInActiveSpan<T>(span: Span | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * Emit a one-shot `handoff` span describing a transition between two named
+ * agents. Pass `parent` to make the span a child of an in-flight
+ * invoke_agent span; otherwise the active context's span is used.
+ */
+export declare function recordHandoff(telemetry: AgentTelemetry | undefined, options: {
+    readonly fromAgent: AgentIdentity | undefined;
+    readonly toAgent: AgentIdentity;
+    readonly parent?: Span;
+    readonly attributes?: Attributes;
+}): void;
+/**
+ * Set a single attribute on a possibly-undefined span. Use when the caller
+ * needs to attach context outside the standard helpers without a branch.
+ */
+export declare function setSpanAttribute(span: Span | undefined, key: string, value: AttributeValue): void;
+/** Re-exports so consumers can write hooks without depending on @opentelemetry/api directly. */
+export { type Attributes, type Span, SpanKind, SpanStatusCode, type Tracer, trace };

package/dist/types/thinking.d.ts

@@ -0,0 +1,17 @@
+import { Effort } from "@gajae-code/ai";
+/**
+ * Agent-local thinking selector.
+ *
+ * `off` disables reasoning, while `inherit` defers to a higher-level selector.
+ */
+export declare const ThinkingLevel: {
+    readonly Inherit: "inherit";
+    readonly Off: "off";
+    readonly Minimal: Effort.Minimal;
+    readonly Low: Effort.Low;
+    readonly Medium: Effort.Medium;
+    readonly High: Effort.High;
+    readonly XHigh: Effort.XHigh;
+};
+export type ThinkingLevel = (typeof ThinkingLevel)[keyof typeof ThinkingLevel];
+export type ResolvedThinkingLevel = Exclude<ThinkingLevel, "inherit">;