@desplega.ai/agent-swarm 1.79.4 → 1.80.1

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;
+}

package/src/otel.ts

@@ -0,0 +1,132 @@
+export type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+export type Attributes = Record<string, AttributeValue | undefined>;
+
+type SpanStatus = {
+  code: number;
+  message?: string;
+};
+
+export type SwarmSpan = {
+  setAttribute: (key: string, value: AttributeValue) => SwarmSpan;
+  setAttributes: (attributes: Attributes) => SwarmSpan;
+  addEvent: (name: string, attributes?: Attributes) => SwarmSpan;
+  recordException: (error: unknown) => void;
+  setStatus: (status: SpanStatus) => SwarmSpan;
+  end: () => void;
+};
+
+const enabled = Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+
+const NOOP_SPAN: SwarmSpan = {
+  setAttribute: () => NOOP_SPAN,
+  setAttributes: () => NOOP_SPAN,
+  addEvent: () => NOOP_SPAN,
+  recordException: () => {},
+  setStatus: () => NOOP_SPAN,
+  end: () => {},
+};
+
+let initialized = false;
+let realWithSpan:
+  | (<T>(
+      name: string,
+      fn: (span: SwarmSpan) => Promise<T> | T,
+      attributes?: Attributes,
+    ) => Promise<T>)
+  | undefined;
+let realStartSpan: ((name: string, attributes?: Attributes) => SwarmSpan) | undefined;
+let realWithRemoteContext:
+  | (<T>(carrier: Record<string, unknown>, fn: () => Promise<T> | T) => Promise<T>)
+  | undefined;
+let realWithSpanContext: (<T>(span: SwarmSpan, fn: () => T) => T) | undefined;
+let realInjectTraceContext:
+  | ((headers: Record<string, string>) => Record<string, string>)
+  | undefined;
+let realShutdown: (() => Promise<void>) | undefined;
+
+export function isOtelEnabled(): boolean {
+  return enabled;
+}
+
+export function isPollTracingEnabled(): boolean {
+  const v = (process.env.OTEL_TRACE_POLL ?? "").toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
+export async function initOtel(serviceRole = process.env.AGENT_ROLE || "api"): Promise<void> {
+  if (!enabled || initialized) return;
+  initialized = true;
+
+  try {
+    const impl = await import("./otel-impl");
+    await impl.boot(serviceRole);
+    realWithSpan = impl.withSpan;
+    realStartSpan = impl.startSpan;
+    realWithRemoteContext = impl.withRemoteContext;
+    realWithSpanContext = impl.withSpanContext;
+    realInjectTraceContext = impl.injectTraceContext;
+    realShutdown = impl.shutdown;
+    console.log(
+      `[OTel] enabled for ${process.env.OTEL_SERVICE_NAME ?? "agent-swarm"} (${serviceRole})`,
+    );
+  } catch (error) {
+    console.warn(`[OTel] disabled after initialization failure: ${error}`);
+  }
+}
+
+export async function withSpan<T>(
+  name: string,
+  fn: (span: SwarmSpan) => Promise<T> | T,
+  attributes?: Attributes,
+): Promise<T> {
+  if (!enabled || !realWithSpan) {
+    return fn(NOOP_SPAN);
+  }
+  return realWithSpan(name, fn, attributes);
+}
+
+export function startSpan(name: string, attributes?: Attributes): SwarmSpan {
+  if (!enabled || !realStartSpan) {
+    return NOOP_SPAN;
+  }
+  return realStartSpan(name, attributes);
+}
+
+export function withSpanContext<T>(span: SwarmSpan, fn: () => T): T {
+  if (!enabled || !realWithSpanContext) {
+    return fn();
+  }
+  return realWithSpanContext(span, fn);
+}
+
+export async function withRemoteContext<T>(
+  carrier: Record<string, unknown>,
+  fn: () => Promise<T> | T,
+): Promise<T> {
+  if (!enabled || !realWithRemoteContext) {
+    return fn();
+  }
+  return realWithRemoteContext(carrier, fn);
+}
+
+export function injectTraceContext(headers: Record<string, string>): Record<string, string> {
+  if (!enabled || !realInjectTraceContext) {
+    return headers;
+  }
+  return realInjectTraceContext(headers);
+}
+
+export async function shutdownOtel(): Promise<void> {
+  if (!realShutdown) return;
+  await realShutdown();
+}
+
+export function _resetOtelForTests() {
+  initialized = false;
+  realWithSpan = undefined;
+  realStartSpan = undefined;
+  realWithRemoteContext = undefined;
+  realWithSpanContext = undefined;
+  realInjectTraceContext = undefined;
+  realShutdown = undefined;
+}

package/src/providers/claude-adapter.ts

@@ -1,7 +1,12 @@
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { computeContextUsed, getContextWindowSize } from "../utils/context-window";
+import {
+  CONTEXT_FORMULA,
+  clampContextPercent,
+  computeContextUsedUnified,
+  getContextWindowSize,
+} from "../utils/context-window";
 import { validateClaudeCredentials } from "../utils/credentials";
 import {
   parseStderrForErrors,
@@ -465,6 +470,10 @@ class ClaudeSession implements ProviderSession {
         this._sessionId = json.session_id;
         this.emit({ type: "session_init", sessionId: json.session_id, provider: "claude" });
         if (json.model) {
+          // Phase 4: the CLI's `init.model` reflects the actual model after any
+          // backoff/fallback. Update `this.model` so subsequent CostData rows
+          // (and the pricing lookup the API runs) use the right rate.
+          this.model = json.model;
           this.contextWindowSize = getContextWindowSize(json.model);
         }
       }
@@ -487,6 +496,10 @@ class ClaudeSession implements ProviderSession {
               output_tokens?: number;
               cache_read_input_tokens?: number;
               cache_creation_input_tokens?: number;
+              // Phase 4: claude extended-thinking flows surface this — the
+              // CLI emits `thinking_input_tokens` when the model produced
+              // thinking content during the turn.
+              thinking_input_tokens?: number;
             }
           | undefined;
 
@@ -499,8 +512,12 @@ class ClaudeSession implements ProviderSession {
           outputTokens: usage?.output_tokens ?? 0,
           cacheReadTokens: usage?.cache_read_input_tokens ?? 0,
           cacheWriteTokens: usage?.cache_creation_input_tokens ?? 0,
+          // Phase 4: surface thinking tokens; previously dropped on the floor.
+          thinkingTokens: usage?.thinking_input_tokens ?? 0,
           durationMs: json.duration_ms || 0,
-          numTurns: json.num_turns || 1,
+          // Phase 4: honest null when the CLI omits num_turns instead of a
+          // faked `1` (would have under-counted in dashboards).
+          numTurns: json.num_turns ?? null,
           model: this.model,
           isError: json.is_error || false,
           provider: "claude",
@@ -524,8 +541,29 @@ class ClaudeSession implements ProviderSession {
       // Tool use from assistant messages — emit tool_start for auto-progress
       if (json.type === "assistant" && json.message) {
         const message = json.message as {
-          content?: Array<{ type: string; name?: string; id?: string; input?: unknown }>;
+          content?: Array<{
+            type: string;
+            name?: string;
+            id?: string;
+            input?: unknown;
+            text?: string;
+          }>;
         };
+
+        // Emit a `message` event BEFORE any tool_start events for this turn.
+        // The runner uses this as an "assistant turn boundary" to implicit-close
+        // any worker.tool spans left open by the previous turn (the Claude CLI
+        // doesn't emit per-tool completion events for harness-side tools like
+        // Bash/Read/Edit, so without this boundary their spans would stay open
+        // until session shutdown and report inflated duration_ms).
+        const text = Array.isArray(message.content)
+          ? message.content
+              .filter((b) => b.type === "text" && typeof b.text === "string")
+              .map((b) => b.text as string)
+              .join("")
+          : "";
+        this.emit({ type: "message", role: "assistant", content: text });
+
         if (message.content) {
           for (const block of message.content) {
             if (block.type === "tool_use" && block.name) {
@@ -539,18 +577,26 @@ class ClaudeSession implements ProviderSession {
           }
         }
 
-        // Context usage extraction from assistant message usage
+        // Context usage extraction from assistant message usage.
+        // Phase 9: unified `input + cache + output` formula across every
+        // provider so cross-provider percent comparisons are meaningful.
         if (json.message.usage) {
           const usage = json.message.usage;
-          const contextUsed = computeContextUsed(usage);
+          const contextUsed = computeContextUsedUnified({
+            inputTokens: usage.input_tokens,
+            cacheReadTokens: usage.cache_read_input_tokens,
+            cacheCreateTokens: usage.cache_creation_input_tokens,
+            outputTokens: usage.output_tokens,
+          });
           const contextTotal = this.contextWindowSize;
 
           this.emit({
             type: "context_usage",
             contextUsedTokens: contextUsed,
             contextTotalTokens: contextTotal,
-            contextPercent: contextTotal > 0 ? (contextUsed / contextTotal) * 100 : 0,
+            contextPercent: clampContextPercent(contextUsed, contextTotal) ?? 0,
             outputTokens: usage.output_tokens ?? 0,
+            contextFormula: CONTEXT_FORMULA,
           });
         }
       }

package/src/providers/claude-managed-adapter.ts

@@ -59,8 +59,15 @@ import type {
 import type { SkillCreateResponse as Skill } from "@anthropic-ai/sdk/resources/beta/skills";
 
 import { checkToolLoop } from "../hooks/tool-loop-detection";
+import {
+  CONTEXT_FORMULA,
+  clampContextPercent,
+  computeContextUsedUnified,
+  getContextWindowSize,
+} from "../utils/context-window";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { computeClaudeManagedCostUsd } from "./claude-managed-models";
+import { getRuntimeFeePerHour } from "./claude-managed-pricing";
 import { createClaudeManagedSwarmEventHandler } from "./claude-managed-swarm-events";
 import type {
   CostData,
@@ -113,13 +120,10 @@ const REQUIRED_ENV_VARS = [
   "MANAGED_ENVIRONMENT_ID",
 ] as const;
 
-/**
- * Default context window for managed Claude sessions when we don't have a
- * model-specific override. Sized to match Sonnet 4.x (1M extended-context
- * variant). The Phase 4 pricing-table commit will replace this with a
- * per-model lookup.
- */
-const DEFAULT_CONTEXT_TOTAL_TOKENS = 1_000_000;
+// Phase 5: removed the hardcoded `DEFAULT_CONTEXT_TOTAL_TOKENS = 1_000_000`.
+// The adapter now calls `getContextWindowSize(this.model)` from
+// `src/utils/context-window.ts`, which resolves shortnames + dated full ids
+// so haiku-4-5 sessions don't pretend to have a 1M window.
 
 /**
  * Compose the per-session user-message content blocks. Returns two blocks:
@@ -187,6 +191,8 @@ function emptyCost(config: ProviderSessionConfig, model: string): CostData {
     numTurns: 0,
     model,
     isError: false,
+    // Phase 3 — tag every emitted CostData so the API's recompute path engages.
+    provider: "claude-managed",
   };
 }
 
@@ -374,6 +380,11 @@ class ClaudeManagedSession implements ProviderSession {
    * 2. Anthropic's $0.08/session-hour runtime fee — billed continuously by
    *    Anthropic regardless of model usage, so we add it here to surface in
    *    the swarm's per-session cost UI.
+   *
+   * Phase 5: the harness-local USD is still computed here, but the server-side
+   * recompute path (`POST /api/session-costs` after Phase 2) will reprice the
+   * row against the seeded pricing-table values and tag `costSource='pricing-table'`.
+   * The runtime fee comes from the same table now (`token_class='runtime_hour'`).
    */
   private snapshotCost(isError: boolean): CostData {
     const durationMs = Date.now() - this.startedAt;
@@ -384,9 +395,11 @@ class ClaudeManagedSession implements ProviderSession {
       this.cost.cacheReadTokens ?? 0,
       this.cost.cacheWriteTokens ?? 0,
     );
-    // $0.08 / session-hour. Sandbox runtime is billed by wallclock, so we
-    // amortize linearly across the session's `durationMs`.
-    const runtimeFeeUsd = (durationMs / 3_600_000) * 0.08;
+    // Phase 5: read the runtime fee from the pricing table when available so
+    // we have one source of truth. Falls back to the historical $0.08/hr
+    // constant if the row hasn't been seeded yet (e.g. on a fresh DB before
+    // seed-pricing.ts ran).
+    const runtimeFeeUsd = (durationMs / 3_600_000) * getRuntimeFeePerHour();
     return {
       ...this.cost,
       durationMs,
@@ -506,12 +519,15 @@ class ClaudeManagedSession implements ProviderSession {
         // this event. Emit a `compaction` ProviderEvent with the values we
         // *do* know; consumers that need richer data can subscribe to
         // `raw_log` for the original payload.
+        // Phase 5 — pre-compact tokens are an inferred proxy (running input
+        // total); flag the compactTrigger as 'auto-inferred' so downstream
+        // dashboards can distinguish a real trigger value from our guess.
         const _cc = event as BetaManagedAgentsAgentThreadContextCompactedEvent;
         this.emit({
           type: "compaction",
           preCompactTokens: this.cost.inputTokens ?? 0,
-          compactTrigger: "auto",
-          contextTotalTokens: DEFAULT_CONTEXT_TOTAL_TOKENS,
+          compactTrigger: "auto-inferred",
+          contextTotalTokens: getContextWindowSize(this.cost.model),
         });
         return { terminal: false, isError: false };
       }
@@ -524,16 +540,26 @@ class ClaudeManagedSession implements ProviderSession {
           (this.cost.cacheReadTokens ?? 0) + usage.cache_read_input_tokens;
         this.cost.cacheWriteTokens =
           (this.cost.cacheWriteTokens ?? 0) + usage.cache_creation_input_tokens;
-        this.cost.numTurns += 1;
-
-        const used = (this.cost.inputTokens ?? 0) + (this.cost.outputTokens ?? 0);
-        const total = DEFAULT_CONTEXT_TOTAL_TOKENS;
+        this.cost.numTurns = (this.cost.numTurns ?? 0) + 1;
+
+        // Phase 5 + Phase 9: unified `input + cache + output` formula AND a
+        // per-model window via `getContextWindowSize`. Previously this used
+        // a hardcoded 1M window and ignored cache — fine for sonnet/opus,
+        // wrong for haiku and any future smaller-window model.
+        const used = computeContextUsedUnified({
+          inputTokens: this.cost.inputTokens,
+          cacheReadTokens: this.cost.cacheReadTokens,
+          cacheCreateTokens: this.cost.cacheWriteTokens,
+          outputTokens: this.cost.outputTokens,
+        });
+        const total = getContextWindowSize(this.cost.model);
         this.emit({
           type: "context_usage",
           contextUsedTokens: used,
           contextTotalTokens: total,
-          contextPercent: Math.min(100, (used / total) * 100),
+          contextPercent: clampContextPercent(used, total),
           outputTokens: this.cost.outputTokens ?? 0,
+          contextFormula: CONTEXT_FORMULA,
         });
         return { terminal: false, isError: false };
       }

package/src/providers/claude-managed-pricing.ts

@@ -0,0 +1,34 @@
+/**
+ * Phase 5 — small adapter-side pricing constants for claude-managed.
+ *
+ * The API server's pricing table is the canonical store (seeded by
+ * `src/be/seed-pricing.ts`). Workers can't touch the DB directly (DB
+ * boundary), so the adapter keeps a local constant for the runtime fee
+ * and lets the API-side recompute path (Phase 2) override the resulting
+ * `totalCostUsd` with the canonical figure. The constant here is what
+ * shows up in the worker's local logs before the row hits the server.
+ *
+ * If/when we plumb pricing through the worker bootstrap (HTTP fetch of
+ * `/api/pricing` at session start), this module is the place to swap.
+ */
+
+/**
+ * USD per session-hour for managed claude runtime. Source:
+ * https://docs.claude.com/en/api/agent-sdk/managed-runtime#pricing
+ * (verified 2026-04-28). Override at runtime via env for ops bumps without
+ * a redeploy.
+ */
+export const RUNTIME_FEE_USD_PER_HOUR = (() => {
+  const raw = process.env.CLAUDE_MANAGED_RUNTIME_FEE_USD_PER_HOUR;
+  const n = raw ? Number(raw) : NaN;
+  if (Number.isFinite(n) && n >= 0) return n;
+  return 0.08;
+})();
+
+/**
+ * Adapter helper. Always returns a finite number — never crashes the
+ * cost snapshot.
+ */
+export function getRuntimeFeePerHour(): number {
+  return RUNTIME_FEE_USD_PER_HOUR;
+}