@superblocksteam/sdk 2.0.139-next.1 → 2.0.140-next.0

package/src/react-compiler-runtime-shim.mts

@@ -0,0 +1,50 @@
+import { createRequire } from "node:module";
+
+import type { Alias } from "vite";
+
+import { getLogger } from "./telemetry/logging.js";
+
+// Module-scoped require for resolving sibling dependencies by absolute path.
+// `createRequire` works under both the Node runtime and the Vitest module
+// runner, unlike top-level `import.meta.resolve`.
+const sdkRequire = createRequire(import.meta.url);
+const logger = getLogger();
+
+/**
+ * Vite alias mapping the React 19-only `react/compiler-runtime` specifier to
+ * the React-team `react-compiler-runtime` shim, which is API-compatible on
+ * React 17/18. Shared by the live-edit dev server and the production build so
+ * that user code (or a dependency) emitting `react/compiler-runtime` imports
+ * resolves against our React 18.3.1 runtime instead of crashing Vite
+ * resolution with `Missing "./compiler-runtime" specifier in "react" package`
+ * (APPS-2887).
+ *
+ * The exact-match string `find` fires only for `react/compiler-runtime`, never
+ * `react`, `react/jsx-runtime`, or `react-dom`.
+ *
+ * Returns `null` (and logs) if the shim package cannot be resolved — e.g. a
+ * corrupted or partial SDK install. Skipping the alias keeps the dev server /
+ * build starting for every other app instead of throwing synchronously inside
+ * `createServer()`/`build()` and permanently rejecting `vitePromise`, which
+ * would reproduce the very infinite-spinner symptom this fix removes. Only an
+ * app that actually imports `react/compiler-runtime` would then hit the
+ * original (now clearly-logged) resolution error.
+ */
+export function reactCompilerRuntimeAlias(
+  // Resolver seam: defaults to the real module resolution; overridable in tests.
+  resolve: (id: string) => string = (id) => sdkRequire.resolve(id),
+): Alias | null {
+  let replacement: string;
+  try {
+    replacement = resolve("react-compiler-runtime");
+  } catch {
+    logger.warn(
+      "[APPS-2887] Could not resolve the 'react-compiler-runtime' shim; " +
+        "skipping the react/compiler-runtime alias. Reinstall the SDK " +
+        "dependencies if an app needs it (apps that do not import " +
+        "react/compiler-runtime are unaffected).",
+    );
+    return null;
+  }
+  return { find: "react/compiler-runtime", replacement };
+}

package/src/react-compiler-runtime-shim.test.mts

@@ -0,0 +1,26 @@
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { reactCompilerRuntimeAlias } from "./react-compiler-runtime-shim.mjs";
+
+describe("reactCompilerRuntimeAlias", () => {
+  it("maps react/compiler-runtime to an existing absolute shim path", () => {
+    const alias = reactCompilerRuntimeAlias();
+    expect(alias).not.toBeNull();
+    expect(alias!.find).toBe("react/compiler-runtime");
+    expect(typeof alias!.replacement).toBe("string");
+    expect(isAbsolute(alias!.replacement as string)).toBe(true);
+    expect(existsSync(alias!.replacement as string)).toBe(true);
+  });
+
+  it("returns null instead of throwing when the shim cannot be resolved", () => {
+    // Simulate a corrupted/partial install where the shim package is absent.
+    // The dev server must keep starting (no permanently-rejected vitePromise).
+    const alias = reactCompilerRuntimeAlias(() => {
+      throw new Error("Cannot find module 'react-compiler-runtime'");
+    });
+    expect(alias).toBeNull();
+  });
+});

package/src/telemetry/attributes.ts

@@ -2,7 +2,6 @@
 export const ATTR_DEPLOYMENT_ENVIRONMENT = "deployment.environment";
 // NOTE: @joeyagreco - this can be used to determine if we are using mock-csb, staging-csb, prod-csb, etc
 export const ATTR_SUPERBLOCKS_BASE_URL = "superblocks.base_url";
-export const ATTR_SUPERBLOCKS_CLI_TOKEN = "superblocks.cli_token";
 export const ATTR_SUPERBLOCKS_IS_CSB = "superblocks.is_csb";
 export const ATTR_SUPERBLOCKS_USER_ID = "user-id";
 export const ATTR_SUPERBLOCKS_CSB_ID = "csb_id";

package/src/telemetry/identity.test.ts

@@ -0,0 +1,30 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+describe("telemetry identity", () => {
+  afterEach(async () => {
+    const { setTelemetryIdentity } = await import("./identity.js");
+    setTelemetryIdentity({});
+    vi.resetModules();
+  });
+
+  it("drops undefined values and returns the rest", async () => {
+    const { setTelemetryIdentity, getTelemetryIdentity } =
+      await import("./identity.js");
+    setTelemetryIdentity({ "application-id": "app-1", branch: undefined });
+    expect(getTelemetryIdentity()).toEqual({ "application-id": "app-1" });
+  });
+
+  it("shares identity across module instances, as when the CLI bundle and the preload's node_modules copy each load their own", async () => {
+    const writer = await import("./identity.js");
+    writer.setTelemetryIdentity({ "application-id": "app-1" });
+
+    // A fresh module registry stands in for the second copy of this module
+    // that esbuild bakes into the packaged CLI.
+    vi.resetModules();
+    const reader = await import("./identity.js");
+
+    expect(reader.getTelemetryIdentity()).toEqual({
+      "application-id": "app-1",
+    });
+  });
+});

package/src/telemetry/identity.ts

@@ -0,0 +1,40 @@
+/**
+ * Mutable holder for dev-server telemetry identity that is only known after
+ * connect: application id, branch, user, and org.
+ *
+ * The preload starts OpenTelemetry early (before the ai-service loads) with only
+ * the static resource it can derive from the environment, and passes
+ * `getTelemetryIdentity` as the SDK's dynamic attribute source.
+ * `configureTelemetry` fills this in once it has fetched the application config,
+ * so spans and exported log records created after connect carry the full
+ * identity — the same set the SDK used to put on the resource — without
+ * re-initializing the SDK. Earlier startup signals simply carry the static
+ * resource. Metrics deliberately do not carry identity (cardinality).
+ *
+ * The holder lives on `globalThis`, not in a module variable: the packaged CLI
+ * contains TWO copies of this module (one esbuild-bundled into the CLI dist,
+ * one under node_modules that the bin's `telemetry-preload` import resolves
+ * to). The preload's copy hands the getter to the exporting SDK while the
+ * bundled copy's `configureTelemetry` calls the setter, so a per-module
+ * variable would split into two holders and identity would never reach an
+ * exported span or log record.
+ */
+declare global {
+  var __superblocksTelemetryIdentity: Record<string, string> | undefined;
+}
+
+/** Replaces the identity. Undefined values are dropped so absent fields are omitted. */
+export function setTelemetryIdentity(
+  next: Record<string, string | undefined>,
+): void {
+  globalThis.__superblocksTelemetryIdentity = Object.fromEntries(
+    Object.entries(next).filter(
+      (entry): entry is [string, string] => entry[1] != null,
+    ),
+  );
+}
+
+/** Current identity; passed to the SDK as the dynamic span-attribute source. */
+export function getTelemetryIdentity(): Record<string, string> {
+  return globalThis.__superblocksTelemetryIdentity ?? {};
+}

package/src/telemetry/index.test.ts

@@ -42,6 +42,8 @@ vi.mock("./logging.js", () => ({
   }),
 }));
 
+import { FeatureFlags } from "../flag.js";
+import type { ApplicationConfigWithTokenConfigAndUserInfo } from "../types/index.js";
 // Import type for module shape
 import type * as TelemetryModule from "./index.js";
 
@@ -63,8 +65,10 @@ describe("CLI SDK Telemetry Integration", () => {
     }
   });
 
-  beforeEach(() => {
+  beforeEach(async () => {
     vi.clearAllMocks();
+    // Each test starts unconfigured; repeat-call behavior is tested explicitly.
+    await telemetryModule.shutdownTelemetry();
   });
 
   describe("configureTelemetry", () => {
@@ -84,6 +88,37 @@ describe("CLI SDK Telemetry Integration", () => {
 
       expect(ddTrace.default.init).toHaveBeenCalled();
     });
+
+    it("refreshes identity on a repeat call without tearing down the pipeline", async () => {
+      const ddTrace = await import("dd-trace");
+      const { isTelemetryInitialized } =
+        await import("@superblocksteam/telemetry");
+      const { getTelemetryIdentity } = await import("./identity.js");
+
+      const applicationConfig: ApplicationConfigWithTokenConfigAndUserInfo = {
+        id: "app-2",
+        branchName: "main",
+        userId: "user-1",
+        userEmail: "dev@example.com",
+        organizationId: "org-1",
+        featureFlags: new FeatureFlags({}),
+        superblocksBaseUrl: "https://app.superblocks.com",
+        token: "test1234",
+      };
+
+      await telemetryModule.configureTelemetry();
+      const result =
+        await telemetryModule.configureTelemetry(applicationConfig);
+
+      expect(result).toBe(true);
+      // The running SDK and dd-trace survive; only identity is refreshed.
+      expect(isTelemetryInitialized()).toBe(true);
+      expect(ddTrace.default.init).toHaveBeenCalledTimes(1);
+      expect(getTelemetryIdentity()).toMatchObject({
+        "application-id": "app-2",
+        "organization-id": "org-1",
+      });
+    });
   });
 
   describe("getTracer", () => {

package/src/telemetry/index.ts

@@ -26,12 +26,12 @@ import packageJson from "../../package.json" with { type: "json" };
 import type { ApplicationConfigWithTokenConfigAndUserInfo } from "../types/index.js";
 import {
   ATTR_SUPERBLOCKS_BASE_URL,
-  ATTR_SUPERBLOCKS_CLI_TOKEN,
   ATTR_SUPERBLOCKS_CSB_ID,
   ATTR_SUPERBLOCKS_IS_CSB,
   ATTR_SUPERBLOCKS_USER_ID,
   getEnvironmentFromHostname,
 } from "./attributes.js";
+import { getTelemetryIdentity, setTelemetryIdentity } from "./identity.js";
 import { applyLocalObsEnvVars, isLocalObsEnabled } from "./local-obs.js";
 import { getLogger as getStandardLogger } from "./logging.js";
 import { getConfiguration, SERVICE_NAME } from "./util.js";
@@ -110,8 +110,28 @@ export async function configureTelemetry(
   applicationConfig?: ApplicationConfigWithTokenConfigAndUserInfo,
 ): Promise<boolean> {
   const logger = getStandardLogger();
+
+  // The application, user, and org are known only at connect, so they are
+  // stamped onto every span and exported log record via the SDK's dynamic
+  // attribute source rather than the resource. This restores the identity the
+  // SDK used to put on the resource, without re-initializing (which would churn
+  // instrumentation). The CLI token is deliberately NOT included: it is a
+  // credential and does not belong in telemetry.
+  const identity = {
+    [OBS_TAG_APPLICATION_ID]: applicationConfig?.id,
+    [OBS_TAG_BRANCH]: applicationConfig?.branchName,
+    [OBS_TAG_USER_EMAIL]: applicationConfig?.userEmail,
+    [ATTR_SUPERBLOCKS_USER_ID]: applicationConfig?.userId,
+    [OBS_TAG_ORG_ID]: applicationConfig?.organizationId,
+  };
+
+  // Repeat calls (e.g. auth hot-reload) must not tear down a working pipeline:
+  // a shutdown+reinit loses the global provider registration (the OTel API
+  // rejects a second registration), leaving all instrumentation pointed at dead
+  // providers. Refresh the identity and keep the running SDK and dd-trace.
   if (configured) {
-    await shutdownTelemetry();
+    setTelemetryIdentity(identity);
+    return true;
   }
 
   configured = true;
@@ -128,6 +148,8 @@ export async function configureTelemetry(
     `[INIT] Initializing telemetry for service ${config.serviceName} at Superblocks instance ${config.superblocksHostname}`,
   );
 
+  setTelemetryIdentity(identity);
+
   // Check for local observability mode (SUPERBLOCKS_LOCAL_OBS=true)
   const isLocalObs = isLocalObsEnabled();
 
@@ -157,7 +179,6 @@ export async function configureTelemetry(
     plugins: false,
     tags: {
       [ATTR_SUPERBLOCKS_BASE_URL]: config.superblocksHostname,
-      [ATTR_SUPERBLOCKS_CLI_TOKEN]: config.token,
       [ATTR_SUPERBLOCKS_IS_CSB]: !!process.env.SUPERBLOCKS_IS_CSB,
       [ATTR_SUPERBLOCKS_CSB_ID]: process.env.SUPERBLOCKS_IS_CSB
         ? os.hostname()
@@ -179,51 +200,41 @@ export async function configureTelemetry(
     } for service ${config.serviceName}`,
   );
 
-  // Configure OpenTelemetry for APM traces and logs via shared telemetry package
-  const policy = getDefaultPolicy(deploymentType);
-
-  try {
-    initNodeTelemetry(
-      {
-        serviceName: config.serviceName,
-        serviceVersion: packageJson.version,
-        environment: getEnvironmentFromHostname(config.superblocksHostname),
-        otlpUrl: config.otlpBaseUrl,
-        resourceAttributes: {
-          [ATTR_SUPERBLOCKS_BASE_URL]: config.superblocksHostname,
-          [ATTR_SUPERBLOCKS_CLI_TOKEN]: config.token,
-          [ATTR_SUPERBLOCKS_IS_CSB]: String(!!process.env.SUPERBLOCKS_IS_CSB),
-          ...(process.env.SUPERBLOCKS_IS_CSB && {
-            [ATTR_SUPERBLOCKS_CSB_ID]: os.hostname(),
-          }),
-          ...(applicationConfig?.id && {
-            [OBS_TAG_APPLICATION_ID]: applicationConfig.id,
-          }),
-          ...(applicationConfig?.branchName && {
-            [OBS_TAG_BRANCH]: applicationConfig.branchName,
-          }),
-          ...(applicationConfig?.userEmail && {
-            [OBS_TAG_USER_EMAIL]: applicationConfig.userEmail,
-          }),
-          ...(applicationConfig?.userId && {
-            [ATTR_SUPERBLOCKS_USER_ID]: applicationConfig.userId,
-          }),
-          ...(applicationConfig?.organizationId && {
-            [OBS_TAG_ORG_ID]: applicationConfig.organizationId,
-          }),
+  // Configure OpenTelemetry for APM traces and logs via shared telemetry
+  // package. When the early preload already started the SDK, skip: identity
+  // flows through the dynamic attribute source above, and constructing
+  // instrumentations here would only leave self-enabled orphans behind
+  // (initNodeTelemetry would return the existing instance and discard them).
+  if (!isTelemetryInitialized()) {
+    const policy = getDefaultPolicy(deploymentType);
+    try {
+      initNodeTelemetry(
+        {
+          serviceName: config.serviceName,
+          serviceVersion: packageJson.version,
+          environment: getEnvironmentFromHostname(config.superblocksHostname),
+          otlpUrl: config.otlpBaseUrl,
+          resourceAttributes: {
+            [ATTR_SUPERBLOCKS_BASE_URL]: config.superblocksHostname,
+            [ATTR_SUPERBLOCKS_IS_CSB]: String(!!process.env.SUPERBLOCKS_IS_CSB),
+            ...(process.env.SUPERBLOCKS_IS_CSB && {
+              [ATTR_SUPERBLOCKS_CSB_ID]: os.hostname(),
+            }),
+          },
+          instrumentations: [
+            new HttpInstrumentation(),
+            new ExpressInstrumentation(),
+          ],
+          logsEnabled: true,
+          dynamicAttributes: getTelemetryIdentity,
         },
-        instrumentations: [
-          new HttpInstrumentation(),
-          new ExpressInstrumentation(),
-        ],
-        logsEnabled: true,
-      },
-      policy,
-    );
-  } catch (error) {
-    console.error("[Telemetry] Failed to initialize OpenTelemetry:", error);
-    configured = false;
-    return false;
+        policy,
+      );
+    } catch (error) {
+      console.error("[Telemetry] Failed to initialize OpenTelemetry:", error);
+      configured = false;
+      return false;
+    }
   }
 
   return true;

package/src/telemetry/local-obs.ts

@@ -5,11 +5,10 @@
  * all environment variables needed for local observability testing with the
  * LGTM stack (Loki, Grafana, Tempo, Mimir).
  *
- * This eliminates the need to manually set 9+ environment variables:
+ * This eliminates the need to manually set 8+ environment variables:
  * - SUPERBLOCKS_DEPLOYMENT_TYPE
  * - SUPERBLOCKS_LLMOBS_ENABLED
  * - OTEL_EXPORTER_OTLP_ENDPOINT
- * - SUPERBLOCKS_OTEL_COLLECTOR_URL
  * - DD_LLMOBS_ENABLED
  * - DD_LLMOBS_ML_APP
  * - DD_LLMOBS_AGENTLESS_ENABLED
@@ -21,6 +20,13 @@
  *
  * Or with custom OTEL endpoint:
  *   SUPERBLOCKS_LOCAL_OBS=true OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 pnpm start:all
+ *
+ * Note: this mode changes export POLICY (sampling, log levels, LLMObs), not the
+ * dev-server's OTLP endpoint. The dev-server always exports through the
+ * Superblocks server proxy at <SUPERBLOCKS_BASE_URL>/api, so with an auth file
+ * pointing at a remote instance, a standalone `SUPERBLOCKS_LOCAL_OBS=true
+ * superblocks dev` sends its telemetry to that instance, not to the local
+ * collector. Run against a local stack to keep telemetry local.
  */
 
 import { DeploymentTypeEnum } from "@superblocksteam/shared";
@@ -122,7 +128,6 @@ export function applyLocalObsEnvVars(): void {
     SUPERBLOCKS_DEPLOYMENT_TYPE: config.deploymentType,
     SUPERBLOCKS_LLMOBS_ENABLED: "true",
     OTEL_EXPORTER_OTLP_ENDPOINT: config.otelEndpoint,
-    SUPERBLOCKS_OTEL_COLLECTOR_URL: config.otelEndpoint,
     DD_LLMOBS_ENABLED: "1",
     DD_LLMOBS_ML_APP: config.llmobs.mlApp,
     DD_LLMOBS_AGENTLESS_ENABLED: "1",

package/src/telemetry/otlp-config.test.ts

@@ -0,0 +1,213 @@
+import * as http from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  buildDeltaCounterPayload,
+  deploymentEnvironment,
+  emitOtlpCounter,
+  otlpBaseUrl,
+  otlpMetricsUrl,
+} from "./otlp-config.js";
+
+describe("otlpBaseUrl", () => {
+  it("returns <origin>/api for a valid base URL, dropping any path", () => {
+    expect(otlpBaseUrl("https://app.superblocks.com/some/path")).toBe(
+      "https://app.superblocks.com/api",
+    );
+  });
+
+  it("returns undefined when the base URL is missing", () => {
+    expect(otlpBaseUrl(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined on an unparseable base URL", () => {
+    expect(otlpBaseUrl("not a url")).toBeUndefined();
+  });
+});
+
+describe("otlpMetricsUrl", () => {
+  it("derives <baseUrl origin>/api/v1/metrics from SUPERBLOCKS_BASE_URL", () => {
+    expect(
+      otlpMetricsUrl({
+        SUPERBLOCKS_BASE_URL: "https://pr-19864.superblocks.dev/some/path",
+      }),
+    ).toBe("https://pr-19864.superblocks.dev/api/v1/metrics");
+  });
+
+  it("always exports through the server proxy: SUPERBLOCKS_OTEL_COLLECTOR_URL alone is ignored", () => {
+    // There is no direct-to-collector path anymore; the server proxies OTLP.
+    expect(
+      otlpMetricsUrl({
+        SUPERBLOCKS_OTEL_COLLECTOR_URL: "http://localhost:4318",
+      }),
+    ).toBeNull();
+  });
+
+  it("returns null when no base URL is present (emission is skipped)", () => {
+    expect(otlpMetricsUrl({})).toBeNull();
+  });
+
+  it("returns null on an unparseable base URL", () => {
+    expect(otlpMetricsUrl({ SUPERBLOCKS_BASE_URL: "not a url" })).toBeNull();
+  });
+});
+
+describe("warnIfCollectorUrlIgnored", () => {
+  it("warns once (and only once) when the retired direct-export var is set", async () => {
+    // The module-level call in otlp-config.ts latches the once-flag against
+    // the real process.env at import time, so a shell that exports the var
+    // would make the statically imported instance a no-op here. Import a
+    // fresh instance with the var stubbed away.
+    vi.stubEnv("SUPERBLOCKS_OTEL_COLLECTOR_URL", "");
+    vi.resetModules();
+    const { warnIfCollectorUrlIgnored } = await import("./otlp-config.js");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    warnIfCollectorUrlIgnored({});
+    expect(warn).not.toHaveBeenCalled();
+
+    warnIfCollectorUrlIgnored({
+      SUPERBLOCKS_OTEL_COLLECTOR_URL: "http://localhost:4318",
+    });
+    warnIfCollectorUrlIgnored({
+      SUPERBLOCKS_OTEL_COLLECTOR_URL: "http://localhost:4318",
+    });
+
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain("SUPERBLOCKS_OTEL_COLLECTOR_URL");
+    warn.mockRestore();
+    vi.unstubAllEnvs();
+  });
+});
+
+describe("deploymentEnvironment", () => {
+  it("maps an ephemeral pr-<n> host to 'ephemeral'", () => {
+    expect(
+      deploymentEnvironment({
+        SUPERBLOCKS_BASE_URL: "https://pr-19864.superblocks.dev",
+      }),
+    ).toBe("ephemeral");
+  });
+
+  it("maps localhost to 'local'", () => {
+    expect(
+      deploymentEnvironment({ SUPERBLOCKS_BASE_URL: "http://localhost:3000" }),
+    ).toBe("local");
+  });
+
+  it("maps the production host to 'prod'", () => {
+    expect(
+      deploymentEnvironment({
+        SUPERBLOCKS_BASE_URL: "https://app.superblocks.com",
+      }),
+    ).toBe("prod");
+  });
+
+  it("falls back to 'other' when no base URL is available", () => {
+    expect(deploymentEnvironment({})).toBe("other");
+  });
+});
+
+describe("buildDeltaCounterPayload", () => {
+  it("builds a monotonic DELTA sum with one int data point and the given attributes", () => {
+    const payload = buildDeltaCounterPayload({
+      name: "dev_server_child_respawn_completed_total",
+      description: "desc",
+      attributes: { reason: "flip_restart" },
+      environment: "ephemeral",
+      nowMs: 1_730_000_000_000,
+    }) as any;
+
+    const rm = payload.resourceMetrics[0];
+    const resourceAttrs = Object.fromEntries(
+      rm.resource.attributes.map((a: any) => [a.key, a.value.stringValue]),
+    );
+    expect(resourceAttrs["service.name"]).toBe("sdk-dev-server");
+    expect(resourceAttrs["deployment.environment.name"]).toBe("ephemeral");
+
+    const metric = rm.scopeMetrics[0].metrics[0];
+    expect(metric.sum.isMonotonic).toBe(true);
+    expect(metric.sum.aggregationTemporality).toBe(1); // DELTA
+
+    const dp = metric.sum.dataPoints[0];
+    expect(dp.asInt).toBe("1");
+    const dpAttrs = Object.fromEntries(
+      dp.attributes.map((a: any) => [a.key, a.value.stringValue]),
+    );
+    expect(dpAttrs.reason).toBe("flip_restart");
+
+    // Nanosecond timestamps must be decimal strings, start <= time.
+    expect(typeof dp.timeUnixNano).toBe("string");
+    expect(BigInt(dp.startTimeUnixNano) <= BigInt(dp.timeUnixNano)).toBe(true);
+    expect(dp.timeUnixNano).toBe(
+      (BigInt(1_730_000_000_000) * 1_000_000n).toString(),
+    );
+  });
+});
+
+describe("emitOtlpCounter (integration: listens on the OTLP endpoint)", () => {
+  let server: http.Server;
+  let received: { url?: string; contentType?: string; body: string } | null;
+  let port: number;
+
+  beforeEach(async () => {
+    received = null;
+    server = http.createServer((req, res) => {
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", () => {
+        received = {
+          url: req.url,
+          contentType: req.headers["content-type"],
+          body,
+        };
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end("{}");
+      });
+    });
+    await new Promise<void>((resolve) =>
+      server.listen(0, "127.0.0.1", resolve),
+    );
+    port = (server.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it("POSTs the counter as OTLP JSON to the server proxy's /api/v1/metrics", async () => {
+    await emitOtlpCounter({
+      name: "dev_server_child_respawn_completed_total",
+      description: "desc",
+      attributes: { reason: "flip_restart" },
+      env: { SUPERBLOCKS_BASE_URL: `http://127.0.0.1:${port}` },
+      // Tests must observe the request, so keep the socket alive (no unref) and
+      // await the POST instead of fire-and-forget.
+      unref: false,
+      timeoutMs: 5000,
+    });
+
+    expect(received).not.toBeNull();
+    expect(received!.url).toBe("/api/v1/metrics");
+    expect(received!.contentType).toContain("application/json");
+
+    const parsed = JSON.parse(received!.body);
+    const metric = parsed.resourceMetrics[0].scopeMetrics[0].metrics[0];
+    expect(metric.sum.dataPoints[0].asInt).toBe("1");
+  });
+
+  it("resolves without throwing and sends nothing when no base URL is configured", async () => {
+    await expect(
+      emitOtlpCounter({
+        name: "dev_server_child_respawn_completed_total",
+        description: "desc",
+        attributes: { reason: "flip_restart" },
+        env: {},
+        unref: false,
+      }),
+    ).resolves.toBeUndefined();
+    expect(received).toBeNull();
+  });
+});