@xopcai/xopc 0.0.362 → 0.0.363

package/dist/src/observability/langfuse.js

@@ -0,0 +1,180 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+//#region src/observability/langfuse.ts
+init_logger();
+const log = createLogger("Observability:Langfuse");
+function otlp(record) {
+	const attributes = Object.entries(record.attributes).map(([key, value]) => ({
+		key,
+		value: typeof value === "number" ? { doubleValue: value } : typeof value === "boolean" ? { boolValue: value } : { stringValue: value }
+	}));
+	return {
+		traceId: record.traceId,
+		spanId: record.spanId,
+		parentSpanId: record.parentSpanId,
+		name: record.name,
+		kind: 1,
+		startTimeUnixNano: String(BigInt(Math.floor(record.startedAt * 1e3)) * 1000n),
+		endTimeUnixNano: String(BigInt(Math.floor((record.endedAt ?? record.startedAt) * 1e3)) * 1000n),
+		attributes,
+		status: { code: record.status === "error" ? 2 : 1 }
+	};
+}
+/** Bounded OTLP/HTTP JSON exporter. No hidden SDK queue or durable replay. */
+var LangfuseTarget = class {
+	queue = [];
+	bytes = 0;
+	timer;
+	sending;
+	controller;
+	closed = false;
+	lastWarning = 0;
+	dropped = 0;
+	lastSuccess;
+	lastFailure;
+	lastError;
+	constructor(baseUrl, publicKey, secretKey) {
+		this.baseUrl = baseUrl;
+		this.publicKey = publicKey;
+		this.secretKey = secretKey;
+	}
+	status() {
+		return {
+			state: this.lastError ? "degraded" : "ready",
+			pending: this.queue.length,
+			dropped: this.dropped,
+			lastSuccess: this.lastSuccess,
+			lastFailure: this.lastFailure,
+			lastError: this.lastError
+		};
+	}
+	enqueue(record) {
+		if (this.closed) return;
+		const bytes = Buffer.byteLength(JSON.stringify(record));
+		if (this.queue.length >= 2e3 || this.bytes + bytes > 8 * 1048576) {
+			this.dropped++;
+			this.lastError = "Export queue full";
+			return;
+		}
+		this.queue.push({
+			record,
+			bytes
+		});
+		this.bytes += bytes;
+		if (this.queue.length >= 100) this.flush();
+		else if (!this.timer) {
+			this.timer = setTimeout(() => {
+				this.timer = void 0;
+				this.flush();
+			}, 5e3);
+			this.timer.unref();
+		}
+	}
+	async flush() {
+		if (this.sending) {
+			await this.sending;
+			if (this.queue.length && !this.closed) await this.flush();
+			return;
+		}
+		if (this.timer) {
+			clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+		if (this.closed || !this.queue.length) return;
+		const batch = this.queue.splice(0, 100);
+		this.bytes -= batch.reduce((n, row) => n + row.bytes, 0);
+		this.sending = this.send(batch.map((row) => row.record)).finally(() => {
+			this.sending = void 0;
+		});
+		await this.sending;
+		if (this.queue.length && !this.closed && !this.timer) {
+			this.timer = setTimeout(() => {
+				this.timer = void 0;
+				this.flush();
+			}, 5e3);
+			this.timer.unref();
+		}
+	}
+	async send(records) {
+		for (let attempt = 0; attempt < 3 && !this.closed; attempt++) {
+			this.controller = new AbortController();
+			const timeout = setTimeout(() => this.controller?.abort(), 5e3);
+			try {
+				const response = await fetch(this.baseUrl.replace(/\/$/, "") + "/api/public/otel/v1/traces", {
+					method: "POST",
+					redirect: "error",
+					signal: this.controller.signal,
+					headers: {
+						"Content-Type": "application/json",
+						Authorization: `Basic ${Buffer.from(`${this.publicKey}:${this.secretKey}`).toString("base64")}`,
+						"x-langfuse-ingestion-version": "4"
+					},
+					body: JSON.stringify({ resourceSpans: [{
+						resource: { attributes: [{
+							key: "service.name",
+							value: { stringValue: "xopc" }
+						}] },
+						scopeSpans: [{
+							scope: { name: "xopc.observability" },
+							spans: records.map(otlp)
+						}]
+					}] })
+				});
+				if (!response.ok) {
+					await response.body?.cancel();
+					throw new Error(`Langfuse returned HTTP ${response.status}`);
+				}
+				if (response.body) {
+					const reader = response.body.getReader();
+					const chunks = [];
+					let size = 0;
+					try {
+						while (true) {
+							const chunk = await reader.read();
+							if (chunk.done) break;
+							size += chunk.value.length;
+							if (size > 16384) {
+								await reader.cancel();
+								throw new Error("Oversized ingestion response");
+							}
+							chunks.push(chunk.value);
+						}
+						const text = Buffer.concat(chunks).toString("utf8");
+						if (text && Number(JSON.parse(text).partialSuccess?.rejectedSpans ?? 0) > 0) throw new Error("Ingestion rejected spans");
+					} finally {
+						reader.releaseLock();
+					}
+				}
+				this.lastSuccess = Date.now();
+				this.lastError = void 0;
+				return;
+			} catch (error) {
+				this.lastFailure = Date.now();
+				if (Date.now() - this.lastWarning > 6e4) {
+					this.lastWarning = Date.now();
+					log.warn({
+						phase: "langfuse_export",
+						attempt: attempt + 1
+					}, "Langfuse trace export failed; local recording continues");
+				}
+				this.lastError = error instanceof Error && /^Langfuse returned HTTP \d+$/.test(error.message) ? error.message : "Langfuse export failed";
+			} finally {
+				clearTimeout(timeout);
+			}
+			if (attempt < 2 && !this.closed) await new Promise((resolve) => {
+				setTimeout(resolve, 250 * 2 ** attempt).unref();
+			});
+		}
+		this.dropped += records.length;
+	}
+	close() {
+		this.closed = true;
+		this.controller?.abort();
+		if (this.timer) clearTimeout(this.timer);
+		this.dropped += this.queue.length;
+		this.queue = [];
+		this.bytes = 0;
+	}
+};
+//#endregion
+export { LangfuseTarget };

package/dist/src/observability/runtime.d.ts

@@ -0,0 +1,57 @@
+import { type Span, type Attributes } from '@opentelemetry/api';
+import { type TracingConfig } from './config.js';
+import { LocalTraceStore } from './store.js';
+import type { TraceRecord } from './types.js';
+export type TraceIdentity = {
+    conversationId?: string;
+    runId?: string;
+    agentId?: string;
+    transcriptId?: string;
+};
+export declare function localStore(): LocalTraceStore;
+export declare function tracingConfig(): TracingConfig;
+export declare function configureTracing(value?: unknown): Promise<void>;
+export declare function tracingStatus(): Promise<{
+    local: any;
+    langfuse: {
+        state: string;
+        pending: number;
+        dropped: number;
+        lastSuccess: number;
+        lastFailure: number;
+        lastError: string;
+    } | {
+        state: string;
+        pending: number;
+        dropped: number;
+    };
+    active: number;
+    dropped: number;
+}>;
+export declare function traceIds(): {
+    traceId?: string;
+    spanId?: string;
+};
+export type Observation = {
+    span?: Span;
+    run: <T>(fn: () => T) => T;
+    finish: (status?: string, output?: unknown) => void;
+    input: (value: unknown) => void;
+    update: (values: Attributes) => void;
+};
+export declare function startObservation(name: string, type: TraceRecord['type'], identity?: TraceIdentity): Observation;
+export declare function traceRun<T extends {
+    ok?: boolean;
+    stopReason?: string;
+    errorMessage?: string;
+    lastAssistantText?: string;
+}>(name: string, identity: TraceIdentity, fn: () => Promise<T>, input?: unknown): Promise<T>;
+export declare function traceTools<T extends {
+    name: string;
+    execute: (...args: any[]) => any;
+}>(tools: T[]): T[];
+export declare function flushTracing(): Promise<void>;
+export declare function testLangfuse(): Promise<boolean>;
+export declare function closeTracing(): Promise<void>;
+export declare function traceOperation<T>(name: string, fn: () => Promise<T>, attributes?: Attributes): Promise<T>;
+export declare function setTraceIdentity(identity: TraceIdentity): void;

package/dist/src/observability/runtime.js

@@ -0,0 +1,404 @@
+import { init_context, runWithLogContext } from "../utils/logger/context.js";
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { CredentialResolver, init_credentials } from "../auth/credentials.js";
+import { TracingConfigSchema, defaultTracingConfig, init_config } from "./config.js";
+import { LangfuseTarget } from "./langfuse.js";
+import { boundedJson, redactString } from "./sanitize.js";
+import { LocalTraceStore } from "./store.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { SpanStatusCode, context, createContextKey, trace } from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+//#region src/observability/runtime.ts
+init_credentials();
+init_logger();
+init_context();
+init_config();
+const log = createLogger("Observability");
+let lastStorageWarning = 0;
+function storageWarning(message) {
+	if (Date.now() - lastStorageWarning < 6e4) return;
+	lastStorageWarning = Date.now();
+	log.warn({
+		errorMessage: message,
+		phase: "local_trace_write"
+	}, `Local trace recording unavailable: ${message}`);
+}
+const localEpochKey = createContextKey("xopc.trace.localEpoch");
+const scopes = new AsyncLocalStorage();
+let config = defaultTracingConfig();
+let store;
+let target;
+let provider;
+let revision = 0;
+let active = 0;
+let dropped = 0;
+const pendingLocal = /* @__PURE__ */ new Set();
+let pendingLocalBytes = 0;
+let remoteState = "disabled";
+let knownSecrets = [];
+let configureVersion = 0;
+let targetSignature = "";
+const targets = /* @__PURE__ */ new WeakMap();
+const localEpochs = /* @__PURE__ */ new WeakMap();
+const captured = /* @__PURE__ */ new WeakMap();
+function secretSafe(value) {
+	let result = redactString(value);
+	for (const secret of knownSecrets) if (secret.length >= 4) result = result.split(secret).join("[REDACTED]");
+	return result;
+}
+function record(span, ended = true) {
+	const attrs = {};
+	for (const [key, value] of Object.entries(span.attributes)) if ([
+		"string",
+		"number",
+		"boolean"
+	].includes(typeof value)) attrs[key] = typeof value === "string" ? secretSafe(value) : value;
+	return {
+		traceId: span.spanContext().traceId,
+		spanId: span.spanContext().spanId,
+		parentSpanId: span.parentSpanContext?.spanId,
+		name: secretSafe(span.name),
+		type: String(attrs["langfuse.observation.type"] ?? "span"),
+		startedAt: Math.floor(span.startTime[0] * 1e3 + span.startTime[1] / 1e6),
+		...ended ? { endedAt: Math.floor(span.endTime[0] * 1e3 + span.endTime[1] / 1e6) } : {},
+		status: ended ? String(attrs["xopc.status"] ?? (span.status.code === SpanStatusCode.ERROR ? "error" : "success")) : "running",
+		attributes: attrs
+	};
+}
+var TraceProcessor = class {
+	onStart(span, parentContext) {
+		const scope = scopes.getStore();
+		if (!(scope?.config ?? config).enabled) return;
+		captured.set(span, true);
+		if (scope?.target ?? target) targets.set(span, scope?.target ?? target);
+		if (!span.parentSpanContext || span.attributes["xopc.localRoot"] === true) {
+			const epoch = localStore().begin(record(span, false)).catch(() => {
+				storageWarning("Trace root could not be persisted");
+				return -1;
+			});
+			localEpochs.set(span, epoch);
+			if (scope) scope.epoch = epoch;
+		} else {
+			const epoch = scope?.epoch ?? parentContext.getValue(localEpochKey);
+			if (epoch) localEpochs.set(span, epoch);
+		}
+	}
+	onEnd(span) {
+		if (!captured.has(span)) return;
+		try {
+			const value = record(span);
+			const bytes = Buffer.byteLength(JSON.stringify(value));
+			if (pendingLocal.size < 2e3 && pendingLocalBytes + bytes <= 8 * 1048576) {
+				const destination = localStore();
+				pendingLocalBytes += bytes;
+				const pending = (localEpochs.get(span) ?? Promise.resolve(void 0)).then(async (epoch) => {
+					await destination.write(value, epoch);
+					if (destination.lastError) storageWarning(destination.lastError);
+				}).catch(() => {
+					dropped++;
+				}).finally(() => {
+					pendingLocal.delete(pending);
+					pendingLocalBytes -= bytes;
+				});
+				pendingLocal.add(pending);
+			} else dropped++;
+			targets.get(span)?.enqueue(value);
+		} catch {
+			dropped++;
+		}
+	}
+	async forceFlush() {
+		await Promise.allSettled([...pendingLocal]);
+		await Promise.allSettled([store?.flush(), target?.flush()]);
+	}
+	async shutdown() {
+		await this.forceFlush();
+		target?.close();
+		await store?.close();
+	}
+};
+function tracer() {
+	if (!provider) {
+		context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
+		process.once("beforeExit", () => {
+			flushTracing();
+		});
+		provider = new BasicTracerProvider({
+			spanProcessors: [new TraceProcessor()],
+			spanLimits: {
+				attributeCountLimit: 64,
+				attributeValueLengthLimit: 65536,
+				eventCountLimit: 0
+			}
+		});
+	}
+	return provider.getTracer("xopc.observability");
+}
+function localStore() {
+	return store ??= new LocalTraceStore(config);
+}
+function tracingConfig() {
+	return structuredClone(config);
+}
+async function configureTracing(value) {
+	const version = ++configureVersion;
+	const next = TracingConfigSchema.parse(value ?? {});
+	config = next;
+	revision++;
+	if (store) await store.request("configure", config).catch(() => {});
+	remoteState = !next.enabled || !next.langfuse.enabled ? "disabled" : "missing_credentials";
+	if (remoteState === "disabled") {
+		target?.close();
+		target = void 0;
+		targetSignature = "";
+		return;
+	}
+	try {
+		const secretKey = process.env.LANGFUSE_SECRET_KEY || await new CredentialResolver().revealGatewayStoredApiKey("langfuse");
+		const publicKey = process.env.LANGFUSE_PUBLIC_KEY || await new CredentialResolver().revealGatewayStoredApiKey("langfuse-public");
+		if (version !== configureVersion) return;
+		if (secretKey && publicKey) {
+			const baseUrl = process.env.LANGFUSE_BASE_URL || next.langfuse.baseUrl;
+			const signature = JSON.stringify([
+				baseUrl,
+				publicKey,
+				secretKey
+			]);
+			knownSecrets = [...new Set([
+				...knownSecrets,
+				secretKey,
+				publicKey
+			])].slice(-64);
+			if (!target || signature !== targetSignature) {
+				target?.close();
+				target = new LangfuseTarget(baseUrl, publicKey, secretKey);
+				targetSignature = signature;
+			}
+			remoteState = "ready";
+		} else {
+			target?.close();
+			target = void 0;
+			targetSignature = "";
+		}
+	} catch {
+		remoteState = "missing_credentials";
+		target?.close();
+		target = void 0;
+		targetSignature = "";
+	}
+}
+async function tracingStatus() {
+	return {
+		local: {
+			...await localStore().request("status").catch(() => ({ unavailable: true })),
+			pending: pendingLocal.size,
+			pendingBytes: pendingLocalBytes,
+			queueDropped: localStore().dropped,
+			lastError: localStore().lastError
+		},
+		langfuse: target?.status() ?? {
+			state: remoteState,
+			pending: 0,
+			dropped: 0
+		},
+		active,
+		dropped
+	};
+}
+function traceIds() {
+	const current = trace.getSpan(context.active())?.spanContext();
+	return current ? {
+		traceId: current.traceId,
+		spanId: current.spanId
+	} : {};
+}
+function attrs(identity, type) {
+	const result = {
+		...type === "agent" ? { "xopc.localRoot": true } : {},
+		"langfuse.observation.type": type,
+		"xopc.configRevision": revision
+	};
+	for (const [key, value] of Object.entries(identity)) if (value) {
+		result[`xopc.${key}`] = value;
+		result[`langfuse.trace.metadata.${key}`] = value;
+	}
+	if (scopes.getStore()?.name) result["langfuse.trace.name"] = scopes.getStore().name;
+	if (identity.conversationId) result["langfuse.session.id"] = identity.conversationId;
+	return result;
+}
+function startObservation(name, type, identity = {}) {
+	const scope = scopes.getStore();
+	if (!(scope?.config ?? config).enabled || scope && ++scope.count > 1e3) {
+		if (scope?.count > 1e3) scope.root?.setAttribute("xopc.partialReason", "span_quota");
+		dropped++;
+		return {
+			run: (fn) => fn(),
+			finish() {},
+			input() {},
+			update() {}
+		};
+	}
+	const standalone = !scope;
+	if (standalone && active >= 256) {
+		dropped++;
+		return {
+			run: (fn) => fn(),
+			finish() {},
+			input() {},
+			update() {}
+		};
+	}
+	if (standalone) active++;
+	const span = tracer().startSpan(name.slice(0, 120), { attributes: attrs({
+		...scope?.identity,
+		...identity
+	}, type) });
+	const spanContext = trace.setSpan(context.active(), span).setValue(localEpochKey, localEpochs.get(span) ?? context.active().getValue(localEpochKey));
+	let ended = false;
+	const put = (key, value) => {
+		const policy = scope?.config ?? config;
+		if (policy.capture === "metadata") return;
+		const json = secretSafe(boundedJson(value, policy.capture === "detailed" && (policy.detailedUntil ?? 0) > Date.now() ? 65536 : 8192));
+		if (scope && (scope.bytes += Buffer.byteLength(json)) > policy.local.maxTraceKiB * 1024) {
+			span.setAttribute("xopc.partialReason", "capture_quota");
+			return;
+		}
+		span.setAttribute(key, json);
+	};
+	return {
+		span,
+		run: (fn) => context.with(spanContext, () => runWithLogContext({
+			...identity,
+			...traceIds()
+		}, fn)),
+		input: (value) => put("langfuse.observation.input", value),
+		update: (values) => {
+			for (const [key, value] of Object.entries(values)) if (value !== void 0) span.setAttribute(key, typeof value === "string" ? secretSafe(value.slice(0, 1024)) : value);
+		},
+		finish(status = "success", output) {
+			if (ended) return;
+			ended = true;
+			if (standalone) active--;
+			if (output !== void 0) put("langfuse.observation.output", output);
+			span.setAttribute("xopc.status", status);
+			span.setStatus({ code: status === "error" ? SpanStatusCode.ERROR : SpanStatusCode.OK });
+			span.end();
+		}
+	};
+}
+async function traceRun(name, identity, fn, input) {
+	if (scopes.getStore() || !config.enabled) return fn();
+	if (active >= 256) {
+		dropped++;
+		return scopes.run({
+			config: {
+				...config,
+				enabled: false
+			},
+			identity,
+			name,
+			count: 0,
+			bytes: 0
+		}, fn);
+	}
+	active++;
+	const scope = {
+		config: structuredClone(config),
+		target,
+		identity,
+		name,
+		count: 0,
+		bytes: 0
+	};
+	try {
+		return await scopes.run(scope, async () => {
+			const observation = startObservation(name, "agent", identity);
+			scope.root = observation.span;
+			observation.input(input);
+			try {
+				const result = await observation.run(fn);
+				observation.finish(result.stopReason ? "suspended" : result.ok === false ? result.errorMessage === "aborted" ? "cancelled" : "error" : "success", result.lastAssistantText ?? result.errorMessage);
+				return result;
+			} catch (error) {
+				observation.finish("error", error instanceof Error ? error.message : String(error));
+				throw error;
+			}
+		});
+	} finally {
+		active--;
+	}
+}
+const tracedExecutions = /* @__PURE__ */ new WeakSet();
+function traceTools(tools) {
+	return tools.map((tool) => {
+		if (tracedExecutions.has(tool.execute)) return tool;
+		const execute = (...args) => {
+			const observation = startObservation(`tool.${tool.name}`, "tool");
+			observation.update({ "xopc.toolCallId": String(args[0]) });
+			observation.input(args[1]);
+			return observation.run(async () => {
+				try {
+					const result = await tool.execute(...args);
+					observation.finish(result?.isError || result?.details?.isError ? "error" : "success", result);
+					return result;
+				} catch (error) {
+					observation.finish(args[2]?.aborted ? "cancelled" : "error", error instanceof Error ? error.message : String(error));
+					throw error;
+				}
+			});
+		};
+		tracedExecutions.add(execute);
+		return {
+			...tool,
+			execute
+		};
+	});
+}
+async function flushTracing() {
+	const timer = new Promise((resolve) => {
+		setTimeout(resolve, 3e3).unref();
+	});
+	await Promise.race([(async () => {
+		await Promise.allSettled([...pendingLocal]);
+		await Promise.allSettled([store?.flush(), target?.flush()]);
+	})(), timer]);
+}
+async function testLangfuse() {
+	if (!target) return false;
+	const result = await traceRun("diagnostic.langfuse", {}, async () => ({ ok: true }));
+	await target.flush();
+	return result.ok && !target.status().lastError;
+}
+async function closeTracing() {
+	await flushTracing();
+	target?.close();
+	target = void 0;
+	targetSignature = "";
+	await store?.close();
+	store = void 0;
+}
+async function traceOperation(name, fn, attributes = {}) {
+	const observation = startObservation(name, "span");
+	observation.update(attributes);
+	try {
+		const result = await observation.run(fn);
+		observation.finish();
+		return result;
+	} catch (error) {
+		observation.finish("error", error instanceof Error ? error.message : String(error));
+		throw error;
+	}
+}
+function setTraceIdentity(identity) {
+	const scope = scopes.getStore();
+	if (!scope) return;
+	scope.identity = {
+		...scope.identity,
+		...identity
+	};
+	scope.root?.setAttributes(attrs(scope.identity, "agent"));
+}
+//#endregion
+export { closeTracing, configureTracing, flushTracing, localStore, setTraceIdentity, startObservation, testLangfuse, traceIds, traceOperation, traceRun, traceTools, tracingConfig, tracingStatus };

package/dist/src/observability/sanitize.d.ts

@@ -0,0 +1,3 @@
+export declare function redactString(value: string): string;
+/** Bounds traversal before serializing; never materializes an entire tool/file payload. */
+export declare function boundedJson(value: unknown, maxBytes?: number): string;