@xopcai/xopc 0.0.362 → 0.0.364

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;

package/dist/src/observability/sanitize.js

@@ -0,0 +1,74 @@
+//#region src/observability/sanitize.ts
+const SECRET_KEY = /authorization|api.?key|password|secret|access.?token|refresh.?token|bot.?token|cookie/i;
+const OMIT_KEY = /^(data|base64|headers|image_url|audio|video)$/i;
+function redactString(value) {
+	return value.replace(/Bearer\s+[^\s"']+/gi, "Bearer [REDACTED]").replace(/\b(?:sk-|pk-lf-|sk-lf-)[A-Za-z0-9_-]+/g, "[REDACTED]").replace(/((?:api[_-]?key|token|secret|password)\s*[=:]\s*)[^\s,;"']+/gi, "$1[REDACTED]").replace(/data:[^\s"']+;base64,[^\s"']+/gi, "[MEDIA OMITTED]");
+}
+/** Bounds traversal before serializing; never materializes an entire tool/file payload. */
+function boundedJson(value, maxBytes = 8192) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	let budget = Math.max(64, maxBytes - 256);
+	let truncated = false;
+	const walk = (v, depth) => {
+		if (budget < 32 || depth > 5) {
+			truncated = true;
+			return "[TRUNCATED]";
+		}
+		if (v === null || typeof v === "number" || typeof v === "boolean") {
+			budget -= 16;
+			return v;
+		}
+		if (typeof v === "string") {
+			const slice = v.slice(0, Math.min(budget, 4096));
+			const clean = redactString(slice);
+			const buf = Buffer.from(clean);
+			const size = Math.min(budget, 4096);
+			budget -= Math.min(buf.length, size);
+			if (slice.length < v.length || buf.length > size) truncated = true;
+			return buf.subarray(0, size).toString("utf8");
+		}
+		if (typeof v !== "object") return void 0;
+		if (seen.has(v)) return "[CIRCULAR]";
+		seen.add(v);
+		if (Array.isArray(v)) {
+			const values = [];
+			for (let i = 0; i < Math.min(v.length, 40) && budget > 32; i++) values.push(walk(v[i], depth + 1));
+			if (values.length < v.length) truncated = true;
+			return values;
+		}
+		const result = {};
+		let count = 0;
+		for (const key in v) {
+			if (!Object.hasOwn(v, key)) continue;
+			if (++count > 40 || budget < 32) {
+				truncated = true;
+				break;
+			}
+			const safeKey = key.slice(0, 80);
+			budget -= Buffer.byteLength(safeKey) + 8;
+			try {
+				result[safeKey] = SECRET_KEY.test(key) ? "[REDACTED]" : OMIT_KEY.test(key) ? "[OMITTED]" : walk(v[key], depth + 1);
+			} catch {
+				result[safeKey] = "[UNAVAILABLE]";
+			}
+		}
+		return result;
+	};
+	let data;
+	try {
+		data = walk(value, 0);
+	} catch {
+		data = "[UNAVAILABLE]";
+	}
+	const text = JSON.stringify({
+		preview: data,
+		truncated
+	});
+	if (Buffer.byteLength(text) <= maxBytes) return text;
+	return JSON.stringify({
+		preview: Buffer.from(redactString(text)).subarray(0, Math.floor(maxBytes / 8)).toString("utf8"),
+		truncated: true
+	});
+}
+//#endregion
+export { boundedJson, redactString };

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

@@ -0,0 +1,20 @@
+import type { TracingConfig } from './config.js';
+import type { TraceRecord } from './types.js';
+export declare class LocalTraceStore {
+    private worker?;
+    private sequence;
+    private requests;
+    private pendingBytes;
+    private epoch;
+    private epochReady;
+    dropped: number;
+    lastError?: string;
+    constructor(config: TracingConfig, file?: string);
+    private fail;
+    request(op: string, data?: unknown): Promise<any>;
+    begin(record: TraceRecord): Promise<number>;
+    write(record: TraceRecord, epoch?: number): Promise<void>;
+    clear(): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/src/observability/store.js

@@ -0,0 +1,128 @@
+import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
+import { redactString } from "./sanitize.js";
+import { traceStoreWorkerSource } from "./storeWorker.js";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { Worker } from "node:worker_threads";
+//#region src/observability/store.ts
+init_paths_state();
+var LocalTraceStore = class {
+	worker;
+	sequence = 0;
+	requests = /* @__PURE__ */ new Map();
+	pendingBytes = 0;
+	epoch = 0;
+	epochReady;
+	dropped = 0;
+	lastError;
+	constructor(config, file = join(resolveStateDir(), "traces", "traces.db")) {
+		try {
+			this.worker = new Worker(traceStoreWorkerSource, {
+				eval: true,
+				execArgv: process.execArgv.filter((arg, index, args) => !arg.startsWith("--input-type") && args[index - 1] !== "--input-type"),
+				workerData: {
+					path: file,
+					config,
+					owner: randomUUID()
+				}
+			});
+			this.worker.on("message", ({ id, value, error }) => {
+				const request = this.requests.get(id);
+				if (!request) return;
+				clearTimeout(request.timer);
+				this.requests.delete(id);
+				this.pendingBytes -= request.bytes;
+				if (error) {
+					this.lastError = error;
+					request.reject(new Error(error));
+				} else request.resolve(value);
+				if (!this.requests.size) this.worker?.unref();
+			});
+			this.worker.on("error", (error) => this.fail(`Trace worker unavailable: ${redactString(error instanceof Error ? error.message : "Worker startup failed").slice(0, 200)}`));
+			this.worker.on("exit", () => {
+				if (this.worker) this.fail("Trace worker stopped");
+			});
+			this.worker.unref();
+			this.epochReady = this.request("status").then((s) => {
+				this.epoch = s.epoch;
+			}).catch(() => {});
+		} catch {
+			this.lastError = "Trace worker unavailable";
+			this.epochReady = Promise.resolve();
+		}
+	}
+	fail(message) {
+		this.lastError = message;
+		for (const r of this.requests.values()) {
+			clearTimeout(r.timer);
+			r.reject(new Error(message));
+		}
+		this.requests.clear();
+		this.pendingBytes = 0;
+		this.worker = void 0;
+	}
+	async request(op, data) {
+		if (!this.worker) throw new Error(this.lastError ?? "Trace storage unavailable");
+		const bytes = Buffer.byteLength(JSON.stringify(data ?? null));
+		if (this.requests.size >= 2e3 || this.pendingBytes + bytes > 8 * 1048576) {
+			this.dropped++;
+			throw new Error("Trace queue full");
+		}
+		const id = ++this.sequence;
+		this.pendingBytes += bytes;
+		this.worker.ref();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.requests.delete(id);
+				this.pendingBytes -= bytes;
+				this.dropped++;
+				reject(/* @__PURE__ */ new Error("Trace storage timeout"));
+				this.worker?.terminate();
+			}, 5e3);
+			this.requests.set(id, {
+				resolve,
+				reject,
+				timer,
+				bytes
+			});
+			this.worker.postMessage({
+				id,
+				op,
+				data
+			});
+		});
+	}
+	async begin(record) {
+		await this.epochReady;
+		return this.request("put", {
+			records: [record],
+			epoch: null
+		});
+	}
+	async write(record, epoch) {
+		await this.epochReady;
+		try {
+			await this.request("put", {
+				records: [record],
+				epoch: epoch ?? this.epoch
+			});
+			this.lastError = void 0;
+		} catch (error) {
+			this.dropped++;
+			this.lastError = error instanceof Error ? error.message : "Trace write failed";
+		}
+	}
+	async clear() {
+		this.epoch = await this.request("clear");
+	}
+	async flush() {
+		await this.request("status");
+	}
+	async close() {
+		const worker = this.worker;
+		this.fail("Trace store closed");
+		await worker?.terminate();
+	}
+};
+//#endregion
+export { LocalTraceStore };

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

@@ -0,0 +1,2 @@
+/** Self-contained worker source works in tsx, published unbundled Node, and Electron builds. */
+export declare const traceStoreWorkerSource: string;