apex-code 0.0.1-alpha.0 → 0.0.1-alpha.2

package/dist/core/observability/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../../src/core/observability/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAWD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,SAAS,EAAE,uBAAuB,EAClC,KAAK,GAAE,mBAAwB,GAC7B,iBAAiB,EAAE,CAkBrB","sourcesContent":["import type { UsagePerformanceSample } from \"../usage-performance-store.ts\";\n\nexport type UsageAggregateDimension = \"model\" | \"session\" | \"role\";\n\nexport interface UsageAggregateRow {\n\tkey: string;\n\tcost: number;\n\tsampleCount: number;\n\tttftMsTotal: number;\n\tgenerationMsTotal: number;\n}\n\nexport interface UsageAggregateRange {\n\tsinceMs?: number;\n\tuntilMs?: number;\n}\n\nconst UNKNOWN_SESSION_KEY = \"(unknown session)\";\nconst NO_ROLE_KEY = \"(no role)\";\n\nfunction keyFor(sample: UsagePerformanceSample, dimension: UsageAggregateDimension): string {\n\tif (dimension === \"model\") return `${sample.provider}/${sample.model}`;\n\tif (dimension === \"session\") return sample.sessionId ?? UNKNOWN_SESSION_KEY;\n\treturn sample.role ?? NO_ROLE_KEY;\n}\n\n/**\n * Groups durable usage/cost samples by model, session, or role over an optional\n * time range. The one query surface both `apex-code cost` (roadmap Phase 8) and\n * the ledger-vs-`getUsageCostBreakdown` reconciliation gate read, so the two never\n * compute cost through independently-drifting logic.\n */\nexport function aggregateUsagePerformance(\n\tsamples: readonly UsagePerformanceSample[],\n\tdimension: UsageAggregateDimension,\n\trange: UsageAggregateRange = {},\n): UsageAggregateRow[] {\n\tconst rows = new Map<string, UsageAggregateRow>();\n\tfor (const sample of samples) {\n\t\tif (range.sinceMs !== undefined && sample.timestamp < range.sinceMs) continue;\n\t\tif (range.untilMs !== undefined && sample.timestamp > range.untilMs) continue;\n\n\t\tconst key = keyFor(sample, dimension);\n\t\tlet row = rows.get(key);\n\t\tif (!row) {\n\t\t\trow = { key, cost: 0, sampleCount: 0, ttftMsTotal: 0, generationMsTotal: 0 };\n\t\t\trows.set(key, row);\n\t\t}\n\t\trow.cost += sample.cost ?? 0;\n\t\trow.sampleCount += 1;\n\t\trow.ttftMsTotal += sample.ttftMs;\n\t\trow.generationMsTotal += sample.generationMs;\n\t}\n\treturn Array.from(rows.values()).sort((a, b) => a.key.localeCompare(b.key));\n}\n"]}

package/dist/core/observability/aggregate.js

@@ -0,0 +1,36 @@
+const UNKNOWN_SESSION_KEY = "(unknown session)";
+const NO_ROLE_KEY = "(no role)";
+function keyFor(sample, dimension) {
+    if (dimension === "model")
+        return `${sample.provider}/${sample.model}`;
+    if (dimension === "session")
+        return sample.sessionId ?? UNKNOWN_SESSION_KEY;
+    return sample.role ?? NO_ROLE_KEY;
+}
+/**
+ * Groups durable usage/cost samples by model, session, or role over an optional
+ * time range. The one query surface both `apex-code cost` (roadmap Phase 8) and
+ * the ledger-vs-`getUsageCostBreakdown` reconciliation gate read, so the two never
+ * compute cost through independently-drifting logic.
+ */
+export function aggregateUsagePerformance(samples, dimension, range = {}) {
+    const rows = new Map();
+    for (const sample of samples) {
+        if (range.sinceMs !== undefined && sample.timestamp < range.sinceMs)
+            continue;
+        if (range.untilMs !== undefined && sample.timestamp > range.untilMs)
+            continue;
+        const key = keyFor(sample, dimension);
+        let row = rows.get(key);
+        if (!row) {
+            row = { key, cost: 0, sampleCount: 0, ttftMsTotal: 0, generationMsTotal: 0 };
+            rows.set(key, row);
+        }
+        row.cost += sample.cost ?? 0;
+        row.sampleCount += 1;
+        row.ttftMsTotal += sample.ttftMs;
+        row.generationMsTotal += sample.generationMs;
+    }
+    return Array.from(rows.values()).sort((a, b) => a.key.localeCompare(b.key));
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/core/observability/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.js","sourceRoot":"","sources":["../../../src/core/observability/aggregate.ts"],"names":[],"mappings":"AAiBA,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAChD,MAAM,WAAW,GAAG,WAAW,CAAC;AAEhC,SAAS,MAAM,CAAC,MAA8B,EAAE,SAAkC,EAAU;IAC3F,IAAI,SAAS,KAAK,OAAO;QAAE,OAAO,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;IACvE,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,SAAS,IAAI,mBAAmB,CAAC;IAC5E,OAAO,MAAM,CAAC,IAAI,IAAI,WAAW,CAAC;AAAA,CAClC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACxC,OAA0C,EAC1C,SAAkC,EAClC,KAAK,GAAwB,EAAE,EACT;IACtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAA6B,CAAC;IAClD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,OAAO;YAAE,SAAS;QAC9E,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,OAAO;YAAE,SAAS;QAE9E,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACtC,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,EAAE,CAAC;YACV,GAAG,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;YAC7E,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACpB,CAAC;QACD,GAAG,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;QAC7B,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC;QACrB,GAAG,CAAC,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC;QACjC,GAAG,CAAC,iBAAiB,IAAI,MAAM,CAAC,YAAY,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAAA,CAC5E","sourcesContent":["import type { UsagePerformanceSample } from \"../usage-performance-store.ts\";\n\nexport type UsageAggregateDimension = \"model\" | \"session\" | \"role\";\n\nexport interface UsageAggregateRow {\n\tkey: string;\n\tcost: number;\n\tsampleCount: number;\n\tttftMsTotal: number;\n\tgenerationMsTotal: number;\n}\n\nexport interface UsageAggregateRange {\n\tsinceMs?: number;\n\tuntilMs?: number;\n}\n\nconst UNKNOWN_SESSION_KEY = \"(unknown session)\";\nconst NO_ROLE_KEY = \"(no role)\";\n\nfunction keyFor(sample: UsagePerformanceSample, dimension: UsageAggregateDimension): string {\n\tif (dimension === \"model\") return `${sample.provider}/${sample.model}`;\n\tif (dimension === \"session\") return sample.sessionId ?? UNKNOWN_SESSION_KEY;\n\treturn sample.role ?? NO_ROLE_KEY;\n}\n\n/**\n * Groups durable usage/cost samples by model, session, or role over an optional\n * time range. The one query surface both `apex-code cost` (roadmap Phase 8) and\n * the ledger-vs-`getUsageCostBreakdown` reconciliation gate read, so the two never\n * compute cost through independently-drifting logic.\n */\nexport function aggregateUsagePerformance(\n\tsamples: readonly UsagePerformanceSample[],\n\tdimension: UsageAggregateDimension,\n\trange: UsageAggregateRange = {},\n): UsageAggregateRow[] {\n\tconst rows = new Map<string, UsageAggregateRow>();\n\tfor (const sample of samples) {\n\t\tif (range.sinceMs !== undefined && sample.timestamp < range.sinceMs) continue;\n\t\tif (range.untilMs !== undefined && sample.timestamp > range.untilMs) continue;\n\n\t\tconst key = keyFor(sample, dimension);\n\t\tlet row = rows.get(key);\n\t\tif (!row) {\n\t\t\trow = { key, cost: 0, sampleCount: 0, ttftMsTotal: 0, generationMsTotal: 0 };\n\t\t\trows.set(key, row);\n\t\t}\n\t\trow.cost += sample.cost ?? 0;\n\t\trow.sampleCount += 1;\n\t\trow.ttftMsTotal += sample.ttftMs;\n\t\trow.generationMsTotal += sample.generationMs;\n\t}\n\treturn Array.from(rows.values()).sort((a, b) => a.key.localeCompare(b.key));\n}\n"]}

package/dist/core/observability/otlp.d.ts

@@ -0,0 +1,66 @@
+import type { UsagePerformanceSample } from "../usage-performance-store.ts";
+/**
+ * User-directed OTLP trace export (roadmap Phase 8, ADR 0012). Uses global
+ * `fetch` deliberately, not a direct undici import: `http-dispatcher.ts` already
+ * binds it to a proxy-aware, timeout-configured dispatcher, and a second HTTP
+ * client here would silently bypass a user's HTTP_PROXY.
+ *
+ * Scope note (recorded in the Phase 8 plan): this emits one span per model
+ * request attempt -- the same unit `SqliteUsagePerformanceStore` already
+ * records -- not a full turn/tool-call span tree. That would require touching
+ * `agent-session.ts`'s tool-call lifecycle, a separate, larger integration this
+ * phase does not open.
+ */
+export interface OtlpExportConfig {
+    endpoint: string;
+    headers?: Record<string, string>;
+}
+interface OtlpAttribute {
+    key: string;
+    value: {
+        stringValue: string;
+    } | {
+        doubleValue: number;
+    };
+}
+export interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpAttribute[];
+}
+export interface OtlpTracePayload {
+    resourceSpans: Array<{
+        resource: {
+            attributes: OtlpAttribute[];
+        };
+        scopeSpans: Array<{
+            scope: {
+                name: string;
+            };
+            spans: OtlpSpan[];
+        }>;
+    }>;
+}
+/**
+ * The complete allowlist ADR 0012 permits. `buildUsageSampleSpan` only ever
+ * emits a subset of this -- extending `UsagePerformanceSample` must not
+ * silently widen what is exported; this list is edited explicitly or not at
+ * all.
+ */
+export declare const OTLP_ALLOWED_ATTRIBUTE_KEYS: readonly ["provider", "model", "role", "outcome", "failure_kind", "ttft_ms", "generation_ms", "input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens", "cost", "credential_identity", "tool_name"];
+/** Builds one span for one model request attempt. Attributes are an allowlist, never a redaction pass. */
+export declare function buildUsageSampleSpan(sample: UsagePerformanceSample): OtlpSpan;
+export declare function buildOtlpTracePayload(spans: readonly OtlpSpan[]): OtlpTracePayload;
+/**
+ * Exports one span for one usage sample. Never throws -- an export failure
+ * must never fail the turn that produced the sample, matching
+ * `instrumentAttempt`'s own fire-and-forget `.catch(() => {})` around the
+ * ledger write.
+ */
+export declare function exportUsageSampleSpan(sample: UsagePerformanceSample, config: OtlpExportConfig): Promise<void>;
+export {};
+//# sourceMappingURL=otlp.d.ts.map

package/dist/core/observability/otlp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp.d.ts","sourceRoot":"","sources":["../../../src/core/observability/otlp.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,UAAU,aAAa;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD;AAED,MAAM,WAAW,QAAQ;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAChC,aAAa,EAAE,KAAK,CAAC;QACpB,QAAQ,EAAE;YAAE,UAAU,EAAE,aAAa,EAAE,CAAA;SAAE,CAAC;QAC1C,UAAU,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAA;aAAE,CAAC;YAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;SAAE,CAAC,CAAC;KAClE,CAAC,CAAC;CACH;AAMD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,uNAe9B,CAAC;AAWX,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,QAAQ,CA8B7E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,gBAAgB,CASlF;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYnH","sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport type { UsagePerformanceSample } from \"../usage-performance-store.ts\";\n\n/**\n * User-directed OTLP trace export (roadmap Phase 8, ADR 0012). Uses global\n * `fetch` deliberately, not a direct undici import: `http-dispatcher.ts` already\n * binds it to a proxy-aware, timeout-configured dispatcher, and a second HTTP\n * client here would silently bypass a user's HTTP_PROXY.\n *\n * Scope note (recorded in the Phase 8 plan): this emits one span per model\n * request attempt -- the same unit `SqliteUsagePerformanceStore` already\n * records -- not a full turn/tool-call span tree. That would require touching\n * `agent-session.ts`'s tool-call lifecycle, a separate, larger integration this\n * phase does not open.\n */\n\nexport interface OtlpExportConfig {\n\tendpoint: string;\n\theaders?: Record<string, string>;\n}\n\ninterface OtlpAttribute {\n\tkey: string;\n\tvalue: { stringValue: string } | { doubleValue: number };\n}\n\nexport interface OtlpSpan {\n\ttraceId: string;\n\tspanId: string;\n\tname: string;\n\tkind: number;\n\tstartTimeUnixNano: string;\n\tendTimeUnixNano: string;\n\tattributes: OtlpAttribute[];\n}\n\nexport interface OtlpTracePayload {\n\tresourceSpans: Array<{\n\t\tresource: { attributes: OtlpAttribute[] };\n\t\tscopeSpans: Array<{ scope: { name: string }; spans: OtlpSpan[] }>;\n\t}>;\n}\n\nconst SERVICE_NAME = \"apex-code\";\n/** OTLP SpanKind: SPAN_KIND_CLIENT -- this process is the caller of the model API. */\nconst SPAN_KIND_CLIENT = 3;\n\n/**\n * The complete allowlist ADR 0012 permits. `buildUsageSampleSpan` only ever\n * emits a subset of this -- extending `UsagePerformanceSample` must not\n * silently widen what is exported; this list is edited explicitly or not at\n * all.\n */\nexport const OTLP_ALLOWED_ATTRIBUTE_KEYS = [\n\t\"provider\",\n\t\"model\",\n\t\"role\",\n\t\"outcome\",\n\t\"failure_kind\",\n\t\"ttft_ms\",\n\t\"generation_ms\",\n\t\"input_tokens\",\n\t\"output_tokens\",\n\t\"cache_read_tokens\",\n\t\"cache_write_tokens\",\n\t\"cost\",\n\t\"credential_identity\",\n\t\"tool_name\",\n] as const;\n\nfunction attr(key: string, value: string | number | undefined): OtlpAttribute | undefined {\n\tif (value === undefined) return undefined;\n\treturn typeof value === \"number\" ? { key, value: { doubleValue: value } } : { key, value: { stringValue: value } };\n}\n\nfunction randomHex(bytes: number): string {\n\treturn randomBytes(bytes).toString(\"hex\");\n}\n\n/** Builds one span for one model request attempt. Attributes are an allowlist, never a redaction pass. */\nexport function buildUsageSampleSpan(sample: UsagePerformanceSample): OtlpSpan {\n\tconst attributes = [\n\t\tattr(\"provider\", sample.provider),\n\t\tattr(\"model\", sample.model),\n\t\tattr(\"role\", sample.role),\n\t\tattr(\"outcome\", sample.outcome),\n\t\tattr(\"failure_kind\", sample.failureKind),\n\t\tattr(\"ttft_ms\", sample.ttftMs),\n\t\tattr(\"generation_ms\", sample.generationMs),\n\t\tattr(\"input_tokens\", sample.usage?.input),\n\t\tattr(\"output_tokens\", sample.usage?.output),\n\t\tattr(\"cache_read_tokens\", sample.usage?.cacheRead),\n\t\tattr(\"cache_write_tokens\", sample.usage?.cacheWrite),\n\t\tattr(\"cost\", sample.cost),\n\t\tattr(\"credential_identity\", sample.credentialIdentity),\n\t].filter((candidate): candidate is OtlpAttribute => candidate !== undefined);\n\n\tconst startNanos = BigInt(sample.timestamp) * 1_000_000n;\n\tconst durationMs = Math.max(0, Math.round(sample.ttftMs + sample.generationMs));\n\tconst endNanos = startNanos + BigInt(durationMs) * 1_000_000n;\n\n\treturn {\n\t\ttraceId: randomHex(16),\n\t\tspanId: randomHex(8),\n\t\tname: \"model_request_attempt\",\n\t\tkind: SPAN_KIND_CLIENT,\n\t\tstartTimeUnixNano: startNanos.toString(),\n\t\tendTimeUnixNano: endNanos.toString(),\n\t\tattributes,\n\t};\n}\n\nexport function buildOtlpTracePayload(spans: readonly OtlpSpan[]): OtlpTracePayload {\n\treturn {\n\t\tresourceSpans: [\n\t\t\t{\n\t\t\t\tresource: { attributes: [attr(\"service.name\", SERVICE_NAME)!] },\n\t\t\t\tscopeSpans: [{ scope: { name: SERVICE_NAME }, spans: [...spans] }],\n\t\t\t},\n\t\t],\n\t};\n}\n\n/**\n * Exports one span for one usage sample. Never throws -- an export failure\n * must never fail the turn that produced the sample, matching\n * `instrumentAttempt`'s own fire-and-forget `.catch(() => {})` around the\n * ledger write.\n */\nexport async function exportUsageSampleSpan(sample: UsagePerformanceSample, config: OtlpExportConfig): Promise<void> {\n\ttry {\n\t\tconst payload = buildOtlpTracePayload([buildUsageSampleSpan(sample)]);\n\t\tconst url = `${config.endpoint.replace(/\\/$/, \"\")}/v1/traces`;\n\t\tawait fetch(url, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: { \"content-type\": \"application/json\", ...config.headers },\n\t\t\tbody: JSON.stringify(payload),\n\t\t});\n\t} catch {\n\t\t// Never let an export failure surface to the caller.\n\t}\n}\n"]}

package/dist/core/observability/otlp.js

@@ -0,0 +1,95 @@
+import { randomBytes } from "node:crypto";
+const SERVICE_NAME = "apex-code";
+/** OTLP SpanKind: SPAN_KIND_CLIENT -- this process is the caller of the model API. */
+const SPAN_KIND_CLIENT = 3;
+/**
+ * The complete allowlist ADR 0012 permits. `buildUsageSampleSpan` only ever
+ * emits a subset of this -- extending `UsagePerformanceSample` must not
+ * silently widen what is exported; this list is edited explicitly or not at
+ * all.
+ */
+export const OTLP_ALLOWED_ATTRIBUTE_KEYS = [
+    "provider",
+    "model",
+    "role",
+    "outcome",
+    "failure_kind",
+    "ttft_ms",
+    "generation_ms",
+    "input_tokens",
+    "output_tokens",
+    "cache_read_tokens",
+    "cache_write_tokens",
+    "cost",
+    "credential_identity",
+    "tool_name",
+];
+function attr(key, value) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "number" ? { key, value: { doubleValue: value } } : { key, value: { stringValue: value } };
+}
+function randomHex(bytes) {
+    return randomBytes(bytes).toString("hex");
+}
+/** Builds one span for one model request attempt. Attributes are an allowlist, never a redaction pass. */
+export function buildUsageSampleSpan(sample) {
+    const attributes = [
+        attr("provider", sample.provider),
+        attr("model", sample.model),
+        attr("role", sample.role),
+        attr("outcome", sample.outcome),
+        attr("failure_kind", sample.failureKind),
+        attr("ttft_ms", sample.ttftMs),
+        attr("generation_ms", sample.generationMs),
+        attr("input_tokens", sample.usage?.input),
+        attr("output_tokens", sample.usage?.output),
+        attr("cache_read_tokens", sample.usage?.cacheRead),
+        attr("cache_write_tokens", sample.usage?.cacheWrite),
+        attr("cost", sample.cost),
+        attr("credential_identity", sample.credentialIdentity),
+    ].filter((candidate) => candidate !== undefined);
+    const startNanos = BigInt(sample.timestamp) * 1000000n;
+    const durationMs = Math.max(0, Math.round(sample.ttftMs + sample.generationMs));
+    const endNanos = startNanos + BigInt(durationMs) * 1000000n;
+    return {
+        traceId: randomHex(16),
+        spanId: randomHex(8),
+        name: "model_request_attempt",
+        kind: SPAN_KIND_CLIENT,
+        startTimeUnixNano: startNanos.toString(),
+        endTimeUnixNano: endNanos.toString(),
+        attributes,
+    };
+}
+export function buildOtlpTracePayload(spans) {
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: [attr("service.name", SERVICE_NAME)] },
+                scopeSpans: [{ scope: { name: SERVICE_NAME }, spans: [...spans] }],
+            },
+        ],
+    };
+}
+/**
+ * Exports one span for one usage sample. Never throws -- an export failure
+ * must never fail the turn that produced the sample, matching
+ * `instrumentAttempt`'s own fire-and-forget `.catch(() => {})` around the
+ * ledger write.
+ */
+export async function exportUsageSampleSpan(sample, config) {
+    try {
+        const payload = buildOtlpTracePayload([buildUsageSampleSpan(sample)]);
+        const url = `${config.endpoint.replace(/\/$/, "")}/v1/traces`;
+        await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...config.headers },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch {
+        // Never let an export failure surface to the caller.
+    }
+}
+//# sourceMappingURL=otlp.js.map

package/dist/core/observability/otlp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp.js","sourceRoot":"","sources":["../../../src/core/observability/otlp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA2C1C,MAAM,YAAY,GAAG,WAAW,CAAC;AACjC,sFAAsF;AACtF,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IAC1C,UAAU;IACV,OAAO;IACP,MAAM;IACN,SAAS;IACT,cAAc;IACd,SAAS;IACT,eAAe;IACf,cAAc;IACd,eAAe;IACf,mBAAmB;IACnB,oBAAoB;IACpB,MAAM;IACN,qBAAqB;IACrB,WAAW;CACF,CAAC;AAEX,SAAS,IAAI,CAAC,GAAW,EAAE,KAAkC,EAA6B;IACzF,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC;AAAA,CACnH;AAED,SAAS,SAAS,CAAC,KAAa,EAAU;IACzC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAAA,CAC1C;AAED,0GAA0G;AAC1G,MAAM,UAAU,oBAAoB,CAAC,MAA8B,EAAY;IAC9E,MAAM,UAAU,GAAG;QAClB,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC;QACxC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,YAAY,CAAC;QAC1C,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC;QACzC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;QAC3C,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC;QAClD,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC;QACpD,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,kBAAkB,CAAC;KACtD,CAAC,MAAM,CAAC,CAAC,SAAS,EAA8B,EAAE,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IAE7E,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,QAAU,CAAC;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,QAAU,CAAC;IAE9D,OAAO;QACN,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;QACtB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;QACpB,IAAI,EAAE,uBAAuB;QAC7B,IAAI,EAAE,gBAAgB;QACtB,iBAAiB,EAAE,UAAU,CAAC,QAAQ,EAAE;QACxC,eAAe,EAAE,QAAQ,CAAC,QAAQ,EAAE;QACpC,UAAU;KACV,CAAC;AAAA,CACF;AAED,MAAM,UAAU,qBAAqB,CAAC,KAA0B,EAAoB;IACnF,OAAO;QACN,aAAa,EAAE;YACd;gBACC,QAAQ,EAAE,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,YAAY,CAAE,CAAC,EAAE;gBAC/D,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;aAClE;SACD;KACD,CAAC;AAAA,CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAA8B,EAAE,MAAwB,EAAiB;IACpH,IAAI,CAAC;QACJ,MAAM,OAAO,GAAG,qBAAqB,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACtE,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC;QAC9D,MAAM,KAAK,CAAC,GAAG,EAAE;YAChB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE;YAClE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SAC7B,CAAC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACR,qDAAqD;IACtD,CAAC;AAAA,CACD","sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport type { UsagePerformanceSample } from \"../usage-performance-store.ts\";\n\n/**\n * User-directed OTLP trace export (roadmap Phase 8, ADR 0012). Uses global\n * `fetch` deliberately, not a direct undici import: `http-dispatcher.ts` already\n * binds it to a proxy-aware, timeout-configured dispatcher, and a second HTTP\n * client here would silently bypass a user's HTTP_PROXY.\n *\n * Scope note (recorded in the Phase 8 plan): this emits one span per model\n * request attempt -- the same unit `SqliteUsagePerformanceStore` already\n * records -- not a full turn/tool-call span tree. That would require touching\n * `agent-session.ts`'s tool-call lifecycle, a separate, larger integration this\n * phase does not open.\n */\n\nexport interface OtlpExportConfig {\n\tendpoint: string;\n\theaders?: Record<string, string>;\n}\n\ninterface OtlpAttribute {\n\tkey: string;\n\tvalue: { stringValue: string } | { doubleValue: number };\n}\n\nexport interface OtlpSpan {\n\ttraceId: string;\n\tspanId: string;\n\tname: string;\n\tkind: number;\n\tstartTimeUnixNano: string;\n\tendTimeUnixNano: string;\n\tattributes: OtlpAttribute[];\n}\n\nexport interface OtlpTracePayload {\n\tresourceSpans: Array<{\n\t\tresource: { attributes: OtlpAttribute[] };\n\t\tscopeSpans: Array<{ scope: { name: string }; spans: OtlpSpan[] }>;\n\t}>;\n}\n\nconst SERVICE_NAME = \"apex-code\";\n/** OTLP SpanKind: SPAN_KIND_CLIENT -- this process is the caller of the model API. */\nconst SPAN_KIND_CLIENT = 3;\n\n/**\n * The complete allowlist ADR 0012 permits. `buildUsageSampleSpan` only ever\n * emits a subset of this -- extending `UsagePerformanceSample` must not\n * silently widen what is exported; this list is edited explicitly or not at\n * all.\n */\nexport const OTLP_ALLOWED_ATTRIBUTE_KEYS = [\n\t\"provider\",\n\t\"model\",\n\t\"role\",\n\t\"outcome\",\n\t\"failure_kind\",\n\t\"ttft_ms\",\n\t\"generation_ms\",\n\t\"input_tokens\",\n\t\"output_tokens\",\n\t\"cache_read_tokens\",\n\t\"cache_write_tokens\",\n\t\"cost\",\n\t\"credential_identity\",\n\t\"tool_name\",\n] as const;\n\nfunction attr(key: string, value: string | number | undefined): OtlpAttribute | undefined {\n\tif (value === undefined) return undefined;\n\treturn typeof value === \"number\" ? { key, value: { doubleValue: value } } : { key, value: { stringValue: value } };\n}\n\nfunction randomHex(bytes: number): string {\n\treturn randomBytes(bytes).toString(\"hex\");\n}\n\n/** Builds one span for one model request attempt. Attributes are an allowlist, never a redaction pass. */\nexport function buildUsageSampleSpan(sample: UsagePerformanceSample): OtlpSpan {\n\tconst attributes = [\n\t\tattr(\"provider\", sample.provider),\n\t\tattr(\"model\", sample.model),\n\t\tattr(\"role\", sample.role),\n\t\tattr(\"outcome\", sample.outcome),\n\t\tattr(\"failure_kind\", sample.failureKind),\n\t\tattr(\"ttft_ms\", sample.ttftMs),\n\t\tattr(\"generation_ms\", sample.generationMs),\n\t\tattr(\"input_tokens\", sample.usage?.input),\n\t\tattr(\"output_tokens\", sample.usage?.output),\n\t\tattr(\"cache_read_tokens\", sample.usage?.cacheRead),\n\t\tattr(\"cache_write_tokens\", sample.usage?.cacheWrite),\n\t\tattr(\"cost\", sample.cost),\n\t\tattr(\"credential_identity\", sample.credentialIdentity),\n\t].filter((candidate): candidate is OtlpAttribute => candidate !== undefined);\n\n\tconst startNanos = BigInt(sample.timestamp) * 1_000_000n;\n\tconst durationMs = Math.max(0, Math.round(sample.ttftMs + sample.generationMs));\n\tconst endNanos = startNanos + BigInt(durationMs) * 1_000_000n;\n\n\treturn {\n\t\ttraceId: randomHex(16),\n\t\tspanId: randomHex(8),\n\t\tname: \"model_request_attempt\",\n\t\tkind: SPAN_KIND_CLIENT,\n\t\tstartTimeUnixNano: startNanos.toString(),\n\t\tendTimeUnixNano: endNanos.toString(),\n\t\tattributes,\n\t};\n}\n\nexport function buildOtlpTracePayload(spans: readonly OtlpSpan[]): OtlpTracePayload {\n\treturn {\n\t\tresourceSpans: [\n\t\t\t{\n\t\t\t\tresource: { attributes: [attr(\"service.name\", SERVICE_NAME)!] },\n\t\t\t\tscopeSpans: [{ scope: { name: SERVICE_NAME }, spans: [...spans] }],\n\t\t\t},\n\t\t],\n\t};\n}\n\n/**\n * Exports one span for one usage sample. Never throws -- an export failure\n * must never fail the turn that produced the sample, matching\n * `instrumentAttempt`'s own fire-and-forget `.catch(() => {})` around the\n * ledger write.\n */\nexport async function exportUsageSampleSpan(sample: UsagePerformanceSample, config: OtlpExportConfig): Promise<void> {\n\ttry {\n\t\tconst payload = buildOtlpTracePayload([buildUsageSampleSpan(sample)]);\n\t\tconst url = `${config.endpoint.replace(/\\/$/, \"\")}/v1/traces`;\n\t\tawait fetch(url, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: { \"content-type\": \"application/json\", ...config.headers },\n\t\t\tbody: JSON.stringify(payload),\n\t\t});\n\t} catch {\n\t\t// Never let an export failure surface to the caller.\n\t}\n}\n"]}