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

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":"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","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"]}