@vauban-org/agent-sdk 0.16.0

package/src/otel/index.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./ingest.js";
+export * from "./trace-context.js";
+export * from "./attributes.js";

package/src/otel/ingest.ts

@@ -0,0 +1,294 @@
+/**
+ * OTel SDK initialization for external agents.
+ *
+ * Phase 2 — sprint-564 hotfix
+ *
+ * initVaubanSDK() now instantiates a BasicTracerProvider with an OTLP HTTP
+ * exporter and a BatchSpanProcessor. No host-side OTel setup is required.
+ * The collectorUrl defaults to the Alloy gateway that fans out to Tempo,
+ * Langfuse, and CC ingest.
+ *
+ * @see https://opentelemetry.io/docs/languages/js/instrumentation/
+ */
+
+import { trace } from "@opentelemetry/api";
+import {
+  BasicTracerProvider,
+  BatchSpanProcessor,
+  ConsoleSpanExporter,
+} from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { registerW3CPropagator } from "./trace-context.js";
+import { GEN_AI_AGENT_ID } from "./attributes.js";
+
+export type { OtlpSpan, OtlpAttribute, OtlpAttributeValue } from "./types.js";
+
+// ─── Legacy client interface (backward compat) ──────────────────────────────
+
+export interface IngestSpansResult {
+  accepted: number;
+  skipped?: number;
+  runs?: string[];
+  warnings?: string[];
+}
+
+export interface IngestSpansOptions {
+  origin?: string;
+}
+
+export interface OtelClient {
+  ingestSpans(
+    spans: { resourceSpans: unknown[] },
+    opts?: IngestSpansOptions
+  ): Promise<IngestSpansResult>;
+}
+
+export interface OtelClientOptions {
+  baseUrl: string;
+  getToken: () => Promise<string>;
+}
+
+export function createOtelClient(opts: OtelClientOptions): OtelClient {
+  const base = opts.baseUrl.replace(/\/$/, "");
+
+  return {
+    async ingestSpans(spans, ingestOpts) {
+      const token = await opts.getToken();
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+      };
+      if (ingestOpts?.origin) headers["X-Origin"] = ingestOpts.origin;
+
+      const response = await fetch(`${base}/api/otel/ingest`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(spans),
+      });
+
+      if (!response.ok) {
+        let message = `HTTP ${response.status}`;
+        try {
+          const body = (await response.json()) as {
+            error?: string;
+            message?: string;
+          };
+          message = body.error ?? body.message ?? message;
+        } catch {
+          /* ignore */
+        }
+        throw new Error(`OtelClient.ingestSpans: ${message}`);
+      }
+      return response.json() as Promise<IngestSpansResult>;
+    },
+  };
+}
+
+// ─── Real OTel SDK init (OTLP HTTP exporter) ───────────────────────────────
+
+export interface VaubanSDKOptions {
+  /** Vauban API key for the org (scope: cc:ingest). */
+  apiKey: string;
+  /**
+   * OTLP HTTP collector endpoint.
+   * Default: internal Alloy gateway that fans out to Tempo, Langfuse, CC ingest.
+   */
+  collectorUrl?: string;
+  /** Agent identifier (e.g. "my-product/trading-agent"). */
+  agentId: string;
+  /** Agent version (semver). */
+  agentVersion: string;
+  /** Organization ID (e.g. "my-org"). */
+  orgId: string;
+  /** Enable console exporter for debugging (default: false). */
+  debug?: boolean;
+  /**
+   * Command Center registry URL for auto-registration.
+   * When set, initVaubanSDK() sends a POST /api/registry/agents on startup
+   * so the agent appears in the dashboard /registry without manual setup.
+   * Default: undefined (opt-in — no auto-registration without explicit URL).
+   */
+  registryUrl?: string;
+  /** Human-readable agent name for the registry (default: agentId). */
+  agentName?: string;
+  /** Capabilities list for the registry (e.g. ["code-generation", "review"]). */
+  capabilities?: string[];
+  /** Repository URL for the registry card. */
+  repoUrl?: string;
+}
+
+let _sdkProvider: BasicTracerProvider | null = null;
+
+/**
+ * Initialize the Vauban OTel SDK. Call once at process startup.
+ *
+ * Instantiates a BasicTracerProvider with an OTLP HTTP exporter on the
+ * configured collector endpoint, registers process-level resource attributes,
+ * and installs a shutdown hook. No host-side OTel setup is required.
+ *
+ * Returns the tracer provider for introspection.
+ */
+export function initVaubanSDK(opts: VaubanSDKOptions): BasicTracerProvider {
+  const collectorUrl =
+    opts.collectorUrl ?? "http://alloy.observability.svc.cluster.local:4318";
+
+  const resource = resourceFromAttributes({
+    "service.name": opts.agentId,
+    "service.version": opts.agentVersion,
+    [GEN_AI_AGENT_ID]: opts.agentId,
+    "vauban.org.id": opts.orgId,
+  });
+
+  // OTLP HTTP exporter
+  const otlpExporter = new OTLPTraceExporter({
+    url: `${collectorUrl.replace(/\/$/, "")}/v1/traces`,
+    headers: { Authorization: `Bearer ${opts.apiKey}` },
+  });
+
+  const spanProcessors = [new BatchSpanProcessor(otlpExporter)];
+
+  if (opts.debug) {
+    spanProcessors.push(new BatchSpanProcessor(new ConsoleSpanExporter()));
+  }
+
+  const provider = new BasicTracerProvider({ resource, spanProcessors });
+  trace.setGlobalTracerProvider(provider);
+
+  // Register W3C Trace Context propagator so traceparent/tracestate headers
+  // are injected/extracted automatically on delegation boundaries.
+  registerW3CPropagator();
+
+  // Graceful shutdown
+  const shutdown = () => {
+    provider.forceFlush().finally(() => provider.shutdown());
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+
+  _sdkProvider = provider;
+
+  console.log(
+    `[vauban-sdk] OTel enabled → ${collectorUrl} | agent=${opts.agentId} v${opts.agentVersion}`
+  );
+
+  // ── Auto-registration (fire-and-forget) ─────────────────────────────────
+  if (opts.registryUrl) {
+    const registryUrl = opts.registryUrl.replace(/\/$/, "");
+    _registryBaseUrl = registryUrl;
+    _apiKey = opts.apiKey;
+    fetch(`${registryUrl}/api/registry/agents`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${opts.apiKey}`,
+      },
+      body: JSON.stringify({
+        agentId: opts.agentId,
+        orgId: opts.orgId,
+        name: opts.agentName ?? opts.agentId,
+        version: opts.agentVersion,
+        capabilities: opts.capabilities ?? [],
+        repoUrl: opts.repoUrl,
+        sdkVersion: "0.14.3",
+        metadata: { collectorUrl },
+      }),
+    })
+      .then((res) => {
+        if (res.ok) {
+          console.log(`[vauban-sdk] agent registered → ${registryUrl}`);
+        } else {
+          console.warn(
+            `[vauban-sdk] registry returned ${res.status} — agent not registered`
+          );
+        }
+      })
+      .catch((err) => {
+        console.warn(
+          `[vauban-sdk] registry unreachable — agent not auto-registered: ${
+            (err as Error).message
+          }`
+        );
+      });
+  }
+
+  return provider;
+}
+
+export function getSDKProvider(): BasicTracerProvider | null {
+  return _sdkProvider;
+}
+
+// ── Run reporting ────────────────────────────────────────────────────────
+
+let _registryBaseUrl: string | undefined;
+let _apiKey: string | undefined;
+
+/**
+ * Report a run start to the CC registry.
+ * Called automatically by initVaubanSDK when registryUrl is set,
+ * and manually by agents that want their cycles to appear in /runs.
+ */
+export async function reportRunStart(opts: {
+  agentId: string;
+  runId?: string;
+  model?: string;
+  provider?: string;
+}): Promise<{ id: string } | null> {
+  const base = _registryBaseUrl;
+  const key = _apiKey;
+  if (!base || !key) return null;
+  try {
+    const res = await fetch(`${base}/api/runs`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        agentId: opts.agentId,
+        runId: opts.runId,
+        model: opts.model,
+        provider: opts.provider,
+      }),
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as { id: string };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Report a run finish to the CC registry.
+ */
+export async function reportRunFinish(opts: {
+  runId: string;
+  status: "success" | "failed" | "completed";
+  inputTokens?: number;
+  outputTokens?: number;
+  costUsd?: number;
+  errorMessage?: string;
+}): Promise<void> {
+  const base = _registryBaseUrl;
+  const key = _apiKey;
+  if (!base || !key) return;
+  try {
+    await fetch(`${base}/api/runs/${encodeURIComponent(opts.runId)}`, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        status: opts.status,
+        input_tokens: opts.inputTokens,
+        output_tokens: opts.outputTokens,
+        cost_usd: opts.costUsd,
+        error_message: opts.errorMessage,
+      }),
+    });
+  } catch {
+    // fire-and-forget
+  }
+}

package/src/otel/trace-context.ts

@@ -0,0 +1,197 @@
+/**
+ * W3C Trace Context propagation utilities for delegation chains.
+ *
+ * Implements W3C Trace Context Level 1 (traceparent / tracestate) via
+ * the @opentelemetry/api propagation and context APIs — no @opentelemetry/core
+ * dependency required.
+ *
+ * Spec: https://www.w3.org/TR/trace-context/
+ */
+
+import {
+  context,
+  propagation,
+  trace,
+  createTraceState,
+  ROOT_CONTEXT,
+  type Span,
+  type SpanContext,
+  defaultTextMapGetter,
+  defaultTextMapSetter,
+  type TextMapSetter,
+  type TextMapGetter,
+} from "@opentelemetry/api";
+
+// ─── W3C Trace Context propagator (inline — no @opentelemetry/core dep) ──────
+
+const TRACEPARENT_HEADER = "traceparent";
+const TRACESTATE_HEADER = "tracestate";
+
+// Format: 00-<32hex traceId>-<16hex spanId>-<2hex flags>
+const TRACEPARENT_RE =
+  /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
+
+class W3CTraceContextPropagatorImpl {
+  inject(
+    ctx: ReturnType<typeof context.active>,
+    carrier: Record<string, string>,
+    setter: TextMapSetter<Record<string, string>>
+  ): void {
+    const spanContext = trace.getSpanContext(ctx);
+    if (!spanContext || !isValidSpanCtx(spanContext)) return;
+
+    const flags = spanContext.traceFlags
+      .toString(16)
+      .padStart(2, "0");
+    const traceparent = `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`;
+    setter.set(carrier, TRACEPARENT_HEADER, traceparent);
+
+    if (spanContext.traceState) {
+      const ts = spanContext.traceState.serialize();
+      if (ts) setter.set(carrier, TRACESTATE_HEADER, ts);
+    }
+  }
+
+  extract(
+    ctx: ReturnType<typeof context.active>,
+    carrier: Record<string, string>,
+    getter: TextMapGetter<Record<string, string>>
+  ): ReturnType<typeof context.active> {
+    const traceparentHeader = getter.get(carrier, TRACEPARENT_HEADER);
+    if (!traceparentHeader) return ctx;
+    const raw = Array.isArray(traceparentHeader)
+      ? traceparentHeader[0]
+      : traceparentHeader;
+    if (!raw) return ctx;
+
+    const match = TRACEPARENT_RE.exec(raw);
+    if (!match) return ctx;
+
+    const traceId = match[1]!.toLowerCase();
+    const spanId = match[2]!.toLowerCase();
+    const traceFlags = parseInt(match[3]!, 16);
+
+    // Reject all-zero ids
+    if (
+      traceId === "0".repeat(32) ||
+      spanId === "0".repeat(16)
+    )
+      return ctx;
+
+    const tracestateHeader = getter.get(carrier, TRACESTATE_HEADER);
+    const rawTracestate = Array.isArray(tracestateHeader)
+      ? tracestateHeader.join(",")
+      : tracestateHeader;
+
+    const spanContext: SpanContext = {
+      traceId,
+      spanId,
+      traceFlags,
+      traceState: rawTracestate
+        ? createTraceState(rawTracestate)
+        : undefined,
+      isRemote: true,
+    };
+
+    return trace.setSpanContext(ctx, spanContext);
+  }
+}
+
+const _propagator = new W3CTraceContextPropagatorImpl();
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Registers the W3C Trace Context propagator as the global OTel propagator.
+ * Safe to call multiple times — idempotent (re-registers on every call).
+ *
+ * Called automatically by initVaubanSDK. External callers only need this when
+ * using the trace-context utilities without calling initVaubanSDK.
+ */
+export function registerW3CPropagator(): void {
+  propagation.setGlobalPropagator({
+    inject(ctx, carrier, setter) {
+      _propagator.inject(
+        ctx,
+        carrier as Record<string, string>,
+        setter as TextMapSetter<Record<string, string>>
+      );
+    },
+    extract(ctx, carrier, getter) {
+      return _propagator.extract(
+        ctx,
+        carrier as Record<string, string>,
+        getter as TextMapGetter<Record<string, string>>
+      );
+    },
+    fields() {
+      return [TRACEPARENT_HEADER, TRACESTATE_HEADER];
+    },
+  });
+}
+
+/**
+ * Injects W3C traceparent/tracestate headers into a carrier map.
+ *
+ * Uses the active span context (or the provided OTel Context if given).
+ *
+ * @param headers - Mutable header map to inject into (safe to start empty).
+ * @param ctx     - Optional OTel Context; defaults to context.active().
+ * @returns The same map with traceparent/tracestate added (or unchanged if
+ *          no active span context is available).
+ */
+export function injectTraceContext(
+  headers: Record<string, string>,
+  ctx?: ReturnType<typeof context.active>
+): Record<string, string> {
+  const activeCtx = ctx ?? context.active();
+  propagation.inject(activeCtx, headers, defaultTextMapSetter);
+  return headers;
+}
+
+/**
+ * Extracts a SpanContext from W3C traceparent/tracestate headers.
+ *
+ * @param headers - Header map (e.g. incoming HTTP request headers).
+ * @returns The extracted SpanContext, or null if no valid traceparent header
+ *          is present or the header is malformed.
+ */
+export function extractTraceContext(
+  headers: Record<string, string>
+): SpanContext | null {
+  const extracted = propagation.extract(
+    ROOT_CONTEXT,
+    headers,
+    defaultTextMapGetter
+  );
+  const spanCtx = trace.getSpanContext(extracted);
+  if (!spanCtx || !isValidSpanCtx(spanCtx)) return null;
+  return spanCtx;
+}
+
+/**
+ * Sets `gen_ai.delegation.parent_run_id` on the given span.
+ *
+ * Every span emitted by a child delegation cycle MUST carry this attribute
+ * so that trace queries in Tempo / Langfuse can reconstruct delegation trees.
+ *
+ * @param span        - The OTel Span to annotate (must be recording).
+ * @param parentRunId - The runId of the parent agent cycle.
+ */
+export function withDelegationAttribute(
+  span: Span,
+  parentRunId: string
+): void {
+  span.setAttribute("gen_ai.delegation.parent_run_id", parentRunId);
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+function isValidSpanCtx(spanCtx: SpanContext): boolean {
+  return (
+    spanCtx.traceId.length === 32 &&
+    spanCtx.spanId.length === 16 &&
+    spanCtx.traceId !== "0".repeat(32) &&
+    spanCtx.spanId !== "0".repeat(16)
+  );
+}

package/src/otel/types.ts

@@ -0,0 +1,49 @@
+/**
+ * OTLP HTTP/JSON type shim — @vauban-org/agent-sdk v0.5.3 (sprint-523 Bloc 3).
+ *
+ * Mirrors src/otel/otlp-decoder.ts so clients building OTLP payloads
+ * (LangGraph, AutoGen, custom exporters) can type-check their spans
+ * without depending on the command-center server source.
+ *
+ * These types follow the OTLP HTTP/JSON wire format:
+ *   https://opentelemetry.io/docs/specs/otlp/#otlphttp
+ */
+
+export interface OtlpAttributeValue {
+  stringValue?: string;
+  intValue?: string;
+  boolValue?: boolean;
+  doubleValue?: number;
+  arrayValue?: { values: OtlpAttributeValue[] };
+}
+
+export interface OtlpAttribute {
+  key: string;
+  value: OtlpAttributeValue;
+}
+
+export interface OtlpSpan {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  kind?: number;
+  startTimeUnixNano: string;
+  endTimeUnixNano: string;
+  attributes: OtlpAttribute[];
+  status?: { code: number; message?: string };
+}
+
+export interface OtlpScopeSpans {
+  scope: { name: string; version?: string };
+  spans: OtlpSpan[];
+}
+
+export interface OtlpResourceSpans {
+  resource: { attributes: OtlpAttribute[] };
+  scopeSpans: OtlpScopeSpans[];
+}
+
+export interface OtlpRequest {
+  resourceSpans: OtlpResourceSpans[];
+}