@desplega.ai/agent-swarm 1.79.3 → 1.80.0

package/src/http/context.ts

@@ -6,7 +6,7 @@ import {
   getContextSummaryByTaskId,
   getTaskById,
 } from "../be/db";
-import { ContextSnapshotEventTypeSchema } from "../types";
+import { ContextFormulaSchema, ContextSnapshotEventTypeSchema } from "../types";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
@@ -25,10 +25,13 @@ const postContext = route({
     contextUsedTokens: z.number().int().min(0).optional(),
     contextTotalTokens: z.number().int().min(0).optional(),
     contextPercent: z.number().min(0).max(100).optional(),
-    compactTrigger: z.enum(["auto", "manual"]).optional(),
+    compactTrigger: z.enum(["auto", "manual", "auto-inferred"]).optional(),
     preCompactTokens: z.number().int().min(0).optional(),
     cumulativeInputTokens: z.number().int().min(0).optional(),
     cumulativeOutputTokens: z.number().int().min(0).optional(),
+    // Migration 063: adapters tag the formula they used so cross-provider
+    // comparisons can tell apples from oranges.
+    contextFormula: ContextFormulaSchema.optional(),
   }),
   responses: {
     200: { description: "Snapshot recorded" },
@@ -91,6 +94,7 @@ export async function handleContext(
       preCompactTokens: parsed.body.preCompactTokens,
       cumulativeInputTokens: parsed.body.cumulativeInputTokens,
       cumulativeOutputTokens: parsed.body.cumulativeOutputTokens,
+      contextFormula: parsed.body.contextFormula,
     });
 
     json(res, { ok: true, snapshotId: snapshot.id });

package/src/http/index.ts

@@ -14,6 +14,7 @@ import { initGitLab } from "../gitlab";
 import { stopHeartbeat } from "../heartbeat";
 import { initJira } from "../jira";
 import { initLinear } from "../linear";
+import { initOtel, startSpan, withRemoteContext } from "../otel";
 import { startSlackApp, stopSlackApp } from "../slack";
 import { initTelemetry, telemetry } from "../telemetry";
 import { initWorkflows } from "../workflows";
@@ -89,6 +90,7 @@ const transports: Record<string, StreamableHTTPServerTransport> = globalState.__
 const httpServer = createHttpServer(async (req, res) => {
   const startTime = performance.now();
   let statusCode = 200;
+  let spanEnded = false;
 
   // Wrap writeHead to capture status code
   const originalWriteHead = res.writeHead.bind(res);
@@ -113,76 +115,108 @@ const httpServer = createHttpServer(async (req, res) => {
     console.error(`[HTTP] ❌ ${req.method} ${req.url} → Error: ${err.message}`);
   });
 
-  setCorsHeaders(req, res);
-
-  // ── Core routes (OPTIONS, health, auth, /me, /cancelled-tasks, /ping, /close) ──
-  if (await handleCore(req, res, req.headers["x-agent-id"] as string | undefined, apiKey)) return;
-
-  const pathSegments = getPathSegments(req.url || "");
-  const queryParams = parseQueryParams(req.url || "");
-  const myAgentId = req.headers["x-agent-id"] as string | undefined;
-
-  // ── Route handlers (order matters — first match wins) ──
-  const handlers: (() => Promise<boolean>)[] = [
-    () => handleAgentRegister(req, res, pathSegments, myAgentId),
-    () => handlePoll(req, res, pathSegments, queryParams, myAgentId),
-    () => handleSessionData(req, res, pathSegments, queryParams, myAgentId),
-    () => handleEcosystem(req, res, pathSegments, myAgentId),
-    () => handleTrackers(req, res, pathSegments),
-    () => handleWebhooks(req, res, pathSegments),
-    () => handleAgentsRest(req, res, pathSegments, queryParams, myAgentId),
-    () => handleBudgets(req, res, pathSegments, queryParams, myAgentId),
-    () => handleContext(req, res, pathSegments, queryParams, myAgentId),
-    () => handleTasks(req, res, pathSegments, queryParams, myAgentId),
-    () => handleStats(req, res, pathSegments, queryParams),
-    () => handleStatus(req, res, pathSegments, queryParams),
-    () => handleActiveSessions(req, res, pathSegments, queryParams, myAgentId),
-    () => handlePricing(req, res, pathSegments, queryParams, myAgentId),
-    () => handleSchedules(req, res, pathSegments, queryParams, myAgentId),
-    () => handleWorkflows(req, res, pathSegments, queryParams, myAgentId),
-    () => handleWorkflowEvents(req, res, pathSegments, queryParams),
-    () => handleApprovalRequests(req, res, pathSegments, queryParams),
-    () => handleConfig(req, res, pathSegments, queryParams),
-    () => handleKv(req, res, pathSegments, queryParams),
-    () => handleIntegrations(req, res, pathSegments),
-    () => handlePromptTemplates(req, res, pathSegments, queryParams),
-    () => handleDbQuery(req, res, pathSegments, queryParams),
-    () => handleRepos(req, res, pathSegments, queryParams),
-    () => handleSkills(req, res, pathSegments, queryParams, myAgentId),
-    () => handleMcpServers(req, res, pathSegments, queryParams),
-    () => handleMcpOAuth(req, res, pathSegments, queryParams),
-    () => handleMemory(req, res, pathSegments, myAgentId),
-    () => handlePagesPublic(req, res, pathSegments, queryParams),
-    () => handlePageProxy(req, res),
-    () => handlePages(req, res, pathSegments, queryParams, myAgentId),
-    () => handleApiKeys(req, res, pathSegments, queryParams),
-    () => handleHeartbeat(req, res, pathSegments),
-    () => handleEvents(req, res, pathSegments, queryParams, myAgentId),
-    () => handleUsers(req, res, pathSegments, queryParams),
-    () => handleSessions(req, res, pathSegments, queryParams),
-    () => handleInboxState(req, res, pathSegments, queryParams),
-    () => handleTaskTemplates(req, res, pathSegments, queryParams),
-    () => handleMcp(req, res, transports),
-  ];
-
-  try {
-    for (const handler of handlers) {
-      if (await handler()) return;
-    }
+  await withRemoteContext(req.headers as Record<string, unknown>, async () => {
+    const span = startSpan("http.server", {
+      "http.request.method": req.method ?? "",
+      "url.path": req.url?.split("?")[0] ?? "",
+      "agent.id": req.headers["x-agent-id"] as string | undefined,
+      "agentswarm.component": "api",
+    });
+
+    res.on("finish", () => {
+      if (spanEnded) return;
+      spanEnded = true;
+      span.setAttributes({
+        "http.response.status_code": statusCode,
+        "agentswarm.http.duration_ms": Math.round((performance.now() - startTime) * 10) / 10,
+      });
+      if (statusCode >= 500) {
+        span.setStatus({ code: 2, message: `HTTP ${statusCode}` });
+      }
+      span.end();
+    });
+
+    res.on("error", (err) => {
+      if (spanEnded) return;
+      spanEnded = true;
+      span.recordException(err);
+      span.setStatus({ code: 2, message: err.message });
+      span.end();
+    });
 
-    // ── 404 ──
-    res.writeHead(404);
-    res.end("Not Found");
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`[HTTP] ❌ ${req.method} ${req.url} → ${message}`);
-    if (!res.headersSent) {
-      res.writeHead(500, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: message }));
-    } else if (!res.writableEnded) {
-      res.end();
+    setCorsHeaders(req, res);
+
+    // ── Core routes (OPTIONS, health, auth, /me, /cancelled-tasks, /ping, /close) ──
+    if (await handleCore(req, res, req.headers["x-agent-id"] as string | undefined, apiKey)) return;
+
+    const pathSegments = getPathSegments(req.url || "");
+    const queryParams = parseQueryParams(req.url || "");
+    const myAgentId = req.headers["x-agent-id"] as string | undefined;
+
+    // ── Route handlers (order matters — first match wins) ──
+    const handlers: (() => Promise<boolean>)[] = [
+      () => handleAgentRegister(req, res, pathSegments, myAgentId),
+      () => handlePoll(req, res, pathSegments, queryParams, myAgentId),
+      () => handleSessionData(req, res, pathSegments, queryParams, myAgentId),
+      () => handleEcosystem(req, res, pathSegments, myAgentId),
+      () => handleTrackers(req, res, pathSegments),
+      () => handleWebhooks(req, res, pathSegments),
+      () => handleAgentsRest(req, res, pathSegments, queryParams, myAgentId),
+      () => handleBudgets(req, res, pathSegments, queryParams, myAgentId),
+      () => handleContext(req, res, pathSegments, queryParams, myAgentId),
+      () => handleTasks(req, res, pathSegments, queryParams, myAgentId),
+      () => handleStats(req, res, pathSegments, queryParams),
+      () => handleStatus(req, res, pathSegments, queryParams),
+      () => handleActiveSessions(req, res, pathSegments, queryParams, myAgentId),
+      () => handlePricing(req, res, pathSegments, queryParams, myAgentId),
+      () => handleSchedules(req, res, pathSegments, queryParams, myAgentId),
+      () => handleWorkflows(req, res, pathSegments, queryParams, myAgentId),
+      () => handleWorkflowEvents(req, res, pathSegments, queryParams),
+      () => handleApprovalRequests(req, res, pathSegments, queryParams),
+      () => handleConfig(req, res, pathSegments, queryParams),
+      () => handleKv(req, res, pathSegments, queryParams),
+      () => handleIntegrations(req, res, pathSegments),
+      () => handlePromptTemplates(req, res, pathSegments, queryParams),
+      () => handleDbQuery(req, res, pathSegments, queryParams),
+      () => handleRepos(req, res, pathSegments, queryParams),
+      () => handleSkills(req, res, pathSegments, queryParams, myAgentId),
+      () => handleMcpServers(req, res, pathSegments, queryParams),
+      () => handleMcpOAuth(req, res, pathSegments, queryParams),
+      () => handleMemory(req, res, pathSegments, myAgentId),
+      () => handlePagesPublic(req, res, pathSegments, queryParams),
+      () => handlePageProxy(req, res),
+      () => handlePages(req, res, pathSegments, queryParams, myAgentId),
+      () => handleApiKeys(req, res, pathSegments, queryParams),
+      () => handleHeartbeat(req, res, pathSegments),
+      () => handleEvents(req, res, pathSegments, queryParams, myAgentId),
+      () => handleUsers(req, res, pathSegments, queryParams),
+      () => handleSessions(req, res, pathSegments, queryParams),
+      () => handleInboxState(req, res, pathSegments, queryParams),
+      () => handleTaskTemplates(req, res, pathSegments, queryParams),
+      () => handleMcp(req, res, transports),
+    ];
+
+    try {
+      for (const handler of handlers) {
+        if (await handler()) return;
+      }
+
+      // ── 404 ──
+      res.writeHead(404);
+      res.end("Not Found");
+    } catch (err) {
+      span.recordException(err);
+      span.setStatus({ code: 2, message: err instanceof Error ? err.message : String(err) });
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[HTTP] ❌ ${req.method} ${req.url} → ${message}`);
+      if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: message }));
+      } else if (!res.writableEnded) {
+        res.end();
+      }
     }
-  }
+  });
 });
 
 // Store references in globalThis for hot reload persistence
@@ -250,9 +284,22 @@ try {
   throw err;
 }
 
+// Phase 2 of the cost-tracking plan: project the vendored models.dev snapshot
+// into pricing rows at boot. Lazy `getDb()` would also work, but doing it
+// here surfaces the count in the boot log and makes the API ready to recompute
+// USD before the first POST /api/session-costs lands.
+try {
+  const { seedPricingFromModelsDev } = await import("../be/seed-pricing");
+  seedPricingFromModelsDev();
+} catch (err) {
+  console.error("[startup] Failed to seed pricing rows:", err);
+}
+
 // business-use initialization (no-op if envs not set)
 initialize();
 
+await initOtel("api");
+
 httpServer
   .listen(port, async () => {
     console.log(`MCP HTTP server running on http://localhost:${port}/mcp`);

package/src/http/session-data.ts

@@ -13,6 +13,7 @@ import {
   getSessionLogsByTaskId,
   getTaskById,
 } from "../be/db";
+import { normalizeModelKey } from "../be/pricing-normalize";
 import type { SessionCost, SessionCostSource } from "../types";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
@@ -65,17 +66,24 @@ const createSessionCostRoute = route({
     inputTokens: z.number().int().optional(),
     outputTokens: z.number().int().optional(),
     cacheReadTokens: z.number().int().optional(),
-    cacheWriteTokens: z.number().int().optional(),
+    // Migration 063: nullable — adapters that can't honestly report cache writes
+    // (e.g. Codex SDK) prefer null over a faked 0.
+    cacheWriteTokens: z.number().int().nullable().optional(),
+    // Migration 063: new token classes previously dropped on the floor.
+    reasoningOutputTokens: z.number().int().nonnegative().optional(),
+    thinkingTokens: z.number().int().nonnegative().optional(),
     durationMs: z.number().int().optional(),
-    numTurns: z.number().int().optional(),
+    // Migration 063: nullable for adapters that can't honestly report numTurns.
+    numTurns: z.number().int().nullable().optional(),
     model: z.string().optional(),
     isError: z.boolean().optional(),
     /**
-     * Phase 6: when present, drives the codex pricing-table recompute path.
-     * Other providers ('claude' / 'pi' / 'opencode') always trust harness-reported USD.
-     * Optional / undefined keeps back-compat for existing callers.
+     * Phase 6 (extended migration 063): drives the API recompute path. After
+     * Phase 2 every provider with seeded pricing rows participates.
      */
-    provider: z.enum(["claude", "codex", "pi", "opencode"]).optional(),
+    provider: z
+      .enum(["claude", "claude-managed", "codex", "pi", "opencode", "devin", "gemini"])
+      .optional(),
     /**
      * Phase 6: epoch-ms timestamp used as the "active price at time T" lookup
      * basis. Defaults to `Date.now()` when omitted. Including it lets
@@ -185,35 +193,75 @@ export async function handleSessionData(
     try {
       const inputTokens = parsed.body.inputTokens ?? 0;
       const cachedInputTokens = parsed.body.cacheReadTokens ?? 0;
+      const cacheWriteTokens = parsed.body.cacheWriteTokens ?? 0;
       const outputTokens = parsed.body.outputTokens ?? 0;
-      const model = parsed.body.model || "opus";
+      // Phase 2: don't paper over a missing model with a fake default — that
+      // poisoned the pricing-table lookup against the wrong rate. Only the
+      // back-compat case (no provider tag) keeps "opus" so old callers don't
+      // explode.
+      const model = parsed.body.model || (parsed.body.provider ? "" : "opus");
 
-      // Phase 6: Codex USD recompute. When the worker reports `provider='codex'`
-      // and DB pricing rows exist for ALL three token classes at the lookup
-      // time, recompute `totalCostUsd` from tokens × DB prices and tag the
-      // row as 'pricing-table'. If any class has no row, fall back to the
-      // worker-reported value with `costSource='harness'` (back-compat for
-      // unseeded models). Claude / pi / opencode paths always use 'harness'.
+      // Phase 2: widen the recompute branch beyond codex. For any provider
+      // with a known model and seeded pricing rows, recompute `totalCostUsd`
+      // from tokens × DB prices and tag the row 'pricing-table'. When the
+      // (provider, model) pair has no pricing rows at all, tag 'unpriced' so
+      // the UI can flag it. When the provider isn't set, fall through with
+      // 'harness' (back-compat for older callers).
       let totalCostUsd = parsed.body.totalCostUsd;
       let costSource: SessionCostSource = "harness";
 
-      if (parsed.body.provider === "codex") {
+      if (parsed.body.provider && model) {
         const lookupTime = parsed.body.createdAt ?? Date.now();
-        const inputRow = getActivePricingRow("codex", model, "input", lookupTime);
-        const cachedRow = getActivePricingRow("codex", model, "cached_input", lookupTime);
-        const outputRow = getActivePricingRow("codex", model, "output", lookupTime);
+        // Phase 2 fix — different harnesses prepend routing prefixes
+        // (`openrouter/`, `github-copilot/`, …) to the same underlying model
+        // id. The pricing seed stores canonical (un-prefixed) keys, so we
+        // strip the prefix here before lookup. The original adapter-emitted
+        // string is still persisted to `session_costs.model` for debugging.
+        const lookupModel = normalizeModelKey(parsed.body.provider, model);
+        const inputRow = getActivePricingRow(
+          parsed.body.provider,
+          lookupModel,
+          "input",
+          lookupTime,
+        );
+        const cachedRow = getActivePricingRow(
+          parsed.body.provider,
+          lookupModel,
+          "cached_input",
+          lookupTime,
+        );
+        const outputRow = getActivePricingRow(
+          parsed.body.provider,
+          lookupModel,
+          "output",
+          lookupTime,
+        );
+        const cacheWriteRow = getActivePricingRow(
+          parsed.body.provider,
+          lookupModel,
+          "cache_write",
+          lookupTime,
+        );
 
-        if (inputRow && cachedRow && outputRow) {
-          // Mirror the existing computeCodexCostUsd logic: subtract cached
-          // tokens from input before billing the uncached portion at the full
-          // rate (Codex SDK reports input_tokens as TOTAL across the turn).
+        if (inputRow && outputRow) {
+          // Mirror the legacy codex semantic: uncached input is billed at the
+          // full rate, cached input at the discounted rate. Cache writes are
+          // billed separately when the provider's pricing table carries that
+          // class (anthropic) and the adapter reports a non-zero value.
           const uncachedInputTokens = Math.max(0, inputTokens - cachedInputTokens);
+          const cachedRate = cachedRow?.pricePerMillionUsd ?? 0;
+          const cacheWriteRate = cacheWriteRow?.pricePerMillionUsd ?? 0;
           totalCostUsd =
             (uncachedInputTokens * inputRow.pricePerMillionUsd +
-              cachedInputTokens * cachedRow.pricePerMillionUsd +
+              cachedInputTokens * cachedRate +
+              cacheWriteTokens * cacheWriteRate +
               outputTokens * outputRow.pricePerMillionUsd) /
             1_000_000;
           costSource = "pricing-table";
+        } else {
+          // Provider was tagged but we have no pricing rows for it; flag the
+          // row so the UI can show an "unpriced" badge instead of pretending.
+          costSource = "unpriced";
         }
       }
 
@@ -226,8 +274,11 @@ export async function handleSessionData(
         outputTokens,
         cacheReadTokens: cachedInputTokens,
         cacheWriteTokens: parsed.body.cacheWriteTokens ?? 0,
+        reasoningOutputTokens: parsed.body.reasoningOutputTokens ?? 0,
+        thinkingTokens: parsed.body.thinkingTokens ?? 0,
         durationMs: parsed.body.durationMs ?? 0,
-        numTurns: parsed.body.numTurns ?? 1,
+        // Migration 063: pass null through honestly instead of faking a 1.
+        numTurns: parsed.body.numTurns ?? null,
         model,
         isError: parsed.body.isError ?? false,
         costSource,

package/src/otel-impl.ts

@@ -0,0 +1,200 @@
+import {
+  context,
+  propagation,
+  ROOT_CONTEXT,
+  type Span,
+  SpanStatusCode,
+  trace,
+} from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import pkg from "../package.json";
+import type { SwarmSpan } from "./otel";
+import { scrubSecrets } from "./utils/secret-scrubber";
+
+type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+type Attributes = Record<string, AttributeValue | undefined>;
+
+const TRACER_NAME = "agent-swarm";
+const RAW_SPAN = Symbol("agent-swarm.raw-span");
+
+let sdk: NodeSDK | undefined;
+
+function decodeResourceAttributeValue(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function parseResourceAttributes(value = process.env.OTEL_RESOURCE_ATTRIBUTES): Attributes {
+  if (!value) return {};
+  const attributes: Attributes = {};
+  for (const pair of value.split(",")) {
+    const [rawKey, ...rawValueParts] = pair.split("=");
+    const key = rawKey?.trim();
+    if (!key) continue;
+    const rawValue = rawValueParts.join("=").trim();
+    if (!rawValue) continue;
+    attributes[key] = decodeResourceAttributeValue(rawValue);
+  }
+  return attributes;
+}
+
+function cleanAttributes(attributes?: Attributes): Record<string, AttributeValue> | undefined {
+  if (!attributes) return undefined;
+  const cleaned: Record<string, AttributeValue> = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value !== undefined) cleaned[key] = value;
+  }
+  return cleaned;
+}
+
+export function scrubOtelException(error: unknown): Error | string {
+  if (!(error instanceof Error)) {
+    return scrubSecrets(String(error));
+  }
+
+  const scrubbed = new Error(scrubSecrets(error.message));
+  scrubbed.name = error.name;
+  if (error.stack) {
+    scrubbed.stack = scrubSecrets(error.stack);
+  }
+  return scrubbed;
+}
+
+export function scrubOtelStatus(status: { code: number; message?: string }) {
+  return status.message === undefined
+    ? status
+    : {
+        ...status,
+        message: scrubSecrets(status.message),
+      };
+}
+
+type AdaptedSwarmSpan = SwarmSpan & { [RAW_SPAN]: Span };
+
+function spanAdapter(span: Span): AdaptedSwarmSpan {
+  return {
+    [RAW_SPAN]: span,
+    setAttribute(key, value) {
+      span.setAttribute(key, value);
+      return this;
+    },
+    setAttributes(attributes) {
+      const cleaned = cleanAttributes(attributes);
+      if (cleaned) span.setAttributes(cleaned);
+      return this;
+    },
+    addEvent(name, attributes) {
+      const cleaned = cleanAttributes(attributes);
+      span.addEvent(name, cleaned);
+      return this;
+    },
+    recordException(error) {
+      span.recordException(scrubOtelException(error));
+    },
+    setStatus(status) {
+      span.setStatus(scrubOtelStatus(status));
+      return this;
+    },
+    end() {
+      span.end();
+    },
+  };
+}
+
+export async function boot(serviceRole: string): Promise<void> {
+  if (sdk) return;
+
+  const configuredResourceAttributes = parseResourceAttributes();
+  const deploymentEnvironment =
+    configuredResourceAttributes["deployment.environment"] || process.env.NODE_ENV || "development";
+  const serviceName =
+    process.env.OTEL_SERVICE_NAME ||
+    (serviceRole === "api" ? "agent-swarm-api" : "agent-swarm-worker");
+  sdk = new NodeSDK({
+    resource: resourceFromAttributes({
+      ...configuredResourceAttributes,
+      [ATTR_SERVICE_NAME]: serviceName,
+      [ATTR_SERVICE_VERSION]: pkg.version,
+      "service.namespace": configuredResourceAttributes["service.namespace"] || "agent-swarm",
+      "service.instance.id": process.env.AGENT_ID || crypto.randomUUID(),
+      "deployment.environment": deploymentEnvironment,
+      env: configuredResourceAttributes.env || deploymentEnvironment,
+      "agentswarm.service.role": serviceRole,
+    }),
+    traceExporter: new OTLPTraceExporter(),
+  });
+
+  sdk.start();
+
+  const shutdown = async () => {
+    try {
+      await sdk?.shutdown();
+    } catch {
+      // Best-effort flush during process shutdown.
+    }
+  };
+
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+}
+
+export async function shutdown(): Promise<void> {
+  await sdk?.shutdown();
+  sdk = undefined;
+}
+
+export async function withSpan<T>(
+  name: string,
+  fn: (span: SwarmSpan) => Promise<T> | T,
+  attributes?: Attributes,
+): Promise<T> {
+  const tracer = trace.getTracer(TRACER_NAME);
+  return tracer.startActiveSpan(name, { attributes: cleanAttributes(attributes) }, async (span) => {
+    try {
+      const result = await fn(spanAdapter(span));
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(scrubOtelException(error));
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: scrubSecrets(error instanceof Error ? error.message : String(error)),
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+export function startSpan(name: string, attributes?: Attributes): SwarmSpan {
+  const span = trace.getTracer(TRACER_NAME).startSpan(name, {
+    attributes: cleanAttributes(attributes),
+  });
+  return spanAdapter(span);
+}
+
+export function withSpanContext<T>(span: SwarmSpan, fn: () => T): T {
+  const rawSpan = (span as Partial<AdaptedSwarmSpan>)[RAW_SPAN];
+  if (!rawSpan) return fn();
+  return context.with(trace.setSpan(context.active(), rawSpan), fn);
+}
+
+export async function withRemoteContext<T>(
+  carrier: Record<string, unknown>,
+  fn: () => Promise<T> | T,
+): Promise<T> {
+  const remoteContext = propagation.extract(ROOT_CONTEXT, carrier);
+  return context.with(remoteContext, fn);
+}
+
+export function injectTraceContext(headers: Record<string, string>): Record<string, string> {
+  propagation.inject(context.active(), headers);
+  return headers;
+}