veryfront 0.1.246 → 0.1.248

package/src/src/cache/keys/utils.ts

@@ -9,7 +9,7 @@
 import { VERSION } from "../../utils/version.js";
 import { withSpan } from "../../observability/tracing/otlp-setup.js";
 import { SpanNames } from "../../observability/tracing/span-names.js";
-import type { Span } from "@opentelemetry/api";
+import type { Span } from "../../observability/tracing/api-shim.js";
 
 import { cacheRegistry } from "../registry.js";
 

package/src/src/cache/registry.ts

@@ -2,7 +2,7 @@ import { rendererLogger } from "../utils/index.js";
 import { getRedisClient, isRedisConfigured } from "../utils/redis-client.js";
 import { withSpan } from "../observability/tracing/otlp-setup.js";
 import { SpanNames } from "../observability/tracing/span-names.js";
-import type { Span } from "@opentelemetry/api";
+import type { Span } from "../observability/tracing/api-shim.js";
 
 const logger = rendererLogger.component("cache-registry");
 

package/src/src/data/static-paths-fetcher.ts

@@ -2,7 +2,7 @@ import type { PageWithData, StaticPathsResult } from "./types.js";
 import { serverLogger } from "../utils/index.js";
 import { withSpan } from "../observability/tracing/otlp-setup.js";
 import { SpanNames } from "../observability/tracing/span-names.js";
-import type { Span } from "@opentelemetry/api";
+import type { Span } from "../observability/tracing/api-shim.js";
 
 const EMPTY_STATIC_PATHS_RESULT: StaticPathsResult = { paths: [], fallback: false };
 

package/src/src/embedding/upload-loader.ts

@@ -1,18 +1,13 @@
-import * as dntShim from "../../_dnt.shims.js";
-import { importKreuzberg } from "../platform/compat/opaque-deps.js";
-import { isDeno } from "../platform/compat/runtime.js";
-import { serverLogger } from "../utils/index.js";
-
-/** Maximum time to wait for document text extraction before aborting. */
-const EXTRACTION_TIMEOUT_MS = 30_000;
+import { tryResolve } from "../extensions/contracts.js";
+import type { NodeCompat } from "../extensions/interfaces/node-compat.js";
 
 /**
  * Extracts plain text from various upload formats.
  *
  * Text and CSV are handled inline (CSV uses a RAG-optimized format that
  * denormalizes headers into every row). All other formats (PDF, DOCX, XLSX,
- * PPTX, HTML, RTF, EPUB, etc.) are delegated to kreuzberg for extraction
- * inside a Worker thread so that hung WASM calls cannot block the server.
+ * PPTX, HTML, RTF, EPUB, etc.) are delegated to the `NodeCompat` extension
+ * contract, which owns kreuzberg and the Worker isolation on Deno.
  *
  * @example
  * ```ts
@@ -34,61 +29,17 @@ export async function loadUpload(buffer: ArrayBuffer, mimeType: string): Promise
     return new TextDecoder().decode(buffer);
   }
 
-  // Everything else (PDF, DOCX, XLSX, PPTX, HTML, XML, etc.) → kreuzberg
-  // Deno: run in a Worker thread to prevent hung WASM from blocking the server.
-  // Node/Bun: call kreuzberg directly (no global Worker; @kreuzberg/node uses
-  // native bindings that don't have the WASM hang issue).
-  if (isDeno) {
-    return extractInWorker(buffer, mimeType);
+  // Everything else (PDF, DOCX, XLSX, PPTX, HTML, XML, etc.) → NodeCompat.
+  // Synchronous registry check so the missing-extension error surfaces
+  // directly from `loadUpload()` rather than through a spawned Worker.
+  const nodeCompat = tryResolve<NodeCompat>("NodeCompat");
+  if (!nodeCompat?.extractInWorker) {
+    throw new Error(
+      "Document extraction requires the NodeCompat extension. " +
+        "Install @veryfront/ext-node-compat and add it to your extensions configuration.",
+    );
   }
-  return extractDirect(buffer, mimeType);
-}
-
-async function extractDirect(
-  buffer: ArrayBuffer,
-  mimeType: string,
-): Promise<string> {
-  const { extractBytes } = await importKreuzberg();
-  const result = await extractBytes(new Uint8Array(buffer), mimeType);
-  return result.content;
-}
-
-function extractInWorker(buffer: ArrayBuffer, mimeType: string): Promise<string> {
-  return new Promise<string>((resolve, reject) => {
-    const workerUrl = new URL("./upload-extraction-worker.ts", import.meta.url);
-    const worker = new Worker(workerUrl, { type: "module" });
-
-    const timer = dntShim.setTimeout(() => {
-      worker.terminate();
-      reject(
-        new Error(
-          `Text extraction timed out after ${
-            EXTRACTION_TIMEOUT_MS / 1000
-          }s — the file may be corrupted or unsupported`,
-        ),
-      );
-    }, EXTRACTION_TIMEOUT_MS);
-
-    worker.onmessage = (event: MessageEvent) => {
-      clearTimeout(timer);
-      worker.terminate();
-      const { content, error } = event.data;
-      if (error) {
-        reject(new Error(error));
-      } else {
-        resolve(content);
-      }
-    };
-
-    worker.onerror = (event) => {
-      clearTimeout(timer);
-      worker.terminate();
-      serverLogger.error("[upload-loader] Worker error:", event);
-      reject(new Error("Text extraction worker failed"));
-    };
-
-    worker.postMessage({ buffer, mimeType }, [buffer]);
-  });
+  return nodeCompat.extractInWorker(buffer, mimeType);
 }
 
 function extractCSV(buffer: ArrayBuffer): string {

package/src/src/errors/middleware/cli-error-boundary.ts

@@ -9,7 +9,7 @@
 import * as dntShim from "../../../_dnt.shims.js";
 
 
-import { trace } from "@opentelemetry/api";
+import { trace } from "../../observability/tracing/api-shim.js";
 import { VeryfrontError } from "../types.js";
 import { UNKNOWN_ERROR } from "../error-registry.js";
 import { getErrorMessage } from "../veryfront-error.js";

package/src/src/errors/middleware/http-error-boundary.ts

@@ -9,7 +9,7 @@
  */
 
 import type { Handler, HandlerContext, HandlerResult } from "../../types/index.js";
-import { trace } from "@opentelemetry/api";
+import { trace } from "../../observability/tracing/api-shim.js";
 import { PROBLEM_JSON_CONTENT_TYPE } from "../http-error.js";
 import { recordErrorCount } from "../../observability/metrics/index.js";
 import { attachErrorToActiveSpan } from "../tracing.js";

package/src/src/errors/tracing.ts

@@ -4,8 +4,8 @@
  * Attaches error metadata to spans for distributed tracing and error correlation.
  */
 
-import type { Span } from "@opentelemetry/api";
-import { SpanStatusCode } from "@opentelemetry/api";
+import type { Span } from "../observability/tracing/api-shim.js";
+import { SpanStatusCode } from "../observability/tracing/api-shim.js";
 import type { VeryfrontError } from "./types.js";
 
 /**
@@ -27,7 +27,7 @@ import type { VeryfrontError } from "./types.js";
  *
  * @example
  * ```typescript
- * import { trace } from "@opentelemetry/api";
+ * import { trace } from "#veryfront/observability/tracing/api-shim.ts";
  *
  * const span = trace.getActiveSpan();
  * if (span) {
@@ -68,7 +68,7 @@ export function attachErrorToSpan(error: VeryfrontError, span: Span): void {
  *
  * @example
  * ```typescript
- * import { trace } from "@opentelemetry/api";
+ * import { trace } from "#veryfront/observability/tracing/api-shim.ts";
  *
  * try {
  *   // ... operation that may throw

package/src/src/extensions/interfaces/index.ts

@@ -49,7 +49,7 @@ export type {
 } from "./auth-provider.js";
 
 // Tracing exporter
-export type { SpanData, TracingExporter } from "./tracing-exporter.js";
+export type { SpanData, TracerProvider, TracingExporter } from "./tracing-exporter.js";
 
 // AI model provider
 export type {
@@ -87,4 +87,9 @@ export type {
 } from "./schema-validator.js";
 
 // Node compatibility
-export type { NodeCompat } from "./node-compat.js";
+export type {
+  KreuzbergExtractor,
+  NodeCompat,
+  NodeCompatSqliteDatabase,
+  SqliteStatement,
+} from "./node-compat.js";

package/src/src/extensions/interfaces/node-compat.ts

@@ -6,20 +6,84 @@
  * @module extensions/interfaces/node-compat
  */
 
+/**
+ * Minimal interface for a prepared SQLite statement, compatible with
+ * `better-sqlite3`'s `Statement` shape.
+ */
+export interface SqliteStatement {
+  get(...params: unknown[]): unknown;
+  run(...params: unknown[]): void;
+  all(...params: unknown[]): unknown[];
+}
+
+/**
+ * Minimal interface for a SQLite database connection, compatible with
+ * `better-sqlite3`'s `Database` shape as consumed by `SqliteKv`.
+ *
+ * Mirrors `SqliteDatabase` in `src/platform/compat/kv/types.ts` — kept
+ * separate here so extensions can import from the public
+ * `veryfront/extensions/interfaces` entrypoint without taking a dependency
+ * on internal platform paths.
+ */
+export interface NodeCompatSqliteDatabase {
+  exec(sql: string): void;
+  prepare(sql: string): SqliteStatement;
+  close(): void;
+}
+
+/**
+ * Shape returned by the kreuzberg document-extraction module.
+ *
+ * Matches the subset used by `importKreuzberg()` in `opaque-deps.ts`.
+ */
+export interface KreuzbergExtractor {
+  extractBytes(
+    data: Uint8Array,
+    mimeType: string,
+  ): Promise<{ content: string }>;
+}
+
 /**
  * NodeCompat contract interface.
  *
- * Implementations provide access to Node.js-compatible APIs in
- * environments where native Node modules are unavailable (e.g. Deno).
+ * Implementations provide access to Node.js-only packages
+ * (`@kreuzberg/wasm`, `better-sqlite3`) in environments where those
+ * packages are available (i.e. a full Node/Deno runtime, not a compiled
+ * binary or edge runtime).
  *
- * Each getter returns the module's namespace object, matching the
- * shape of the corresponding Node.js built-in.
+ * Both methods are optional on the interface so that partial
+ * implementations (e.g. SQLite-only or kreuzberg-only) are valid.
  */
 export interface NodeCompat {
-  /** Return a Node-compatible `fs` module (sync + async + promises). */
-  getFS(): unknown;
-  /** Return a Node-compatible `path` module. */
-  getPath(): unknown;
-  /** Return a Node-compatible `WebSocket` constructor. */
-  getWebSocket(): unknown;
+  /**
+   * Initialise and return the kreuzberg document-extraction module.
+   *
+   * Callers should fall back to a "no extraction" path when this
+   * method is absent or throws.
+   */
+  importKreuzberg?(): Promise<KreuzbergExtractor>;
+
+  /**
+   * Run kreuzberg extraction inside an isolated Worker thread.
+   *
+   * Owned by the extension so that the worker script lives in a module
+   * graph where `@kreuzberg/wasm` resolves and the NodeCompat contract
+   * is reachable (Deno worker isolates do not share the main-thread
+   * contract registry).
+   *
+   * Callers on Node/Bun can skip workers and use `importKreuzberg()`
+   * directly — native bindings don't need WASM-hang isolation.
+   */
+  extractInWorker?(buffer: ArrayBuffer, mimeType: string): Promise<string>;
+
+  /**
+   * Open (or create) a SQLite database at `path`.
+   *
+   * Returns a database compatible with `SqliteKv`.
+   * When `path` is omitted an in-memory database is created.
+   *
+   * Callers should fall back to the in-memory KV when this method is
+   * absent or throws.
+   */
+  openSqliteDatabase?(path?: string): Promise<NodeCompatSqliteDatabase>;
 }

package/src/src/extensions/interfaces/tracing-exporter.ts

@@ -6,6 +6,14 @@
  * @module extensions/interfaces/tracing-exporter
  */
 
+/**
+ * Minimal TracerProvider interface for the contract.
+ * Structurally compatible with both the core shim and the real OTel SDK.
+ */
+export interface TracerProvider {
+  getTracer(name: string, version?: string): unknown;
+}
+
 /** Data describing a single trace span. */
 export interface SpanData {
   /** Unique span identifier. */
@@ -32,11 +40,38 @@ export interface SpanData {
  * TracingExporter contract interface.
  *
  * Implementations export collected trace spans to an observability
- * backend (e.g. Jaeger, Zipkin, OTLP collector).
+ * backend (e.g. Jaeger, Zipkin, OTLP collector) and expose the SDK
+ * TracerProvider so the core shim can delegate to it.
  */
 export interface TracingExporter {
+  /**
+   * Initialize the SDK provider and exporter.
+   * Called during extension setup.
+   */
+  start(config: Record<string, unknown>): Promise<void>;
+
   /** Export a batch of completed spans. */
   export(spans: SpanData[]): Promise<void>;
+
   /** Flush pending data and release resources. */
   shutdown(): Promise<void>;
+
+  /**
+   * Return the SDK TracerProvider so the core shim can delegate to it.
+   * The shim calls this after `start()` completes.
+   */
+  getProvider(): TracerProvider;
+
+  /**
+   * Return the OTel Metrics API so the metrics subsystem can get meters.
+   * Returns `null` when metrics are not available.
+   */
+  getMetricsAPI(): { getMeter(name: string | undefined, version?: string): unknown } | null;
+
+  /**
+   * Return the OTel Trace API so the core shim can look up the active span
+   * (for error correlation, proxy trace-id extraction, etc.). Returns `null`
+   * when tracing is disabled.
+   */
+  getTraceAPI?(): { getActiveSpan(): unknown; getSpan(ctx: unknown): unknown } | null;
 }

package/src/src/mcp/index.ts

@@ -17,8 +17,13 @@
  *   execute: async ({ query }) => ({ results: [] }),
  * });
  *
- * // Start MCP server — registered tools are exposed automatically
- * const server = createMCPServer();
+ * // Start MCP server — registered tools are exposed automatically.
+ * // `auth` is required: use bearer for production, or the explicit
+ * // `{ type: "none", allowUnauthenticated: true }` opt-in for local dev only.
+ * const server = createMCPServer({
+ *   enabled: true,
+ *   auth: { type: "none", allowUnauthenticated: true },
+ * });
  * ```
  */
 import "../../_dnt.polyfills.js";

package/src/src/mcp/schemas/index.ts

@@ -5,6 +5,7 @@
  */
 
 export {
+  MCPAuthConfigSchema,
   type MCPServerConfig,
   MCPServerConfigSchema,
   type MCPStats,

package/src/src/mcp/schemas/mcp.schema.ts

@@ -1,15 +1,28 @@
 import { z } from "zod";
 
+/**
+ * MCP auth configuration. One of:
+ * - `{ type: "bearer", validate?: (token) => Promise<boolean> }` — bearer-token auth.
+ * - `{ type: "none", allowUnauthenticated: true }` — explicit opt-in to an
+ *   unauthenticated server. Required for local dev/testing; prevents accidental
+ *   exposure of the JSON-RPC surface in production (VULN-SRV-5).
+ */
+const AuthValidatedSchema = z.object({
+  type: z.literal("bearer"),
+  validate: z.function().optional(),
+});
+
+const AuthNoneSchema = z.object({
+  type: z.literal("none"),
+  allowUnauthenticated: z.literal(true),
+});
+
+export const MCPAuthConfigSchema = z.union([AuthValidatedSchema, AuthNoneSchema]);
+
 export const MCPServerConfigSchema = z.object({
   enabled: z.boolean(),
   port: z.number().int().positive().optional(),
-  auth: z
-    .object({
-      type: z.enum(["bearer", "api-key", "none"]),
-      validate: z.function()
-        .optional(),
-    })
-    .optional(),
+  auth: MCPAuthConfigSchema,
   cors: z
     .object({
       enabled: z.boolean(),

package/src/src/mcp/server.ts

@@ -113,13 +113,69 @@ export class MCPServer {
   onNotification?: (notification: { jsonrpc: "2.0"; method: string; params?: unknown }) => void;
 
   constructor(config: MCPServerConfig) {
+    MCPServer.validateAuthConfig(config);
     this.config = config;
 
-    if (!config.auth || config.auth.type === "none") {
-      logger.warn("MCP server has no authentication configured — all requests will be accepted");
+    if (config.auth.type === "none") {
+      logger.warn(
+        "MCP server started with auth.type='none' (allowUnauthenticated) — all requests will be accepted",
+      );
     }
   }
 
+  /**
+   * Fail-closed validation of the auth configuration (VULN-SRV-5).
+   *
+   * Historically, an unset `auth` field — or `{ type: "none" }` — silently
+   * accepted every request with only a warning log. That meant an operator who
+   * forgot to configure auth shipped an unauthenticated JSON-RPC surface.
+   *
+   * The new contract: `auth` is required, and the only way to accept
+   * unauthenticated traffic is to explicitly set
+   * `{ type: "none", allowUnauthenticated: true }`. Any other shape is
+   * rejected at construction time.
+   */
+  private static validateAuthConfig(config: MCPServerConfig): void {
+    const auth = (config as { auth?: unknown }).auth;
+
+    if (auth === undefined || auth === null) {
+      throw new Error(
+        "MCP auth must be configured. For local dev, pass " +
+          "{ auth: { type: 'none', allowUnauthenticated: true } } explicitly.",
+      );
+    }
+
+    if (typeof auth !== "object") {
+      throw new Error(
+        "MCP auth must be an object. For local dev, pass " +
+          "{ auth: { type: 'none', allowUnauthenticated: true } } explicitly.",
+      );
+    }
+
+    const type = (auth as { type?: unknown }).type;
+
+    if (type === "none") {
+      const allow = (auth as { allowUnauthenticated?: unknown }).allowUnauthenticated;
+      if (allow !== true) {
+        throw new Error(
+          "MCP auth type 'none' requires allowUnauthenticated: true to acknowledge " +
+            "the server will accept all requests.",
+        );
+      }
+      return;
+    }
+
+    if (type === "bearer") {
+      return;
+    }
+
+    throw new Error(
+      `MCP auth type '${String(type)}' is not supported. Use 'bearer' ` +
+        "or { type: 'none', allowUnauthenticated: true } for explicit opt-in to " +
+        "unauthenticated traffic.",
+    );
+  }
+
   notifyToolsChanged(): void {
     this.onNotification?.({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
   }
@@ -607,7 +663,7 @@ export class MCPServer {
 
   createHTTPHandler(): (request: Request) => Promise<Response> {
     return createMCPHTTPHandler({
-      authEnabled: Boolean(this.config.auth?.type && this.config.auth.type !== "none"),
+      authEnabled: this.config.auth.type !== "none",
       getCORSHeaders: (requestOrigin) => this.getCORSHeaders(requestOrigin),
       validateAuth: (request) => this.validateAuth(request),
       handleRequest: (request, context) => this.handleRequest(request, context),
@@ -640,13 +696,11 @@ export class MCPServer {
 
   private async validateAuth(request: Request): Promise<boolean> {
     const auth = this.config.auth;
-    if (!auth || auth.type === "none") return true;
+    if (auth.type === "none") return true;
 
     const authHeader = request.headers.get("Authorization");
     if (!authHeader) return false;
 
-    if (auth.type !== "bearer") return false;
-
     const token = authHeader.replace("Bearer ", "");
 
     // When bearer auth is configured without a validate function, reject all requests

package/src/src/observability/auto-instrument/http-instrumentation.ts

@@ -6,7 +6,7 @@ import {
   SpanKind,
   SpanStatusCode,
   trace,
-} from "@opentelemetry/api";
+} from "../tracing/api-shim.js";
 import type { ErrorAttributes, HttpAttributes } from "./types.js";
 
 const logger = serverLogger.component("auto-instrument");

package/src/src/observability/auto-instrument/react-instrumentation.ts

@@ -1,4 +1,4 @@
-import { type Span, SpanStatusCode } from "@opentelemetry/api";
+import { type Span, SpanStatusCode } from "../tracing/api-shim.js";
 import { endSpan, setSpanAttributes, SpanNames, startSpan, withSpan } from "../tracing/index.js";
 import { recordRenderError } from "../metrics/index.js";
 

package/src/src/observability/auto-instrument/wrappers.ts

@@ -1,4 +1,4 @@
-import type { Span } from "@opentelemetry/api";
+import type { Span } from "../tracing/api-shim.js";
 import { endSpan, setSpanAttributes, type SpanOptions, startSpan } from "../tracing/index.js";
 import type { BatchOptions, InstrumentOptions } from "./types.js";
 

package/src/src/observability/instruments/build-instruments.ts

@@ -1,4 +1,4 @@
-import type { Counter, Histogram, Meter } from "@opentelemetry/api";
+import type { Counter, Histogram, Meter } from "../tracing/api-shim.js";
 import {
   DURATION_HISTOGRAM_BOUNDARIES_MS,
   SIZE_HISTOGRAM_BOUNDARIES_KB,

package/src/src/observability/instruments/cache-instruments.ts

@@ -1,4 +1,9 @@
-import type { Counter, Meter, ObservableGauge, ObservableResult } from "@opentelemetry/api";
+import type {
+  Counter,
+  Meter,
+  ObservableGauge,
+  ObservableResult,
+} from "../tracing/api-shim.js";
 import type { MetricsConfig, RuntimeState } from "../metrics/types.js";
 
 export interface CacheInstruments {

package/src/src/observability/instruments/data-instruments.ts

@@ -1,4 +1,4 @@
-import type { Counter, Histogram, Meter } from "@opentelemetry/api";
+import type { Counter, Histogram, Meter } from "../tracing/api-shim.js";
 import { DURATION_HISTOGRAM_BOUNDARIES_MS } from "../../config/defaults.js";
 import type { MetricsConfig } from "../metrics/types.js";
 

package/src/src/observability/instruments/error-instruments.ts

@@ -5,7 +5,7 @@
  * observability dashboards and alerting.
  */
 
-import type { Counter, Meter } from "@opentelemetry/api";
+import type { Counter, Meter } from "../tracing/api-shim.js";
 import type { MetricsConfig } from "../metrics/types.js";
 import type { VeryfrontError } from "../../errors/types.js";
 

package/src/src/observability/instruments/http-instruments.ts

@@ -1,4 +1,9 @@
-import type { Counter, Histogram, Meter, UpDownCounter } from "@opentelemetry/api";
+import type {
+  Counter,
+  Histogram,
+  Meter,
+  UpDownCounter,
+} from "../tracing/api-shim.js";
 import { DURATION_HISTOGRAM_BOUNDARIES_MS } from "../../config/defaults.js";
 import type { MetricsConfig } from "../metrics/types.js";
 

package/src/src/observability/instruments/instruments-factory.ts

@@ -1,4 +1,4 @@
-import type { Meter } from "@opentelemetry/api";
+import type { Meter } from "../tracing/api-shim.js";
 import { serverLogger } from "../../utils/index.js";
 import type { MetricsConfig, MetricsInstruments, RuntimeState } from "../metrics/types.js";
 import { createBuildInstruments } from "./build-instruments.js";

package/src/src/observability/instruments/memory-instruments.ts

@@ -1,4 +1,8 @@
-import type { Meter, ObservableGauge, ObservableResult } from "@opentelemetry/api";
+import type {
+  Meter,
+  ObservableGauge,
+  ObservableResult,
+} from "../tracing/api-shim.js";
 import { getV8FlagsEnv } from "../../config/env.js";
 import { getMemoryUsage } from "../metrics/config.js";
 import type { MetricsConfig } from "../metrics/types.js";

package/src/src/observability/instruments/render-instruments.ts

@@ -1,4 +1,4 @@
-import type { Counter, Histogram, Meter } from "@opentelemetry/api";
+import type { Counter, Histogram, Meter } from "../tracing/api-shim.js";
 import { DURATION_HISTOGRAM_BOUNDARIES_MS } from "../../config/defaults.js";
 import type { MetricsConfig } from "../metrics/types.js";
 

package/src/src/observability/instruments/rsc-instruments.ts

@@ -1,4 +1,4 @@
-import type { Counter, Histogram, Meter } from "@opentelemetry/api";
+import type { Counter, Histogram, Meter } from "../tracing/api-shim.js";
 import { DURATION_HISTOGRAM_BOUNDARIES_MS } from "../../config/defaults.js";
 import type { MetricsConfig } from "../metrics/types.js";
 

package/src/src/observability/metrics/manager.ts

@@ -3,7 +3,8 @@
  * Main OpenTelemetry metrics initialization and management
  */
 
-import type { Meter } from "@opentelemetry/api";
+import type { Meter } from "../tracing/api-shim.js";
+import { getGlobalMetricsAPI } from "../tracing/api-shim.js";
 import { serverLogger } from "../../utils/index.js";
 import type { RuntimeAdapter } from "../../platform/adapters/base.js";
 import { loadConfig } from "./config.js";
@@ -79,8 +80,15 @@ export class MetricsManager {
     }
 
     try {
-      this.api = await import("@opentelemetry/api");
-      this.meter = this.api.metrics.getMeter(finalConfig.prefix, RUNTIME_VERSION);
+      // The metrics API is injected by ext-opentelemetry via setGlobalMetricsAPI().
+      // When the extension is not active, metrics collection is disabled.
+      const metricsApi = getGlobalMetricsAPI();
+      if (!metricsApi) {
+        logger.debug("No metrics API available — metrics collection disabled");
+        return;
+      }
+      this.api = { metrics: metricsApi } as OpenTelemetryAPI;
+      this.meter = metricsApi.getMeter(finalConfig.prefix, RUNTIME_VERSION);
 
       this.instruments = initializeInstruments(this.meter, finalConfig, this.runtimeState);
       this.recorder.instruments = this.instruments;

package/src/src/observability/metrics/types.ts

@@ -3,7 +3,13 @@
  * Type definitions for OpenTelemetry metrics system
  */
 
-import type { Counter, Histogram, Meter, ObservableGauge, UpDownCounter } from "@opentelemetry/api";
+import type {
+  Counter,
+  Histogram,
+  Meter,
+  ObservableGauge,
+  UpDownCounter,
+} from "../tracing/api-shim.js";
 
 export interface OpenTelemetryAPI {
   metrics: {