@frontmcp/observability 0.0.1 → 1.0.0

package/otel/otel.types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * OpenTelemetry semantic attributes for FrontMCP.
+ *
+ * Three attribute namespaces:
+ * - `mcp.*`       — MCP protocol-level attributes (interoperable with other MCP implementations)
+ * - `frontmcp.*`  — FrontMCP-specific attributes (vendor namespace per OTel conventions)
+ * - Standard OTel — `http.*`, `rpc.*`, `url.*`, `enduser.*`, `server.*`
+ */
+export declare const McpAttributes: {
+    /** MCP protocol method name (e.g., "tools/call", "resources/read") */
+    readonly METHOD_NAME: "mcp.method.name";
+    /** MCP session identifier (hashed for privacy) */
+    readonly SESSION_ID: "mcp.session.id";
+    /** MCP resource URI */
+    readonly RESOURCE_URI: "mcp.resource.uri";
+    /** MCP component type: "tool" | "resource" | "prompt" | "resource_template" */
+    readonly COMPONENT_TYPE: "mcp.component.type";
+    /** MCP component key (e.g., "tool:get_weather", "resource:config://db") */
+    readonly COMPONENT_KEY: "mcp.component.key";
+};
+export declare const FrontMcpAttributes: {
+    /** Scope identifier */
+    readonly SCOPE_ID: "frontmcp.scope.id";
+    /** Server/scope name */
+    readonly SERVER_NAME: "frontmcp.server.name";
+    /** Tool name being executed */
+    readonly TOOL_NAME: "frontmcp.tool.name";
+    /** Tool owner class name */
+    readonly TOOL_OWNER: "frontmcp.tool.owner";
+    /** Resource URI being read */
+    readonly RESOURCE_URI: "frontmcp.resource.uri";
+    /** Resource name */
+    readonly RESOURCE_NAME: "frontmcp.resource.name";
+    /** Prompt name being invoked */
+    readonly PROMPT_NAME: "frontmcp.prompt.name";
+    /** Flow name (e.g., "tools:call-tool") */
+    readonly FLOW_NAME: "frontmcp.flow.name";
+    /** Flow stage (e.g., "willExecute") */
+    readonly FLOW_STAGE: "frontmcp.flow.stage";
+    /** Hook stage (e.g., "willValidateInput") */
+    readonly HOOK_STAGE: "frontmcp.hook.stage";
+    /** Hook owner identifier */
+    readonly HOOK_OWNER: "frontmcp.hook.owner";
+    /** Hashed session ID (for trace correlation, not the real session ID) */
+    readonly SESSION_ID_HASH: "frontmcp.session.id_hash";
+    /** Authentication type */
+    readonly AUTH_TYPE: "frontmcp.auth.type";
+    /** Request identifier */
+    readonly REQUEST_ID: "frontmcp.request.id";
+    /** Provider type (e.g., "local", "adapter", "remote") */
+    readonly PROVIDER_TYPE: "frontmcp.provider.type";
+    /** Delegation — original name before namespacing */
+    readonly DELEGATE_ORIGINAL_NAME: "frontmcp.delegate.original_name";
+    /** Transport type: "legacy-sse" | "streamable-http" | "stateless-http" */
+    readonly TRANSPORT_TYPE: "frontmcp.transport.type";
+    /** Transport request type: "initialize" | "message" | "elicitResult" | "sseListener" | "extApps" */
+    readonly TRANSPORT_REQUEST_TYPE: "frontmcp.transport.request_type";
+    /** Session protocol */
+    readonly SESSION_PROTOCOL: "frontmcp.session.protocol";
+    /** Whether a new session was created */
+    readonly SESSION_CREATED: "frontmcp.session.created";
+    /** Auth mode: "public" | "transparent" | "orchestrated" */
+    readonly AUTH_MODE: "frontmcp.auth.mode";
+    /** Auth result: "authorized" | "unauthorized" | "anonymous" */
+    readonly AUTH_RESULT: "frontmcp.auth.result";
+    /** OAuth grant type: "authorization_code" | "refresh_token" | "anonymous" */
+    readonly OAUTH_GRANT_TYPE: "frontmcp.oauth.grant_type";
+    /** Elicitation request ID */
+    readonly ELICITATION_ID: "frontmcp.elicitation.id";
+    /** Agent name */
+    readonly AGENT_NAME: "frontmcp.agent.name";
+    /** Agent execution loop iterations */
+    readonly AGENT_ITERATIONS: "frontmcp.agent.iterations";
+    /** Agent execution duration in ms */
+    readonly AGENT_EXECUTION_DURATION_MS: "frontmcp.agent.execution_duration_ms";
+    /** Total tools registered at startup */
+    readonly STARTUP_TOOLS_COUNT: "frontmcp.startup.tools_count";
+    /** Total resources registered at startup */
+    readonly STARTUP_RESOURCES_COUNT: "frontmcp.startup.resources_count";
+    /** Total prompts registered at startup */
+    readonly STARTUP_PROMPTS_COUNT: "frontmcp.startup.prompts_count";
+    /** Total plugins loaded at startup */
+    readonly STARTUP_PLUGINS_COUNT: "frontmcp.startup.plugins_count";
+    /** Startup initialization duration in ms */
+    readonly STARTUP_DURATION_MS: "frontmcp.startup.duration_ms";
+};
+export declare const HttpAttributes: {
+    readonly METHOD: "http.request.method";
+    readonly STATUS_CODE: "http.response.status_code";
+    readonly URL_PATH: "url.path";
+    readonly URL_FULL: "url.full";
+    readonly URL_SCHEME: "url.scheme";
+    readonly SERVER_ADDRESS: "server.address";
+    readonly SERVER_PORT: "server.port";
+};
+export declare const RpcAttributes: {
+    /** RPC system — "mcp" for MCP protocol */
+    readonly SYSTEM: "rpc.system";
+    /** RPC service name */
+    readonly SERVICE: "rpc.service";
+    /** RPC method */
+    readonly METHOD: "rpc.method";
+    /** JSON-RPC version */
+    readonly JSONRPC_VERSION: "rpc.jsonrpc.version";
+    /** JSON-RPC request ID */
+    readonly JSONRPC_REQUEST_ID: "rpc.jsonrpc.request_id";
+};
+export declare const EnduserAttributes: {
+    /** Client/user ID from auth token */
+    readonly ID: "enduser.id";
+    /** OAuth scopes (space-separated) */
+    readonly SCOPE: "enduser.scope";
+};
+/**
+ * OTel tracing configuration options.
+ */
+export interface TracingOptions {
+    /** Instrument HTTP request spans (default: true) */
+    httpSpans?: boolean;
+    /** Instrument tool/resource/prompt execution spans (default: true) */
+    executionSpans?: boolean;
+    /** Instrument individual hook spans — verbose (default: false) */
+    hookSpans?: boolean;
+    /** Instrument outbound fetch() calls (default: true) */
+    fetchSpans?: boolean;
+    /** Record flow stages as span events (default: true) */
+    flowStageEvents?: boolean;
+    /** Instrument transport flows — SSE, streamable-http, stateless-http (default: true) */
+    transportSpans?: boolean;
+    /** Instrument auth verify/session verify flows (default: true) */
+    authSpans?: boolean;
+    /** Instrument OAuth flows — token, authorize, callback, register (default: true) */
+    oauthSpans?: boolean;
+    /** Instrument elicitation request/result flows (default: true) */
+    elicitationSpans?: boolean;
+    /** Emit startup telemetry report on first request (default: true) */
+    startupReport?: boolean;
+}
+/**
+ * OTel setup configuration for the convenience setupOTel() function.
+ */
+export interface OTelSetupOptions {
+    /** Service name for the OTel resource (default: 'frontmcp-server') */
+    serviceName?: string;
+    /** Exporter type */
+    exporter?: 'otlp' | 'console';
+    /** OTLP endpoint URL (default: 'http://localhost:4318') */
+    endpoint?: string;
+    /** Service version */
+    serviceVersion?: string;
+}

package/otel/spans/auth.span.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Auth Span — authentication and session verification instrumentation.
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface AuthSpanOptions {
+    /** Auth flow name (e.g., "auth:verify", "session:verify") */
+    flowName: string;
+    /** Parent OTel context */
+    parentContext?: Context;
+}
+/**
+ * Start an auth span.
+ *
+ * Span name: "auth {flowName}"
+ */
+export declare function startAuthSpan(tracer: Tracer, options: AuthSpanOptions): {
+    span: Span;
+    context: Context;
+};
+/**
+ * Set auth mode on the span.
+ */
+export declare function setAuthMode(span: Span, mode: string): void;
+/**
+ * Set auth result on the span.
+ */
+export declare function setAuthResult(span: Span, result: string): void;

package/otel/spans/fetch.span.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fetch Span — outbound HTTP client instrumentation.
+ *
+ * Wraps fetch() calls made via FrontMcpContext.fetch() to create
+ * client HTTP spans following OTel HTTP semantic conventions.
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface FetchSpanOptions {
+    /** HTTP method */
+    method: string;
+    /** Full URL */
+    url: string;
+    /** Parent OTel context */
+    parentContext?: Context;
+}
+/**
+ * Start an outbound HTTP client span.
+ *
+ * Span name follows OTel convention: "{method}"
+ */
+export declare function startFetchSpan(tracer: Tracer, options: FetchSpanOptions): {
+    span: Span;
+    context: Context;
+};
+/**
+ * Set the response status on a fetch span.
+ */
+export declare function setFetchResponseStatus(span: Span, statusCode: number): void;

package/otel/spans/hook.span.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hook Span — FrontMCP hook execution instrumentation.
+ *
+ * By default, hook executions are recorded as span events (not child spans)
+ * to keep trace depth manageable. When hookSpans is enabled, each hook
+ * gets its own child span.
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface HookSpanOptions {
+    /** Hook stage name (e.g., "willExecute") */
+    stage: string;
+    /** Hook owner identifier */
+    owner?: string;
+    /** Flow name (e.g., "tools:call-tool") */
+    flowName?: string;
+    /** Parent OTel context */
+    parentContext?: Context;
+}
+/**
+ * Record a hook execution as a span event on the parent span.
+ *
+ * This is the default behavior — lightweight, no trace depth increase.
+ */
+export declare function recordHookEvent(parentSpan: Span, stage: string, owner?: string): void;
+/**
+ * Start a dedicated hook span (verbose mode).
+ *
+ * Only used when hookSpans is enabled in the tracing options.
+ */
+export declare function startHookSpan(tracer: Tracer, options: HookSpanOptions): {
+    span: Span;
+    context: Context;
+};

package/otel/spans/http-server.span.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP Server Span — follows OTel HTTP semantic conventions.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/http/http-spans/
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface HttpServerSpanOptions {
+    method: string;
+    path: string;
+    scheme?: string;
+    serverAddress?: string;
+    serverPort?: number;
+    scopeId?: string;
+    requestId?: string;
+    parentContext?: Context;
+}
+/**
+ * Start an HTTP server span.
+ *
+ * Span name follows OTel convention: "{method} {path}"
+ */
+export declare function startHttpServerSpan(tracer: Tracer, options: HttpServerSpanOptions): {
+    span: Span;
+    context: Context;
+};
+/**
+ * Set the HTTP response status code on a server span.
+ */
+export declare function setHttpResponseStatus(span: Span, statusCode: number): void;

package/otel/spans/index.d.ts

@@ -0,0 +1,23 @@
+export { startSpan, endSpanOk, endSpanError, withSpan } from './span.utils';
+export type { StartSpanOptions } from './span.utils';
+export { startHttpServerSpan, setHttpResponseStatus } from './http-server.span';
+export type { HttpServerSpanOptions } from './http-server.span';
+export { startRpcSpan } from './rpc.span';
+export type { RpcSpanOptions } from './rpc.span';
+export { startToolSpan } from './tool.span';
+export type { ToolSpanOptions } from './tool.span';
+export { startResourceSpan } from './resource.span';
+export type { ResourceSpanOptions } from './resource.span';
+export { startPromptSpan } from './prompt.span';
+export type { PromptSpanOptions } from './prompt.span';
+export { recordHookEvent, startHookSpan } from './hook.span';
+export type { HookSpanOptions } from './hook.span';
+export { startFetchSpan, setFetchResponseStatus } from './fetch.span';
+export type { FetchSpanOptions } from './fetch.span';
+export { startTransportSpan, setTransportRequestType } from './transport.span';
+export type { TransportSpanOptions } from './transport.span';
+export { startAuthSpan, setAuthMode, setAuthResult } from './auth.span';
+export type { AuthSpanOptions } from './auth.span';
+export { emitStartupReport } from './startup.span';
+export { PrettySpanExporter } from './pretty-span-exporter';
+export type { StartupTelemetryData } from './startup.span';

package/otel/spans/pretty-span-exporter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PrettySpanExporter — human-readable span output for development.
+ *
+ * Instead of dumping raw JSON (like ConsoleSpanExporter), formats spans
+ * as compact, colored one-liners with key attributes and timing.
+ *
+ * Example output:
+ *   ↳ SPAN tools/call [36008509] 8ms rpc.system=mcp mcp.session.id=5bfdd288
+ *   ↳ SPAN tool get_weather [36008509] 5ms mcp.component.type=tool enduser.id=client-42
+ */
+import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { ExportResult } from '@opentelemetry/core';
+export declare class PrettySpanExporter implements SpanExporter {
+    private useAnsi;
+    constructor();
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    private format;
+}

package/otel/spans/prompt.span.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prompt Span — FrontMCP prompt invocation instrumentation.
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface PromptSpanOptions {
+    /** Prompt name */
+    name: string;
+    /** Parent OTel context */
+    parentContext?: Context;
+}
+/**
+ * Start a prompt invocation span.
+ *
+ * Span name: "prompt {name}"
+ */
+export declare function startPromptSpan(tracer: Tracer, options: PromptSpanOptions): {
+    span: Span;
+    context: Context;
+};

package/otel/spans/resource.span.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resource Read Span — FrontMCP resource read instrumentation.
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface ResourceSpanOptions {
+    /** Resource URI */
+    uri: string;
+    /** Resource name */
+    name?: string;
+    /** Parent OTel context */
+    parentContext?: Context;
+}
+/**
+ * Start a resource read span.
+ *
+ * Span name: "resource {uri}"
+ */
+export declare function startResourceSpan(tracer: Tracer, options: ResourceSpanOptions): {
+    span: Span;
+    context: Context;
+};

package/otel/spans/rpc.span.d.ts

@@ -0,0 +1,33 @@
+/**
+ * RPC Span — follows OTel RPC semantic conventions for MCP.
+ *
+ * MCP is treated as its own RPC system (`rpc.system = "mcp"`)
+ * rather than generic JSON-RPC, following the FastMCP convention
+ * for better filtering in trace backends.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface RpcSpanOptions {
+    /** MCP method (e.g., "tools/call", "resources/read") */
+    method: string;
+    /** JSON-RPC request ID */
+    requestId?: string | number;
+    /** Scope ID */
+    scopeId?: string;
+    /** Server/service name */
+    serviceName?: string;
+    /** Hashed session ID for trace correlation */
+    sessionIdHash?: string;
+    /** Parent OTel context */
+    parentContext?: Context;
+}
+/**
+ * Start an RPC span for an MCP method invocation.
+ *
+ * Span name follows OTel convention: "{rpc.method}"
+ */
+export declare function startRpcSpan(tracer: Tracer, options: RpcSpanOptions): {
+    span: Span;
+    context: Context;
+};

package/otel/spans/span.utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Span utility helpers for creating and managing OTel spans.
+ */
+import { type Tracer, type Span, type Context, SpanKind } from '@opentelemetry/api';
+/**
+ * Options for starting a span.
+ */
+export interface StartSpanOptions {
+    /** Span name (follows OTel naming conventions) */
+    name: string;
+    /** Span kind (default: INTERNAL) */
+    kind?: SpanKind;
+    /** Span attributes */
+    attributes?: Record<string, string | number | boolean>;
+    /** Parent OTel context (default: current active context) */
+    parentContext?: Context;
+}
+/**
+ * Start a new span using the provided tracer.
+ *
+ * @returns The new span and the context with the span set as active.
+ */
+export declare function startSpan(tracer: Tracer, options: StartSpanOptions): {
+    span: Span;
+    context: Context;
+};
+/**
+ * End a span with success status.
+ */
+export declare function endSpanOk(span: Span): void;
+/**
+ * End a span with error status.
+ */
+export declare function endSpanError(span: Span, error: Error | string): void;
+/**
+ * Run a function within a span, automatically handling success/error.
+ */
+export declare function withSpan<T>(tracer: Tracer, options: StartSpanOptions, fn: (span: Span) => Promise<T>): Promise<T>;

package/otel/spans/startup.span.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Startup Report Span — emits server initialization telemetry.
+ *
+ * Created as a standalone span after scope initialization completes.
+ * Records counts of registered components and initialization duration.
+ */
+import { type Tracer } from '@opentelemetry/api';
+export interface StartupTelemetryData {
+    /** Total tools registered */
+    toolsCount: number;
+    /** Total resources registered */
+    resourcesCount: number;
+    /** Total prompts registered */
+    promptsCount: number;
+    /** Total plugins loaded */
+    pluginsCount: number;
+    /** Initialization duration in ms */
+    durationMs: number;
+    /** Scope/server name */
+    scopeId?: string;
+}
+/**
+ * Emit a startup telemetry report as a standalone span.
+ *
+ * Creates and immediately ends a span with all startup metrics
+ * as attributes. Call this after scope.initialize() completes.
+ */
+export declare function emitStartupReport(tracer: Tracer, data: StartupTelemetryData): void;

package/otel/spans/tool.span.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tool Execution Span — FrontMCP tool invocation instrumentation.
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface ToolSpanOptions {
+    /** Tool name */
+    name: string;
+    /** Tool owner class name */
+    owner?: string;
+    /** Enduser ID (from auth token, e.g., client ID) */
+    enduserId?: string;
+    /** Enduser scopes (space-separated OAuth scopes) */
+    enduserScope?: string;
+    /** Parent OTel context */
+    parentContext?: Context;
+}
+/**
+ * Start a tool execution span.
+ *
+ * Span name: "tool {name}"
+ */
+export declare function startToolSpan(tracer: Tracer, options: ToolSpanOptions): {
+    span: Span;
+    context: Context;
+};

package/otel/spans/transport.span.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Transport Span — SSE, Streamable HTTP, Stateless HTTP instrumentation.
+ *
+ * Created for each transport-level flow that handles session creation,
+ * protocol routing, and message dispatch.
+ */
+import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+export interface TransportSpanOptions {
+    /** Transport type: "legacy-sse" | "streamable-http" | "stateless-http" */
+    type: string;
+    /** Session tracing ID (hashed) */
+    sessionIdHash?: string;
+    /** Whether a new session was created */
+    sessionCreated?: boolean;
+    /** Parent OTel context */
+    parentContext?: Context;
+}
+/**
+ * Start a transport span.
+ *
+ * Span name: "transport {type}"
+ */
+export declare function startTransportSpan(tracer: Tracer, options: TransportSpanOptions): {
+    span: Span;
+    context: Context;
+};
+/**
+ * Set the request type on a transport span.
+ */
+export declare function setTransportRequestType(span: Span, requestType: string): void;

package/otel/trace-context-bridge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * TraceContext Bridge — maps between FrontMCP's TraceContext
+ * and OpenTelemetry's SpanContext.
+ *
+ * FrontMCP already has W3C Trace Context support in the SDK.
+ * This bridge allows OTel spans to be created as children of
+ * the existing trace, preserving the trace ID across the boundary.
+ */
+import { type SpanContext, type Context as OTelContext } from '@opentelemetry/api';
+/**
+ * Minimal TraceContext interface — matches the SDK's TraceContext type
+ * without importing it directly.
+ */
+export interface TraceContextLike {
+    traceId: string;
+    parentId: string;
+    traceFlags: number;
+    raw: string;
+}
+/**
+ * Convert a FrontMCP TraceContext to an OTel SpanContext.
+ *
+ * Maps:
+ * - traceId → traceId (32 hex chars)
+ * - parentId → spanId (16 hex chars)
+ * - traceFlags → traceFlags
+ *
+ * The resulting SpanContext is marked as remote (isRemote: true)
+ * since it originated from an incoming request.
+ */
+export declare function frontmcpToOTelSpanContext(tc: TraceContextLike): SpanContext;
+/**
+ * Convert an OTel SpanContext back to a FrontMCP TraceContext.
+ */
+export declare function otelToFrontmcpContext(sc: SpanContext): TraceContextLike;
+/**
+ * Create an OTel Context with the FrontMCP TraceContext as the
+ * active remote parent span. All child spans created within
+ * this context will share the same traceId.
+ */
+export declare function createOTelContextFromTrace(tc: TraceContextLike): OTelContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/observability",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "OpenTelemetry instrumentation, structured JSON logging, and request log objects for FrontMCP",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",

package/plugin/index.d.ts

@@ -0,0 +1,3 @@
+export { default as ObservabilityPlugin } from './observability.plugin';
+export type { ObservabilityPluginOptions, ObservabilityPluginOptionsInput, ObservabilityLoggingOptions, } from './observability.plugin.types';
+export { sessionTracingId, SPAN_KEY, SPAN_CTX_KEY, EXEC_SPAN_KEY, ACTIVE_SPAN_KEY, ACTIVE_OTEL_CTX_KEY, reportStartup, } from './observability.hooks';

package/plugin/observability.hooks.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ObservabilityHooks — comprehensive auto-instrumentation for FrontMCP.
+ *
+ * Provides full-depth visibility across the ENTIRE FrontMCP system:
+ * - HTTP request flow (every stage: traceRequest → auth → route → transport → finalize)
+ * - Tool/Resource/Prompt/Agent execution (every flow stage as span events)
+ * - Auth flows (verify, session, OAuth token/authorize/callback)
+ * - Skill flows (search, load, HTTP endpoints)
+ * - Elicitation flows (request, result)
+ * - External fetch calls
+ * - Session lifecycle
+ * - Plugin initialization
+ *
+ * Architecture:
+ * - Single trace ID per request (from FrontMcpContext.traceContext)
+ * - Session tracing ID = truncated SHA-256 hash (not the real session ID)
+ * - Root span per flow type (HTTP, RPC, execution)
+ * - Every flow stage recorded as a timed span event
+ * - Error status propagated to parent spans
+ */
+import type { TracingOptions } from '../otel/otel.types';
+import { type StartupTelemetryData } from '../otel/spans/startup.span';
+/** Root span for the current flow (HTTP server span or RPC span) */
+export declare const SPAN_KEY: unique symbol;
+/** OTel context containing the root span (for child span parenting) */
+export declare const SPAN_CTX_KEY: unique symbol;
+/** Execution span (tool/resource/prompt/agent child span) */
+export declare const EXEC_SPAN_KEY: unique symbol;
+/** Active telemetry span — stored on FrontMcpContext.set() so TelemetryAccessor can read it */
+export declare const ACTIVE_SPAN_KEY: unique symbol;
+/** Active OTel context for child span parenting from TelemetryAccessor */
+export declare const ACTIVE_OTEL_CTX_KEY: unique symbol;
+/** Timestamp of the last recorded stage event */
+export declare const STAGE_TS_KEY: unique symbol;
+/**
+ * Generate a privacy-safe session tracing ID.
+ * 16-char truncated SHA-256 — sufficient for trace correlation,
+ * not reversible to the original session ID.
+ */
+export declare function sessionTracingId(sessionId: string): string;
+/** Minimal interface for flow context objects passed to hooks. */
+export interface FlowContextLike {
+    get?(key: symbol): unknown;
+    state?: Record<symbol | string, any>;
+}
+export declare function onHttpWillTrace(options: TracingOptions, flowCtx: any): void;
+export declare function onHttpWillAcquireQuota(flowCtx: any): void;
+export declare function onHttpDidAcquireQuota(flowCtx: any): void;
+export declare function onHttpWillCheckAuth(flowCtx: any): void;
+export declare function onHttpDidCheckAuth(flowCtx: any): void;
+export declare function onHttpWillRoute(flowCtx: any): void;
+export declare function onHttpDidRoute(flowCtx: any): void;
+export declare function onHttpDidFinalize(flowCtx: any): void;
+export declare function onToolWillParse(options: TracingOptions, flowCtx: any): void;
+export declare function onToolWillFindTool(flowCtx: any): void;
+export declare function onToolWillCheckAuth(flowCtx: any): void;
+export declare function onToolWillCreateContext(flowCtx: any): void;
+export declare function onToolWillValidateInput(flowCtx: any): void;
+export declare function onToolWillExecute(options: TracingOptions, flowCtx: any): void;
+export declare function onToolDidExecute(options: TracingOptions, flowCtx: any): void;
+export declare function onToolWillValidateOutput(flowCtx: any): void;
+export declare function onToolWillApplyUI(flowCtx: any): void;
+export declare function onToolDidFinalize(flowCtx: any): void;
+export declare function onResourceWillParse(options: TracingOptions, flowCtx: any): void;
+export declare function onResourceWillFind(flowCtx: any): void;
+export declare function onResourceWillExecute(options: TracingOptions, flowCtx: any): void;
+export declare function onResourceDidExecute(flowCtx: any): void;
+export declare function onResourceDidFinalize(flowCtx: any): void;
+export declare function onPromptWillParse(options: TracingOptions, flowCtx: any): void;
+export declare function onPromptWillFind(flowCtx: any): void;
+export declare function onPromptWillExecute(options: TracingOptions, flowCtx: any): void;
+export declare function onPromptDidExecute(flowCtx: any): void;
+export declare function onPromptDidFinalize(flowCtx: any): void;
+export declare function onAgentWillParse(options: TracingOptions, flowCtx: any): void;
+export declare function onAgentWillFind(flowCtx: any): void;
+export declare function onAgentWillExecute(options: TracingOptions, flowCtx: any): void;
+export declare function onAgentDidExecute(flowCtx: any): void;
+export declare function onAgentDidFinalize(flowCtx: any): void;
+export declare function onGenericFlowWillStart(flowName: string, options: TracingOptions, flowCtx: any): void;
+export declare function onGenericFlowStage(stageName: string, flowCtx: any): void;
+export declare function onGenericFlowDidFinalize(flowCtx: any): void;
+export declare function onTransportWillStart(transportType: string, options: TracingOptions, flowCtx: any): void;
+export declare function onTransportDidRoute(flowCtx: any): void;
+export declare function onTransportStage(stageName: string, flowCtx: any): void;
+export declare function onTransportDidFinalize(flowCtx: any): void;
+export declare function onAuthWillStart(flowName: string, options: TracingOptions, flowCtx: any): void;
+export declare function onAuthDidDetermineMode(flowCtx: any): void;
+export declare function onAuthStage(stageName: string, flowCtx: any): void;
+export declare function onAuthDidFinalize(flowCtx: any): void;
+export declare function wrapContextFetch(options: TracingOptions, flowCtx: any): void;
+export declare function onAgentDidExecuteEnrich(flowCtx: any): void;
+export declare function reportStartup(data: StartupTelemetryData): void;