@vauban-org/agent-sdk 0.16.0

package/dist/otel/attributes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * OTel gen_ai.* semantic convention constants for Vauban agents.
+ *
+ * Spec: https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ *
+ * All standard gen_ai.* attributes follow the OTel semantic conventions.
+ * Custom Vauban attributes (gen_ai.agent.id, gen_ai.delegation.parent_run_id,
+ * gen_ai.cost.usd) are prefixed gen_ai.* to stay in the same namespace.
+ */
+import type { Span } from "@opentelemetry/api";
+/** AI system identifier, e.g. "anthropic", "deepseek", "groq". */
+export declare const GEN_AI_SYSTEM: "gen_ai.system";
+/** Model name as requested, e.g. "claude-sonnet-4-6". */
+export declare const GEN_AI_REQUEST_MODEL: "gen_ai.request.model";
+/** Maximum token limit requested. */
+export declare const GEN_AI_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens";
+/** Actual model used in the response (may differ from request). */
+export declare const GEN_AI_RESPONSE_MODEL: "gen_ai.response.model";
+/** Number of input/prompt tokens consumed. */
+export declare const GEN_AI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+/** Number of output/completion tokens generated. */
+export declare const GEN_AI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+/** Total tokens (input + output). */
+export declare const GEN_AI_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens";
+/** High-level operation: "chat" | "completion" | "embedding". */
+export declare const GEN_AI_OPERATION_NAME: "gen_ai.operation.name";
+/** Agent / runner identifier (Vauban extension). */
+export declare const GEN_AI_AGENT_ID: "gen_ai.agent.id";
+/**
+ * Parent run ID for delegation chain tracking (Sprint B).
+ * Must match `withDelegationAttribute` in trace-context.ts.
+ */
+export declare const GEN_AI_DELEGATION_PARENT_RUN_ID: "gen_ai.delegation.parent_run_id";
+/**
+ * Computed cost in USD (Vauban extension).
+ * Set by OutcomeTracker when available; stub value 0 until wired.
+ */
+export declare const GEN_AI_COST_USD: "gen_ai.cost.usd";
+export interface GenAiAttributes {
+    /** @see GEN_AI_SYSTEM */
+    "gen_ai.system"?: string;
+    /** @see GEN_AI_REQUEST_MODEL */
+    "gen_ai.request.model"?: string;
+    /** @see GEN_AI_REQUEST_MAX_TOKENS */
+    "gen_ai.request.max_tokens"?: number;
+    /** @see GEN_AI_RESPONSE_MODEL */
+    "gen_ai.response.model"?: string;
+    /** @see GEN_AI_USAGE_INPUT_TOKENS */
+    "gen_ai.usage.input_tokens"?: number;
+    /** @see GEN_AI_USAGE_OUTPUT_TOKENS */
+    "gen_ai.usage.output_tokens"?: number;
+    /** @see GEN_AI_USAGE_TOTAL_TOKENS */
+    "gen_ai.usage.total_tokens"?: number;
+    /** @see GEN_AI_OPERATION_NAME */
+    "gen_ai.operation.name"?: string;
+    /** @see GEN_AI_AGENT_ID */
+    "gen_ai.agent.id"?: string;
+    /** @see GEN_AI_DELEGATION_PARENT_RUN_ID */
+    "gen_ai.delegation.parent_run_id"?: string;
+    /** @see GEN_AI_COST_USD */
+    "gen_ai.cost.usd"?: number;
+}
+/**
+ * Sets all provided gen_ai.* attributes on a recording span.
+ * Undefined values are skipped (not set).
+ *
+ * @param span  - The OTel Span to annotate (must be recording).
+ * @param attrs - Partial bag of gen_ai.* attributes.
+ */
+export declare function setGenAiAttributes(span: Span, attrs: Partial<GenAiAttributes>): void;
+//# sourceMappingURL=attributes.d.ts.map

package/dist/otel/attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/otel/attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAI/C,kEAAkE;AAClE,eAAO,MAAM,aAAa,EAAG,eAAwB,CAAC;AAEtD,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAC;AAEpE,qCAAqC;AACrC,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAE9E,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,EAAG,uBAAgC,CAAC;AAEtE,8CAA8C;AAC9C,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAE9E,oDAAoD;AACpD,eAAO,MAAM,0BAA0B,EACrC,4BAAqC,CAAC;AAExC,qCAAqC;AACrC,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAE9E,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,EAAG,uBAAgC,CAAC;AAItE,oDAAoD;AACpD,eAAO,MAAM,eAAe,EAAG,iBAA0B,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,+BAA+B,EAC1C,iCAA0C,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAG,iBAA0B,CAAC;AAI1D,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qCAAqC;IACrC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,iCAAiC;IACjC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qCAAqC;IACrC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,sCAAsC;IACtC,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,qCAAqC;IACrC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,iCAAiC;IACjC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,2BAA2B;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,2BAA2B;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,GAC9B,IAAI,CAON"}

package/dist/otel/attributes.js

@@ -0,0 +1,56 @@
+/**
+ * OTel gen_ai.* semantic convention constants for Vauban agents.
+ *
+ * Spec: https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ *
+ * All standard gen_ai.* attributes follow the OTel semantic conventions.
+ * Custom Vauban attributes (gen_ai.agent.id, gen_ai.delegation.parent_run_id,
+ * gen_ai.cost.usd) are prefixed gen_ai.* to stay in the same namespace.
+ */
+// ─── Standard gen_ai.* attribute name constants ───────────────────────────────
+/** AI system identifier, e.g. "anthropic", "deepseek", "groq". */
+export const GEN_AI_SYSTEM = "gen_ai.system";
+/** Model name as requested, e.g. "claude-sonnet-4-6". */
+export const GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+/** Maximum token limit requested. */
+export const GEN_AI_REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens";
+/** Actual model used in the response (may differ from request). */
+export const GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+/** Number of input/prompt tokens consumed. */
+export const GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
+/** Number of output/completion tokens generated. */
+export const GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+/** Total tokens (input + output). */
+export const GEN_AI_USAGE_TOTAL_TOKENS = "gen_ai.usage.total_tokens";
+/** High-level operation: "chat" | "completion" | "embedding". */
+export const GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+// ─── Custom Vauban gen_ai.* extensions ────────────────────────────────────────
+/** Agent / runner identifier (Vauban extension). */
+export const GEN_AI_AGENT_ID = "gen_ai.agent.id";
+/**
+ * Parent run ID for delegation chain tracking (Sprint B).
+ * Must match `withDelegationAttribute` in trace-context.ts.
+ */
+export const GEN_AI_DELEGATION_PARENT_RUN_ID = "gen_ai.delegation.parent_run_id";
+/**
+ * Computed cost in USD (Vauban extension).
+ * Set by OutcomeTracker when available; stub value 0 until wired.
+ */
+export const GEN_AI_COST_USD = "gen_ai.cost.usd";
+// ─── Helper ───────────────────────────────────────────────────────────────────
+/**
+ * Sets all provided gen_ai.* attributes on a recording span.
+ * Undefined values are skipped (not set).
+ *
+ * @param span  - The OTel Span to annotate (must be recording).
+ * @param attrs - Partial bag of gen_ai.* attributes.
+ */
+export function setGenAiAttributes(span, attrs) {
+    const entries = Object.entries(attrs);
+    for (const [key, value] of entries) {
+        if (value !== undefined) {
+            span.setAttribute(key, value);
+        }
+    }
+}
+//# sourceMappingURL=attributes.js.map

package/dist/otel/attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.js","sourceRoot":"","sources":["../../src/otel/attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,iFAAiF;AAEjF,kEAAkE;AAClE,MAAM,CAAC,MAAM,aAAa,GAAG,eAAwB,CAAC;AAEtD,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAA+B,CAAC;AAEpE,qCAAqC;AACrC,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAAoC,CAAC;AAE9E,mEAAmE;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAgC,CAAC;AAEtE,8CAA8C;AAC9C,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAAoC,CAAC;AAE9E,oDAAoD;AACpD,MAAM,CAAC,MAAM,0BAA0B,GACrC,4BAAqC,CAAC;AAExC,qCAAqC;AACrC,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAAoC,CAAC;AAE9E,iEAAiE;AACjE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAgC,CAAC;AAEtE,iFAAiF;AAEjF,oDAAoD;AACpD,MAAM,CAAC,MAAM,eAAe,GAAG,iBAA0B,CAAC;AAE1D;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAC1C,iCAA0C,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,iBAA0B,CAAC;AA6B1D,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAU,EACV,KAA+B;IAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAA4C,CAAC;IACjF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/otel/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./ingest.js";
+export * from "./trace-context.js";
+export * from "./attributes.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/otel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/otel/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/otel/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./ingest.js";
+export * from "./trace-context.js";
+export * from "./attributes.js";
+//# sourceMappingURL=index.js.map

package/dist/otel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/otel/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/otel/ingest.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+export type { OtlpSpan, OtlpAttribute, OtlpAttributeValue } from "./types.js";
+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 declare function createOtelClient(opts: OtelClientOptions): OtelClient;
+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;
+}
+/**
+ * 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 declare function initVaubanSDK(opts: VaubanSDKOptions): BasicTracerProvider;
+export declare function getSDKProvider(): BasicTracerProvider | null;
+/**
+ * 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 declare function reportRunStart(opts: {
+    agentId: string;
+    runId?: string;
+    model?: string;
+    provider?: string;
+}): Promise<{
+    id: string;
+} | null>;
+/**
+ * Report a run finish to the CC registry.
+ */
+export declare function reportRunFinish(opts: {
+    runId: string;
+    status: "success" | "failed" | "completed";
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    errorMessage?: string;
+}): Promise<void>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/otel/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/otel/ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,mBAAmB,EAGpB,MAAM,+BAA+B,CAAC;AAMvC,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAI9E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,CACT,KAAK,EAAE;QAAE,aAAa,EAAE,OAAO,EAAE,CAAA;KAAE,EACnC,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAkCpE;AAID,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,CAoFzE;AAED,wBAAgB,cAAc,IAAI,mBAAmB,GAAG,IAAI,CAE3D;AAOD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAuBjC;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBhB"}

package/dist/otel/ingest.js

@@ -0,0 +1,192 @@
+/**
+ * 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 function createOtelClient(opts) {
+    const base = opts.baseUrl.replace(/\/$/, "");
+    return {
+        async ingestSpans(spans, ingestOpts) {
+            const token = await opts.getToken();
+            const headers = {
+                "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());
+                    message = body.error ?? body.message ?? message;
+                }
+                catch {
+                    /* ignore */
+                }
+                throw new Error(`OtelClient.ingestSpans: ${message}`);
+            }
+            return response.json();
+        },
+    };
+}
+let _sdkProvider = 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) {
+    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.message}`);
+        });
+    }
+    return provider;
+}
+export function getSDKProvider() {
+    return _sdkProvider;
+}
+// ── Run reporting ────────────────────────────────────────────────────────
+let _registryBaseUrl;
+let _apiKey;
+/**
+ * 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) {
+    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());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Report a run finish to the CC registry.
+ */
+export async function reportRunFinish(opts) {
+    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
+    }
+}
+//# sourceMappingURL=ingest.js.map

package/dist/otel/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../src/otel/ingest.ts"],"names":[],"mappings":"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"}

package/dist/otel/trace-context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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, type Span, type SpanContext } from "@opentelemetry/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 declare function registerW3CPropagator(): void;
+/**
+ * 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 declare function injectTraceContext(headers: Record<string, string>, ctx?: ReturnType<typeof context.active>): Record<string, string>;
+/**
+ * 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 declare function extractTraceContext(headers: Record<string, string>): SpanContext | null;
+/**
+ * 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 declare function withDelegationAttribute(span: Span, parentRunId: string): void;
+//# sourceMappingURL=trace-context.d.ts.map

package/dist/otel/trace-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.d.ts","sourceRoot":"","sources":["../../src/otel/trace-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,OAAO,EAKP,KAAK,IAAI,EACT,KAAK,WAAW,EAKjB,MAAM,oBAAoB,CAAC;AAiF5B;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAoB5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,GAAG,CAAC,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,MAAM,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,WAAW,GAAG,IAAI,CASpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,GAClB,IAAI,CAEN"}

package/dist/otel/trace-context.js

@@ -0,0 +1,137 @@
+/**
+ * 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, defaultTextMapGetter, defaultTextMapSetter, } 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, carrier, setter) {
+        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, carrier, getter) {
+        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 = {
+            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() {
+    propagation.setGlobalPropagator({
+        inject(ctx, carrier, setter) {
+            _propagator.inject(ctx, carrier, setter);
+        },
+        extract(ctx, carrier, getter) {
+            return _propagator.extract(ctx, carrier, getter);
+        },
+        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, ctx) {
+    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) {
+    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, parentRunId) {
+    span.setAttribute("gen_ai.delegation.parent_run_id", parentRunId);
+}
+// ─── Internal helpers ────────────────────────────────────────────────────────
+function isValidSpanCtx(spanCtx) {
+    return (spanCtx.traceId.length === 32 &&
+        spanCtx.spanId.length === 16 &&
+        spanCtx.traceId !== "0".repeat(32) &&
+        spanCtx.spanId !== "0".repeat(16));
+}
+//# sourceMappingURL=trace-context.js.map