@xopcai/xopc 0.0.361 → 0.0.363

package/dist/src/gateway/hono/routes/lazy-bundles.js

@@ -297,6 +297,14 @@ const AUTHENTICATED_LAZY_ROUTE_BUNDLES = [
 			return { register: registerLogsRoutes };
 		}
 	},
+	{
+		id: "observability",
+		match: (path) => startsWithAny(path, ["/api/observability"]),
+		load: async () => {
+			const { registerObservabilityRoutes } = await import("./observability.js");
+			return { register: registerObservabilityRoutes };
+		}
+	},
 	{
 		id: "usage",
 		match: (path) => startsWithAny(path, ["/api/usage"]),

package/dist/src/gateway/hono/routes/models.js

@@ -1,11 +1,11 @@
-import { resolveEffectiveAgentConfigForAgent } from "../../../config/agent-profile.js";
 import { resolveModelsJsonPath } from "../../../config/paths.js";
+import { CredentialResolver, init_credentials } from "../../../auth/credentials.js";
+import { resolveEffectiveAgentConfigForAgent } from "../../../config/agent-profile.js";
 import { init_resolve_config_value, testApiKeyResolution } from "../../../config/resolve-config-value.js";
 import { computerModelProfile, init_model_policy, isDedicatedComputerModel } from "../../../computer/model-policy.js";
 import { init_models_json, loadModelsJson, saveModelsJson, validateModelsConfig } from "../../../config/models-json.js";
 import { getModelCatalogStore, init_model_catalog_store } from "../../../providers/model-catalog-store.js";
 import { getModelRegistry } from "../../../providers/model-registry.js";
-import { CredentialResolver, init_credentials } from "../../../auth/credentials.js";
 import "../../../providers/constants.js";
 import { getProviderRegistry, init_plugin_registry } from "../../../providers/plugin-registry.js";
 import { PROVIDER_META, getAllModels, getAllProviders, getAvailableModels, getProviderAuthState, init_providers, isProviderConfigured, isProviderConfiguredSync } from "../../../providers/index.js";

package/dist/src/gateway/hono/routes/observability.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from 'hono';
+import type { AuthenticatedRouteDeps } from './deps.js';
+export declare function registerObservabilityRoutes(authenticated: Hono, { service, strictRateLimitMiddleware }: AuthenticatedRouteDeps): void;

package/dist/src/gateway/hono/routes/observability.js

@@ -0,0 +1,106 @@
+import { CredentialResolver, init_credentials } from "../../../auth/credentials.js";
+import { TracingConfigSchema, init_config } from "../../../observability/config.js";
+import { configureTracing, localStore, testLangfuse, tracingConfig, tracingStatus } from "../../../observability/runtime.js";
+import { z } from "zod";
+import { Hono } from "hono";
+//#region src/gateway/hono/routes/observability.ts
+init_credentials();
+init_config();
+const traceIdSchema = z.string().regex(/^[0-9a-f]{32}$/);
+const querySchema = z.object({
+	limit: z.coerce.number().int().min(1).max(100).optional(),
+	cursor: z.string().regex(/^\d{1,16}:[0-9a-f]{32}$/).optional(),
+	from: z.coerce.number().int().nonnegative().optional(),
+	to: z.coerce.number().int().positive().optional(),
+	status: z.enum([
+		"running",
+		"success",
+		"error",
+		"cancelled",
+		"suspended",
+		"interrupted"
+	]).optional(),
+	conversationId: z.string().max(200).optional(),
+	runId: z.string().max(200).optional(),
+	agentId: z.string().max(200).optional()
+});
+function registerObservabilityRoutes(authenticated, { service, strictRateLimitMiddleware }) {
+	const app = new Hono();
+	app.onError((error, c) => {
+		if (error instanceof z.ZodError || error instanceof SyntaxError) return c.json({ error: "Invalid tracing request" }, 400);
+		return c.json({ error: "Tracing service unavailable" }, 503);
+	});
+	app.get("/tracing/settings", async (c) => {
+		const resolver = new CredentialResolver();
+		const secret = process.env.LANGFUSE_SECRET_KEY || await resolver.revealGatewayStoredApiKey("langfuse");
+		const pub = process.env.LANGFUSE_PUBLIC_KEY || await resolver.revealGatewayStoredApiKey("langfuse-public");
+		return c.json({
+			config: tracingConfig(),
+			credentials: {
+				publicKeyConfigured: Boolean(pub),
+				secretKeyConfigured: Boolean(secret),
+				publicKeySource: process.env.LANGFUSE_PUBLIC_KEY ? "environment" : pub ? "stored" : "none",
+				secretKeySource: process.env.LANGFUSE_SECRET_KEY ? "environment" : secret ? "stored" : "none",
+				baseUrlSource: process.env.LANGFUSE_BASE_URL ? "environment" : "config"
+			}
+		});
+	});
+	app.patch("/tracing/settings", strictRateLimitMiddleware, async (c) => {
+		const parsed = TracingConfigSchema.parse(await c.req.json());
+		if (parsed.capture === "detailed") parsed.detailedUntil = Date.now() + 1800 * 1e3;
+		else delete parsed.detailedUntil;
+		const next = {
+			...service.currentConfig,
+			observability: { tracing: parsed }
+		};
+		if (!(await service.saveConfig(next)).saved) return c.json({ error: "Could not save tracing configuration" }, 500);
+		await configureTracing(parsed);
+		return c.json({
+			ok: true,
+			config: parsed
+		});
+	});
+	app.put("/tracing/langfuse/credentials", strictRateLimitMiddleware, async (c) => {
+		const body = z.object({
+			publicKey: z.string().trim().min(1).max(512).optional(),
+			secretKey: z.string().trim().min(1).max(512).optional()
+		}).strict().parse(await c.req.json());
+		const resolver = new CredentialResolver();
+		if (body.publicKey) await resolver.saveApiKey("langfuse-public", body.publicKey, { profileName: "default" });
+		if (body.secretKey) await resolver.saveApiKey("langfuse", body.secretKey, { profileName: "default" });
+		await configureTracing(service.currentConfig.observability?.tracing);
+		return c.json({ ok: true });
+	});
+	app.delete("/tracing/langfuse/credentials", strictRateLimitMiddleware, async (c) => {
+		const resolver = new CredentialResolver();
+		await resolver.deleteProviderCredential("langfuse");
+		await resolver.deleteProviderCredential("langfuse-public");
+		await configureTracing(service.currentConfig.observability?.tracing);
+		return c.json({ ok: true });
+	});
+	app.post("/tracing/langfuse/test", strictRateLimitMiddleware, async (c) => c.json({ ok: await testLangfuse() }));
+	app.get("/tracing/status", async (c) => c.json(await tracingStatus()));
+	app.get("/traces", async (c) => c.json(await localStore().request("list", querySchema.parse(c.req.query()))));
+	app.post("/traces/prune", strictRateLimitMiddleware, async (c) => {
+		await localStore().request("prune");
+		return c.json({ ok: true });
+	});
+	app.delete("/traces", strictRateLimitMiddleware, async (c) => {
+		await localStore().clear();
+		return c.json({ ok: true });
+	});
+	app.get("/traces/:traceId/export", async (c) => {
+		const id = traceIdSchema.parse(c.req.param("traceId"));
+		const data = await localStore().request("detail", id);
+		if (!data) return c.json({ error: "Trace not found" }, 404);
+		c.header("Content-Disposition", `attachment; filename="trace-${id}.json"`);
+		return c.json(data);
+	});
+	app.get("/traces/:traceId", async (c) => {
+		const data = await localStore().request("detail", traceIdSchema.parse(c.req.param("traceId")));
+		return data ? c.json(data) : c.json({ error: "Trace not found" }, 404);
+	});
+	authenticated.route("/api/observability", app);
+}
+//#endregion
+export { registerObservabilityRoutes };

package/dist/src/gateway/image-generation-setup.js

@@ -1,7 +1,7 @@
 import { normalizeAgentId } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
-import { ConfigSchema, init_schema } from "../config/schema.js";
 import { init_agent_scope } from "../agent/agent-scope.js";
+import { ConfigSchema, init_schema } from "../config/schema.js";
 import { resolveEffectiveAgentConfigForAgent } from "../config/agent-profile.js";
 import { fetchWithTimeoutGuarded } from "../media-shared/http/provider-http.js";
 import "../media-shared/http/index.js";

package/dist/src/gateway/lock.js

@@ -1,8 +1,8 @@
 import path from "node:path";
 import fs from "node:fs";
 import { createHash } from "node:crypto";
-import net from "node:net";
 import fs$1 from "node:fs/promises";
+import net from "node:net";
 import { homedir } from "os";
 //#region src/gateway/lock.ts
 /**

package/dist/src/gateway/security/gateway-scopes.js

@@ -24,6 +24,7 @@ function requiredGatewayScope(method, path) {
 	if (method === "GET" && path === "/api/connectors/approvals") return "sessions.read";
 	if (method === "POST" && path === "/api/connectors/approvals/respond") return "sessions.write";
 	if (path === "/api/agent" || path.startsWith("/api/agent/")) return "agents.run";
+	if (path === "/api/observability" || path.startsWith("/api/observability/")) return "gateway.admin";
 	if (path.startsWith("/api/usage")) return "gateway.admin";
 	if (path.startsWith("/api/agents") || path.startsWith("/api/models")) return methodScope(method, "agents.read", "gateway.admin");
 	if (path.startsWith("/api/sessions") || path.startsWith("/api/side-chats")) return methodScope(method, "sessions.read", "sessions.write");

package/dist/src/gateway/service/config-coordinator.d.ts

@@ -1,28 +1,3 @@
-/**
- * GatewayConfigCoordinator — owns config persistence, hot-reload, and the
- * per-section reload handlers.
- *
- * Was 350 lines of `GatewayService` covering nine concerns:
- *   - manual `reloadConfig()` (CLI/UI trigger)
- *   - `saveConfig()` / `updateConfig()` (PATCH /api/config)
- *   - `setExtensionActivationTarget` (extension lifecycle)
- *   - `afterWeixinCredentialsPersisted` / `afterFeishuCredentialsPersisted`
- *     (QR-login follow-ups that bypass the watcher)
- *   - `ConfigHotReloader` (fs.watch → debounced per-section dispatch)
- *   - Section reload handlers (models / agents / channels /
- *     tools / mcp / extensions)
- *   - `scheduleChannelPluginsAfterPersist` (coalesces rapid saves so
- *     Telegram/Weixin do not stop/start repeatedly)
- *
- * Pulled out so the gateway composition root stays focused on lifecycle, and
- * each handler is reachable from one place when adding a new config section.
- *
- * **Config state ownership.** `GatewayService.config` is still the single
- * source of truth — this coordinator reads it via `getConfig()` and writes it
- * back via `setConfig()` after every reload / persist. We pass through rather
- * than holding our own copy so other coordinators (sessions, marketplace,
- * agent runner) see the latest config the moment a reload commits.
- */
 import type { Config } from '../../config/schema.js';
 import type { AgentService } from '../../agent/service.js';
 import type { ChannelManager } from '../../channels/manager.js';

package/dist/src/gateway/service/config-coordinator.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { configureTracing } from "../../observability/runtime.js";
 import { getModelRegistry } from "../../providers/model-registry.js";
 import { init_providers } from "../../providers/index.js";
 import { disposeAllSessionMcpRuntimes } from "../../agent/mcp/bundle-mcp-runtime.js";
@@ -11,6 +12,31 @@ import "../../config/index.js";
 import { computeExtensionActivationPatch } from "../../extensions/bundled-extension-activation.js";
 import { sanitizeTunnelConfig } from "../../tunnel/tunnel-config.js";
 //#region src/gateway/service/config-coordinator.ts
+/**
+* GatewayConfigCoordinator — owns config persistence, hot-reload, and the
+* per-section reload handlers.
+*
+* Was 350 lines of `GatewayService` covering nine concerns:
+*   - manual `reloadConfig()` (CLI/UI trigger)
+*   - `saveConfig()` / `updateConfig()` (PATCH /api/config)
+*   - `setExtensionActivationTarget` (extension lifecycle)
+*   - `afterWeixinCredentialsPersisted` / `afterFeishuCredentialsPersisted`
+*     (QR-login follow-ups that bypass the watcher)
+*   - `ConfigHotReloader` (fs.watch → debounced per-section dispatch)
+*   - Section reload handlers (models / agents / channels /
+*     tools / mcp / extensions)
+*   - `scheduleChannelPluginsAfterPersist` (coalesces rapid saves so
+*     Telegram/Weixin do not stop/start repeatedly)
+*
+* Pulled out so the gateway composition root stays focused on lifecycle, and
+* each handler is reachable from one place when adding a new config section.
+*
+* **Config state ownership.** `GatewayService.config` is still the single
+* source of truth — this coordinator reads it via `getConfig()` and writes it
+* back via `setConfig()` after every reload / persist. We pass through rather
+* than holding our own copy so other coordinators (sessions, marketplace,
+* agent runner) see the latest config the moment a reload commits.
+*/
 init_providers();
 init_logger();
 const log = createLogger("GatewayConfigCoordinator");
@@ -26,6 +52,10 @@ var GatewayConfigCoordinator = class {
 	startHotReloader() {
 		if (this.configReloader) return;
 		this.configReloader = new ConfigHotReloader(this.opts.configPath, this.opts.getConfig(), {
+			onTracingReload: async (next) => {
+				this.opts.setConfig(next);
+				await configureTracing(next.observability?.tracing);
+			},
 			onModelsReload: (newConfig) => this.handleModelsReload(newConfig),
 			onChannelsReload: (newConfig) => this.handleChannelsReload(newConfig),
 			onCronReload: (newConfig) => this.handleAutomationReload(newConfig),
@@ -316,6 +346,7 @@ var GatewayConfigCoordinator = class {
 		await saveConfig(configToWrite, this.opts.configPath);
 		const reloaded = loadConfig(this.opts.configPath);
 		this.opts.setConfig(reloaded);
+		await configureTracing(reloaded.observability?.tracing);
 		if (sanitizeTunnelConfig(reloaded)) await saveConfig(reloaded, this.opts.configPath);
 		this.opts.getAgentService().applyRuntimeConfiguration(reloaded);
 		await this.opts.reconcileMemoryMaintenanceAutomations().catch((err) => {

package/dist/src/gateway/service.js

@@ -17,14 +17,15 @@ import { init_session_repository, listSessionMetadata, patchSessionMetadata } fr
 import { getSessionConfig, init_config_repository } from "../storage/sqlite/config-repository.js";
 import { init_sqlite } from "../storage/sqlite/index.js";
 import { normalizeAgentId } from "../agent-catalog/id.js";
+import { init_agent_scope, listAgentEntries, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { init_paths, resolveConfigPath, resolveExtensionsDir } from "../config/paths.js";
+import { flushTracing } from "../observability/runtime.js";
 import { init_config, resolveKnowledgeReadPolicy } from "../user-context/config.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
-import { init_agent_scope, listAgentEntries, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agent/agent-scope.js";
 import { init_agent_session_key, resolveAgentMainConversationId } from "../routing/agent-session-key.js";
 import { init_session_key, resolveConversationId, sanitizeSegment } from "../routing/session-key.js";
 import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
 import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
-import { init_paths, resolveConfigPath, resolveExtensionsDir } from "../config/paths.js";
 import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { init_providers, providers_exports } from "../providers/index.js";
 import { AI_USAGE_RETENTION_MS, markStaleAiUsageEventsUnknown, pruneAiUsageEvents } from "../storage/sqlite/ai-usage-repository.js";
@@ -1513,6 +1514,7 @@ var GatewayService = class {
 		}
 	}
 	async stop() {
+		await flushTracing();
 		if (!this.running) return;
 		this.stopping = true;
 		this.taskRunDispatcher?.stop();
@@ -1563,7 +1565,7 @@ var GatewayService = class {
 		await disposeAllSessionMcpRuntimes().catch((err) => {
 			log.warn({ err }, "MCP runtime shutdown failed");
 		});
-		this._agentService?.stop();
+		await this._agentService?.stop();
 		this.running = false;
 		this.bus.shutdown();
 		this.lastDeferredChannelConnectIds = [];

package/dist/src/gateway/side-chat/manager.js

@@ -6,7 +6,8 @@ import { createSideChatContextSnapshot, formatSideChatSelections, validateSideCh
 import { randomUUID } from "node:crypto";
 //#region src/gateway/side-chat/manager.ts
 init_logger();
-const DEFAULT_IDLE_TTL_MS = 1800 * 1e3;
+const DEFAULT_IDLE_TTL_MS = 360 * 60 * 1e3;
+const EXPIRED_RECORD_RETENTION_MS = 1800 * 1e3;
 const DEFAULT_MAX_PER_CLIENT = 5;
 const DEFAULT_MAX_TOTAL = 50;
 const MAX_EXPIRED_RECORDS = 500;
@@ -260,7 +261,7 @@ var EphemeralSideChatManager = class {
 		this.expired.set(entry.id, {
 			clientInstanceId: entry.clientInstanceId,
 			reason,
-			removeAt: this.now() + DEFAULT_IDLE_TTL_MS
+			removeAt: this.now() + EXPIRED_RECORD_RETENTION_MS
 		});
 		this.pruneExpiredRecords(this.now());
 		const cleanup = this.disposeEntry(entry.id, entry.clientInstanceId);

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const TracingConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    capture: z.ZodDefault<z.ZodEnum<{
+        metadata: "metadata";
+        redacted: "redacted";
+        detailed: "detailed";
+    }>>;
+    detailedUntil: z.ZodOptional<z.ZodNumber>;
+    local: z.ZodPrefault<z.ZodObject<{
+        retentionDays: z.ZodDefault<z.ZodNumber>;
+        maxStoreMiB: z.ZodDefault<z.ZodNumber>;
+        maxTraces: z.ZodDefault<z.ZodNumber>;
+        maxSpans: z.ZodDefault<z.ZodNumber>;
+        maxTraceKiB: z.ZodDefault<z.ZodNumber>;
+        maxWriteMiBPerMinute: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    langfuse: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        baseUrl: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type TracingConfig = z.infer<typeof TracingConfigSchema>;
+export declare const defaultTracingConfig: () => {
+    enabled: boolean;
+    capture: "metadata" | "redacted" | "detailed";
+    local: {
+        retentionDays: number;
+        maxStoreMiB: number;
+        maxTraces: number;
+        maxSpans: number;
+        maxTraceKiB: number;
+        maxWriteMiBPerMinute: number;
+    };
+    langfuse: {
+        enabled: boolean;
+        baseUrl: string;
+    };
+    detailedUntil?: number;
+};

package/dist/src/observability/config.js

@@ -0,0 +1,31 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { z } from "zod";
+//#region src/observability/config.ts
+var TracingConfigSchema, defaultTracingConfig;
+var init_config = __esmMin((() => {
+	TracingConfigSchema = z.object({
+		enabled: z.boolean().default(true),
+		capture: z.enum([
+			"metadata",
+			"redacted",
+			"detailed"
+		]).default("redacted"),
+		detailedUntil: z.number().int().nonnegative().optional(),
+		local: z.object({
+			retentionDays: z.number().int().min(1).max(90).default(7),
+			maxStoreMiB: z.number().int().min(16).max(4096).default(256),
+			maxTraces: z.number().int().min(10).max(1e5).default(1e4),
+			maxSpans: z.number().int().min(100).max(1e6).default(1e5),
+			maxTraceKiB: z.number().int().min(16).max(4096).default(1024),
+			maxWriteMiBPerMinute: z.number().int().min(1).max(100).default(2)
+		}).prefault({}),
+		langfuse: z.object({
+			enabled: z.boolean().default(false),
+			baseUrl: z.string().url().max(2048).refine((value) => ["http:", "https:"].includes(new URL(value).protocol), "HTTP(S) URL required").default("https://cloud.langfuse.com")
+		}).prefault({})
+	}).strict();
+	defaultTracingConfig = () => TracingConfigSchema.parse({});
+}));
+//#endregion
+init_config();
+export { TracingConfigSchema, defaultTracingConfig, init_config };

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

@@ -0,0 +1,31 @@
+import type { TraceRecord } from './types.js';
+/** Bounded OTLP/HTTP JSON exporter. No hidden SDK queue or durable replay. */
+export declare class LangfuseTarget {
+    private baseUrl;
+    private publicKey;
+    private secretKey;
+    private queue;
+    private bytes;
+    private timer?;
+    private sending?;
+    private controller?;
+    private closed;
+    private lastWarning;
+    dropped: number;
+    lastSuccess?: number;
+    lastFailure?: number;
+    lastError?: string;
+    constructor(baseUrl: string, publicKey: string, secretKey: string);
+    status(): {
+        state: string;
+        pending: number;
+        dropped: number;
+        lastSuccess: number;
+        lastFailure: number;
+        lastError: string;
+    };
+    enqueue(record: TraceRecord): void;
+    flush(): Promise<void>;
+    private send;
+    close(): void;
+}

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;