@dxos/observability 0.14.0 → 0.16.0

package/dist/lib/Observability.mjs

@@ -1,249 +1,2 @@
-import { n as __reExport, t as __exportAll } from "./chunk-rolldown-runtime.mjs";
-import { t as storage_exports } from "./chunk-storage.mjs";
-import { log } from "@dxos/log";
-import * as Effect from "effect/Effect";
-import { SubscriptionList } from "@dxos/async";
-import * as Array from "effect/Array";
-import * as Function from "effect/Function";
-import { invariant } from "@dxos/invariant";
+export { n as addDataProvider, r as addExtension, i as initialize, a as make } from "./chunk-Observability.mjs";
 export * from "#storage";
-//#region src/Observability.ts
-var Observability_exports = /* @__PURE__ */ __exportAll({
-	addDataProvider: () => addDataProvider,
-	addExtension: () => addExtension,
-	initialize: () => initialize,
-	make: () => make
-});
-__reExport(Observability_exports, storage_exports);
-var __dxlog_file = "/__w/dxos/dxos/packages/sdk/observability/src/Observability.ts";
-var attachAiCapture = async (observability) => {
-	const { AiSpanProcessor, contentCaptureAllowed } = await import("./ai/AiObservability.mjs");
-	const { Otel } = await import("./chunk-extensions.mjs").then((n) => n.t);
-	return Otel.addSpanProcessor(new AiSpanProcessor({
-		captureInference: (inference) => observability.ai.captureInference(inference),
-		captureTurn: (turn) => observability.ai.captureTurn(turn),
-		captureToolCall: (toolCall) => observability.ai.captureToolCall(toolCall),
-		captureEnabled: () => observability.enabled,
-		allowContent: contentCaptureAllowed
-	}));
-};
-var ObservabilityImpl = class {
-	_initialized = false;
-	_extensions = [];
-	_dataProviders = [];
-	_subscriptions = new SubscriptionList();
-	initialize() {
-		if (this._initialized) return Effect.succeed(void 0);
-		const initializedExtensions = [];
-		return Effect.gen({ self: this }, function* () {
-			const context = { setTags: (tags, kind) => this.setTags(tags, kind) };
-			for (const extension of this._extensions) {
-				if (extension.initialize) yield* extension.initialize(context);
-				initializedExtensions.push(extension);
-			}
-			const cleanups = yield* Effect.all(this._dataProviders.map((provider) => provider(this)));
-			this._subscriptions.add(...cleanups.filter((cleanup) => cleanup !== void 0));
-			this._subscriptions.add(yield* Effect.promise(() => attachAiCapture(this)));
-			this._initialized = true;
-		}).pipe(Effect.catch((error) => Effect.gen({ self: this }, function* () {
-			log.catch(error, void 0, {
-				"~LogMeta": "~LogMeta",
-				F: __dxlog_file,
-				L: 102,
-				S: this
-			});
-			for (const extension of initializedExtensions) if (extension.close) yield* extension.close().pipe(Effect.catch(() => Effect.succeed(void 0)));
-			this._subscriptions.clear();
-		})));
-	}
-	close() {
-		return Effect.gen({ self: this }, function* () {
-			this._subscriptions.clear();
-			this._dataProviders.length = 0;
-			for (const extension of this._extensions) if (extension.close) yield* extension.close();
-			this._initialized = false;
-		});
-	}
-	enable() {
-		return Effect.gen({ self: this }, function* () {
-			for (const extension of this._extensions) if (extension.enable) yield* extension.enable();
-		});
-	}
-	disable() {
-		return Effect.gen({ self: this }, function* () {
-			for (const extension of this._extensions) if (extension.disable) yield* extension.disable();
-		});
-	}
-	flush() {
-		return Effect.gen({ self: this }, function* () {
-			for (const extension of this._extensions) if (extension.flush) yield* extension.flush();
-		});
-	}
-	_addExtension(extension) {
-		invariant(!this._initialized, "Observability is already initialized", {
-			"~LogMeta": "~LogMeta",
-			F: __dxlog_file,
-			L: 159,
-			S: this,
-			A: ["!this._initialized", "'Observability is already initialized'"]
-		});
-		this._extensions.push(extension);
-	}
-	_addDataProvider(dataProvider) {
-		invariant(!this._initialized, "Observability is already initialized", {
-			"~LogMeta": "~LogMeta",
-			F: __dxlog_file,
-			L: 164,
-			S: this,
-			A: ["!this._initialized", "'Observability is already initialized'"]
-		});
-		this._dataProviders.push(dataProvider);
-	}
-	/**
-	* Adds a data provider and initializes it.
-	*/
-	addDataProvider(dataProvider) {
-		return Effect.gen({ self: this }, function* () {
-			this._dataProviders.push(dataProvider);
-			const cleanup = yield* dataProvider(this);
-			if (cleanup) this._subscriptions.add(cleanup);
-		});
-	}
-	identify(distinctId, attributes, setOnceAttributes) {
-		for (const extension of this._extensions) extension.identify?.(distinctId, attributes, setOnceAttributes);
-	}
-	alias(distinctId, previousId) {
-		for (const extension of this._extensions) extension.alias?.(distinctId, previousId);
-	}
-	setTags(tags, kind) {
-		for (const extension of this._extensions) {
-			if (kind && !extension.apis.some((api) => api.kind === kind)) continue;
-			const processedTags = Object.fromEntries(Object.entries(tags).filter((entry) => entry[1] !== void 0).map(([key, value]) => [key, value.toString()]));
-			extension.setTags?.(processedTags, kind);
-		}
-	}
-	get enabled() {
-		return this._extensions.every((extension) => extension.enabled);
-	}
-	get errors() {
-		return { captureException: (error, attributes) => {
-			for (const extension of this._getExtensions("errors")) extension.captureException(error, attributes);
-		} };
-	}
-	get events() {
-		return { captureEvent: (event, attributes) => {
-			for (const extension of this._getExtensions("events")) extension.captureEvent(event, attributes);
-		} };
-	}
-	get mcp() {
-		return {
-			captureInitialize: (client) => {
-				for (const extension of this._getExtensions("mcp")) extension.captureInitialize(client);
-			},
-			captureToolCall: (call) => {
-				for (const extension of this._getExtensions("mcp")) extension.captureToolCall(call);
-			}
-		};
-	}
-	get ai() {
-		return {
-			captureInference: (inference) => {
-				for (const extension of this._getExtensions("ai")) extension.captureInference(inference);
-			},
-			captureTurn: (turn) => {
-				for (const extension of this._getExtensions("ai")) extension.captureTurn(turn);
-			},
-			captureToolCall: (toolCall) => {
-				for (const extension of this._getExtensions("ai")) extension.captureToolCall(toolCall);
-			}
-		};
-	}
-	get support() {
-		return {
-			uploadLogs: async () => {
-				let key;
-				for (const extension of this._getExtensions("support")) key = await extension.uploadLogs() ?? key;
-				return key;
-			},
-			uploadNdjson: async (ndjson, kind) => {
-				let key;
-				for (const extension of this._getExtensions("support")) key = await extension.uploadNdjson(ndjson, kind) ?? key;
-				return key;
-			},
-			sessionContext: () => {
-				for (const extension of this._getExtensions("support")) {
-					const context = extension.sessionContext();
-					if (context) return context;
-				}
-			},
-			flushLogs: async (attributes) => {
-				for (const extension of this._getExtensions("support")) await extension.flushLogs(attributes);
-			}
-		};
-	}
-	isAvailable(kind) {
-		const apis = this._getExtensions(kind);
-		if (apis.length === 0) return Effect.succeed(false);
-		return Effect.gen({ self: this }, function* () {
-			for (const api of apis) if (yield* api.isAvailable()) return true;
-			return false;
-		});
-	}
-	get metrics() {
-		return {
-			gauge: (name, value, attributes, meta) => {
-				for (const extension of this._getExtensions("metrics")) extension.gauge(name, value, attributes, meta);
-			},
-			increment: (name, value, attributes, meta) => {
-				for (const extension of this._getExtensions("metrics")) extension.increment(name, value, attributes, meta);
-			},
-			distribution: (name, value, attributes, meta) => {
-				for (const extension of this._getExtensions("metrics")) extension.distribution(name, value, attributes, meta);
-			},
-			observe: (name, callback, attributes, meta) => {
-				const cleanups = this._getExtensions("metrics").map((extension) => extension.observe(name, callback, attributes, meta));
-				return () => {
-					for (const cleanup of cleanups) cleanup();
-				};
-			}
-		};
-	}
-	_getExtensions(kind) {
-		return Function.pipe(this._extensions, Array.flatMap((extension) => extension.apis), Array.filter((api) => api.kind === kind));
-	}
-};
-var make = () => Effect.succeed(new ObservabilityImpl());
-var addExtension = (_extension) => Effect.fn(function* (_observability) {
-	const observability = yield* _observability;
-	const extension = yield* _extension;
-	invariant("_addExtension" in observability && typeof observability._addExtension === "function", void 0, {
-		"~LogMeta": "~LogMeta",
-		F: __dxlog_file,
-		L: 367,
-		S: this,
-		A: ["'_addExtension' in observability && typeof observability._addExtension === 'function'", ""]
-	});
-	observability._addExtension(extension);
-	return observability;
-});
-var addDataProvider = (dataProvider) => Effect.fn(function* (_observability) {
-	const observability = yield* _observability;
-	invariant("_addDataProvider" in observability && typeof observability._addDataProvider === "function", void 0, {
-		"~LogMeta": "~LogMeta",
-		F: __dxlog_file,
-		L: 375,
-		S: this,
-		A: ["'_addDataProvider' in observability && typeof observability._addDataProvider === 'function'", ""]
-	});
-	observability._addDataProvider(dataProvider);
-	return observability;
-});
-var initialize = Effect.fn(function* (_observability) {
-	const observability = yield* _observability;
-	yield* observability.initialize();
-	return observability;
-});
-//#endregion
-export { addDataProvider, addExtension, initialize, make, Observability_exports as t };
-
-//# sourceMappingURL=Observability.mjs.map

package/dist/lib/ai/AiObservability.mjs

@@ -1,238 +1 @@
-import { t as __exportAll } from "../chunk-rolldown-runtime.mjs";
-import { log } from "@dxos/log";
-import { SpanStatusCode } from "@opentelemetry/api";
-import * as SpanAttributes from "@dxos/effect/SpanAttributes";
-//#region src/ai/AiObservability.ts
-var AiObservability_exports = /* @__PURE__ */ __exportAll({
-	AiSpanProcessor: () => AiSpanProcessor,
-	contentCaptureAllowed: () => contentCaptureAllowed,
-	stripUndefined: () => stripUndefined
-});
-var __dxlog_file = "/__w/dxos/dxos/packages/sdk/observability/src/ai/AiObservability.ts";
-/**
-* AI telemetry capture — data policy.
-*
-* The AI stack already annotates every model call with the OTel GenAI conventions (`gen_ai.*`,
-* emitted by the `effect/ai` provider layers) plus the `dxos.ai.*` attributes those
-* conventions have no room for. This reads the finished spans, applies the capture policy, and
-* hands each surviving call to a sink as a {@link ObservabilityExtension.Inference} — a shape
-* that follows the GenAI conventions, not any vendor's schema. Mapping onto a backend's own
-* vocabulary belongs to that backend's extension.
-*
-* It is the only place the policy is evaluated, so everything leaving passes through it:
-*
-* - **Nothing** unless {@link Options.captureEnabled} reports the user's telemetry opt-in as on.
-*   The gate is checked here, before a record is built, rather than left to a backend client's own
-*   opt-out flag: that flag is a separate store, so it is not the same answer as the user's
-*   DXOS-side preference.
-* - **Metadata** — model, provider, request parameters, token counts (including the prompt-cache
-*   reads and writes, which price the call and give the hit rate), latency, trace/span/session ids,
-*   error class.
-* - **Content** — prompt, response and tool names, kept only for a span that names its space and
-*   whose space {@link Options.allowContent} accepts. Content is always stamped on the span
-*   upstream (`AiTelemetry` in `@dxos/ai`) and dropped here, rather than conditionally stamped, so
-*   a source that forgets the policy cannot bypass it.
-*
-* Scrub rules enforced here regardless of the above:
-* - A span that does not name its space is treated as unknown, and unknown **denies** content. Only
-*   a call that runs in a known space can have its content captured, so the policy fails closed
-*   for one that does not (`AiSession` names it, and a process scoped to a space stamps it on every
-*   span it runs; a utility model call outside both is reported as metadata only).
-* - Attribute **allowlist**: only the fields of `Inference` are read; every other span attribute
-*   is dropped (so an accidental attribute upstream cannot leak through telemetry).
-* - Errors are reduced to the exception **class name** — `exception.message` and
-*   `exception.stacktrace` recorded on the span are never forwarded, since provider error
-*   messages can embed request or response fragments.
-*
-* Nothing here may throw: `onEnd` runs inside `Span.end()` on the fiber that made the model call,
-* and OTel's `MultiSpanProcessor` does not catch, so an escaping error would fail that call.
-*/
-/**
-* AI telemetry capture policy:
-*
-* | Observability toggle | Space                                 | Capture          |
-* |----------------------|---------------------------------------|------------------|
-* | off                  | any                                   | nothing          |
-* | on                   | EDGE has plaintext access (all today) | metadata+content |
-* | on                   | E2E-encrypted (future)                | metadata only    |
-* | on                   | not declared by the call site         | metadata only    |
-*
-* Metadata is model, provider, tokens, latency, and trace/session ids. Content adds the prompt,
-* the response, and tool names — including tool results, i.e. data the agent read from the space.
-* The rationale: content that already leaves the device in plaintext for EDGE to replicate is not
-* newly exposed in kind by telemetry, whereas an E2E space promises that plaintext never reaches
-* infrastructure, and telemetry must not become the side channel that breaks it.
-*
-* The last row is the fail-closed default. A space id reaches the span only from a call site that
-* declares one (`AiSession` does; the utility model calls behind summarization, tagging, and
-* extraction do not), so content capture is opt-in per call site and an undeclared one reports
-* metadata only. That is what keeps this predicate honest once it stops returning true: it can
-* never be asked about a space nobody named.
-*
-* Both this predicate and the telemetry opt-in are evaluated in the sink, not at the model call, so
-* they apply to every event on the way out (see `AiSpanProcessor` in `@dxos/observability`, which
-* also holds the scrub rules).
-*/
-var contentCaptureAllowed = (_spaceId) => {
-	return true;
-};
-/** The span `effect/ai` names for a streamed call; anything else is a single response. */
-var STREAM_SPAN_NAME = "LanguageModel.streamText";
-/** Marker attributes identifying a GenAI span (per OTel GenAI semantic conventions). */
-var GEN_AI_MARKERS = [
-	"gen_ai.system",
-	"gen_ai.request.model",
-	"gen_ai.response.model"
-];
-/**
-* Session/content attributes stamped by `AiTelemetry.ATTRIBUTES` in `@dxos/ai` (not part of the
-* GenAI spec). Restated rather than imported because telemetry sits below the AI stack, not above
-* it; the `wired to @dxos/ai` cases in `AiObservability.test.ts` drive both halves so a rename fails there.
-*/
-var SESSION_ID_ATTR = SpanAttributes.AI.sessionId;
-/**
-* Shared with the process handle and ECHO rather than AI-specific: a model call inside a
-* space-scoped process carries it whether or not the call site named its space itself.
-*/
-var SPACE_ID_ATTR = SpanAttributes.SPACE_ID;
-var INPUT_ATTR = SpanAttributes.AI.input;
-var OUTPUT_ATTR = SpanAttributes.AI.output;
-var TOOLS_ATTR = SpanAttributes.AI.tools;
-var TRUNCATED_ATTR = SpanAttributes.AI.truncated;
-var CACHE_READ_TOKENS_ATTR = SpanAttributes.AI.cacheReadTokens;
-var CACHE_WRITE_TOKENS_ATTR = SpanAttributes.AI.cacheWriteTokens;
-/** What a non-model span is (`AiTelemetry.KIND`); a span with neither value is not AI at all. */
-var KIND_ATTR = SpanAttributes.AI.kind;
-var KIND_TURN = SpanAttributes.AI_KIND.turn;
-var KIND_TOOL = SpanAttributes.AI_KIND.tool;
-/** Display name for a span whose OTel name is generic, e.g. the tool a `callTool` span ran. */
-var NAME_ATTR = SpanAttributes.AI.name;
-/**
-* Reports finished AI spans to the injected sinks: model calls (`gen_ai.*`) as inferences, and the
-* turn and tool-call spans the AI stack marks with `dxos.ai.kind`. Every other span passes through
-* untouched.
-*
-* Attaches to the realm's tracer provider via `Otel.addSpanProcessor` rather than owning one: the
-* process manager's baseline tracer already records every span, so a second provider would mean a
-* second sampler and a second tracer over the same spans.
-*/
-var AiSpanProcessor = class {
-	_captureInference;
-	_captureTurn;
-	_captureToolCall;
-	_captureEnabled;
-	_allowContent;
-	constructor({ captureInference, captureTurn, captureToolCall, captureEnabled, allowContent }) {
-		this._captureInference = captureInference;
-		this._captureTurn = captureTurn;
-		this._captureToolCall = captureToolCall;
-		this._captureEnabled = captureEnabled;
-		this._allowContent = allowContent;
-	}
-	onStart(_span, _parentContext) {}
-	onEnd(span) {
-		try {
-			this._capture(span);
-		} catch (err) {
-			log.catch(err, { span: span.name }, {
-				"~LogMeta": "~LogMeta",
-				F: __dxlog_file,
-				L: 168,
-				S: this
-			});
-		}
-	}
-	_capture(span) {
-		const attributes = span.attributes;
-		const kind = attributes[KIND_ATTR];
-		const isModelCall = GEN_AI_MARKERS.some((key) => attributes[key] !== void 0);
-		if (kind !== KIND_TURN && kind !== KIND_TOOL && !isModelCall) return;
-		if (!this._captureEnabled()) return;
-		const spaceId = attributes[SPACE_ID_ATTR];
-		const content = typeof spaceId === "string" && this._allowContent(spaceId);
-		if (kind === KIND_TURN || kind === KIND_TOOL) {
-			const spanContext = span.spanContext();
-			const record = {
-				traceId: spanContext.traceId,
-				spanId: spanContext.spanId,
-				parentSpanId: span.parentSpanContext?.spanId,
-				spanName: stringAttribute(attributes[NAME_ATTR]) ?? span.name,
-				sessionId: stringAttribute(attributes[SESSION_ID_ATTR]),
-				latency: hrTimeToSeconds(span.duration),
-				content: content ? {
-					input: parseJsonOrRaw(attributes[INPUT_ATTR]),
-					output: parseJsonOrRaw(attributes[OUTPUT_ATTR]),
-					truncated: attributes[TRUNCATED_ATTR] === true ? true : void 0
-				} : void 0,
-				errorClass: span.status.code === SpanStatusCode.ERROR ? errorClass(span) : void 0
-			};
-			if (kind === KIND_TURN) this._captureTurn(record);
-			else this._captureToolCall(record);
-			return;
-		}
-		const spanContext = span.spanContext();
-		const inference = {
-			traceId: spanContext.traceId,
-			spanId: spanContext.spanId,
-			parentSpanId: span.parentSpanContext?.spanId,
-			spanName: span.name,
-			provider: stringAttribute(attributes["gen_ai.system"]),
-			model: stringAttribute(attributes["gen_ai.response.model"] ?? attributes["gen_ai.request.model"]),
-			sessionId: stringAttribute(attributes[SESSION_ID_ATTR]),
-			parameters: modelParameters(attributes),
-			inputTokens: numberAttribute(attributes["gen_ai.usage.input_tokens"]),
-			outputTokens: numberAttribute(attributes["gen_ai.usage.output_tokens"]),
-			cacheReadTokens: numberAttribute(attributes[CACHE_READ_TOKENS_ATTR]),
-			cacheWriteTokens: numberAttribute(attributes[CACHE_WRITE_TOKENS_ATTR]),
-			latency: hrTimeToSeconds(span.duration),
-			streaming: span.name === STREAM_SPAN_NAME,
-			content: content ? {
-				input: parseJsonOrRaw(attributes[INPUT_ATTR]),
-				output: parseJsonOrRaw(attributes[OUTPUT_ATTR]),
-				tools: parseJsonOrRaw(attributes[TOOLS_ATTR]),
-				truncated: attributes[TRUNCATED_ATTR] === true ? true : void 0
-			} : void 0,
-			errorClass: span.status.code === SpanStatusCode.ERROR ? errorClass(span) : void 0
-		};
-		this._captureInference(inference);
-	}
-	forceFlush() {
-		return Promise.resolve();
-	}
-	shutdown() {
-		return Promise.resolve();
-	}
-};
-var hrTimeToSeconds = ([seconds, nanos]) => seconds + nanos / 1e9;
-var stringAttribute = (value) => typeof value === "string" ? value : void 0;
-var numberAttribute = (value) => typeof value === "number" ? value : void 0;
-var modelParameters = (attributes) => {
-	const parameters = stripUndefined({
-		temperature: attributes["gen_ai.request.temperature"],
-		max_tokens: attributes["gen_ai.request.max_tokens"],
-		top_p: attributes["gen_ai.request.top_p"],
-		top_k: attributes["gen_ai.request.top_k"]
-	});
-	return Object.keys(parameters).length > 0 ? parameters : void 0;
-};
-var parseJsonOrRaw = (value) => {
-	if (typeof value !== "string") return;
-	try {
-		return JSON.parse(value);
-	} catch {
-		return value;
-	}
-};
-/** Only the exception class name — messages and stack traces can embed prompt/response content. */
-var errorClass = (span) => {
-	for (const event of span.events) {
-		const type = event.attributes?.["exception.type"];
-		if (typeof type === "string") return type;
-	}
-	return "Error";
-};
-var stripUndefined = (properties) => Object.fromEntries(Object.entries(properties).filter(([, value]) => value !== void 0));
-//#endregion
-export { AiSpanProcessor, contentCaptureAllowed, stripUndefined, AiObservability_exports as t };
-
-//# sourceMappingURL=AiObservability.mjs.map
+export { n as AiSpanProcessor, r as contentCaptureAllowed, i as stripUndefined } from "../chunk-AiObservability.mjs";