@warlock.js/ai-panoptic 4.3.0

package/cjs/index.cjs

@@ -0,0 +1,1370 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _warlock_js_ai = require("@warlock.js/ai");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+
+//#region ../@warlock.js/ai-panoptic/src/exporters/utils/walk-spans.ts
+/**
+* Depth-first pre-order traversal of a {@link TraceSpan} tree, yielding
+* the root first and then each descendant in `children` (invocation)
+* order. Exporters that emit a flat span stream — OpenTelemetry, the
+* console table — walk the tree once with this instead of re-writing the
+* recursion in every exporter.
+*
+* @example
+* for (const span of walkSpans(trace.root)) {
+*   emit(span);
+* }
+*/
+function* walkSpans(root) {
+	yield root;
+	for (const child of root.children) yield* walkSpans(child);
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/collector/normalize-error.ts
+/**
+* Project a captured execution error onto the structural
+* {@link TraceSpanError} shape used on a failed / cancelled span.
+*
+* Source errors are typically `AIError` instances (every error surfaced
+* by `@warlock.js/ai` is one), but the collector never depends on the
+* concrete class — it reads only the structural surface (`name` / `code`
+* / `message` / `stack`) so a plain `Error`, an `AIError`, or any
+* thrown value all normalize identically. The result is a JSON-safe
+* plain object so it survives serialization to a backend collector
+* unchanged.
+*
+* The error `type` prefers the stable `code` (e.g. `"RATE_LIMIT"`) over
+* the class `name`, falling back to `name` and finally to the generic
+* `"Error"` so the field is always populated.
+*
+* @example
+* const spanError = normalizeError(report.error);
+* // { type: "RATE_LIMIT", message: "429 Too Many Requests", stack: "..." }
+*/
+function normalizeError(error) {
+	if (error === void 0 || error === null) return;
+	if (typeof error !== "object") return {
+		type: "Error",
+		message: String(error)
+	};
+	const candidate = error;
+	const type = pickString(candidate.code) ?? pickString(candidate.name) ?? "Error";
+	const message = pickString(candidate.message) ?? "";
+	const stack = pickString(candidate.stack);
+	const normalized = {
+		type,
+		message
+	};
+	if (stack !== void 0) normalized.stack = stack;
+	return normalized;
+}
+/**
+* Return the value when it is a non-empty string, otherwise `undefined`.
+* Keeps `normalizeError` from promoting empty / non-string fields.
+*/
+function pickString(value) {
+	if (typeof value === "string" && value.length > 0) return value;
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/collector/extract-span-attributes.ts
+/**
+* Build the free-form `TraceSpan.attributes` bag for one report node.
+*
+* The collector keeps the first-class span fields (identity, timing,
+* status, usage, error) on the span itself and routes everything
+* primitive-specific here — trip/step/iteration counts, the model
+* identity an agent ran against, the tool's originating trip index, a
+* supervisor's termination reason. Exporters forward this verbatim as
+* backend span attributes (OTel attributes, Langfuse metadata).
+*
+* Only populated keys are emitted; the function returns `undefined`
+* when the node carried no extra detail, so the optional
+* `TraceSpan.attributes` field stays absent rather than holding an
+* empty object (matches the contract's "absent when empty" note).
+*
+* Retry count is surfaced from the shared `BaseReport.attempts` for
+* every primitive so cost dashboards see the real call count.
+*
+* @example
+* const attributes = extractSpanAttributes(agentReport);
+* // { "agent.trips": 3, "agent.model.name": "gpt-4o", "agent.model.provider": "openai" }
+*/
+function extractSpanAttributes(report) {
+	const extensions = report;
+	const attributes = {};
+	if (report.attempts !== void 0 && report.attempts.length > 0) attributes["retries"] = report.attempts.length;
+	switch (report.type) {
+		case "agent":
+			addAgentAttributes(attributes, extensions);
+			break;
+		case "workflow":
+			addWorkflowAttributes(attributes, extensions);
+			break;
+		case "supervisor":
+			addSupervisorAttributes(attributes, extensions);
+			break;
+		case "orchestrator":
+			addOrchestratorAttributes(attributes, extensions);
+			break;
+		case "tool":
+			addToolAttributes(attributes, extensions);
+			break;
+		default: break;
+	}
+	if (Object.keys(attributes).length === 0) return;
+	return attributes;
+}
+function addAgentAttributes(attributes, extensions) {
+	if (Array.isArray(extensions.trips)) attributes["agent.trips"] = extensions.trips.length;
+	if (extensions.model?.name !== void 0) attributes["agent.model.name"] = extensions.model.name;
+	if (extensions.model?.provider !== void 0) attributes["agent.model.provider"] = extensions.model.provider;
+}
+function addWorkflowAttributes(attributes, extensions) {
+	if (extensions.workflowName !== void 0) attributes["workflow.name"] = extensions.workflowName;
+	if (extensions.signature !== void 0) attributes["workflow.signature"] = extensions.signature;
+	if (extensions.steps !== void 0) attributes["workflow.steps"] = Object.keys(extensions.steps).length;
+}
+function addSupervisorAttributes(attributes, extensions) {
+	if (extensions.supervisorName !== void 0) attributes["supervisor.name"] = extensions.supervisorName;
+	if (extensions.terminatedBy !== void 0) attributes["supervisor.terminatedBy"] = extensions.terminatedBy;
+	if (extensions.iterations !== void 0) attributes["supervisor.iterations"] = extensions.iterations;
+}
+function addOrchestratorAttributes(attributes, extensions) {
+	if (extensions.turnIndex !== void 0) attributes["orchestrator.turnIndex"] = extensions.turnIndex;
+	if (extensions.signature !== void 0) attributes["orchestrator.signature"] = extensions.signature;
+	if (Array.isArray(extensions.turns)) attributes["orchestrator.turns"] = extensions.turns.length;
+}
+function addToolAttributes(attributes, extensions) {
+	if (extensions.tripIndex !== void 0) attributes["tool.tripIndex"] = extensions.tripIndex;
+	if (extensions.recoveredFrom !== void 0) attributes["tool.recoveredFrom"] = extensions.recoveredFrom;
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/collector/report-to-span.ts
+/**
+* Project one {@link BaseReport} node — and its entire subtree — into a
+* {@link TraceSpan}. Pure and recursive: identity, timing, status, and
+* the rolled-up `usage` map across 1:1 from the report; lineage maps
+* `runId → spanId`, `parentRunId → parentSpanId`, `rootRunId → traceId`;
+* children recurse in invocation order so the span tree mirrors the
+* report tree exactly.
+*
+* The error is normalized to the JSON-safe {@link
+* import("../contracts/trace.type").TraceSpanError} shape only when the
+* node carried one (failed / cancelled). Primitive-specific detail that
+* has no first-class span field (trip / step / iteration counts, model
+* identity, tool trip index) is routed into the optional `attributes`
+* bag via {@link extractSpanAttributes}.
+*
+* No external lookup is needed — a `BaseReport` already carries
+* everything a span requires, so a collector can flatten a tree without
+* consulting any other source.
+*
+* @example
+* const root = reportToSpan(result.report);
+* console.log(root.spanId, root.traceId, root.children.length);
+*/
+function reportToSpan(report) {
+	const span = {
+		spanId: report.runId,
+		traceId: report.rootRunId,
+		name: report.name,
+		type: report.type,
+		status: report.status,
+		startedAt: report.startedAt,
+		endedAt: report.endedAt,
+		duration: report.duration,
+		usage: report.usage,
+		children: report.children.map(reportToSpan)
+	};
+	if (report.parentRunId !== void 0) span.parentSpanId = report.parentRunId;
+	if (report.sessionId !== void 0) span.sessionId = report.sessionId;
+	if (report.version !== void 0) span.version = report.version;
+	const error = normalizeError(report.error);
+	if (error !== void 0) span.error = error;
+	const attributes = extractSpanAttributes(report);
+	if (attributes !== void 0) span.attributes = attributes;
+	return span;
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/collector/report-to-trace.ts
+/**
+* Project an outermost {@link BaseReport} (one whole `.execute()` /
+* `.invoke()` run) into a {@link Trace} — the root {@link
+* import("../contracts/trace.type").TraceSpan} plus the trace-wide
+* rollups exporters need without re-walking the tree.
+*
+* The trace-level identity and rollups all read off the root span the
+* projection already built (`traceId`, `usage`, timing), so the trace
+* envelope never disagrees with its own root. `reportSchemaVersion` is
+* mirrored from the root report when present (it is stamped only on
+* root nodes upstream) so exporters can branch on the source shape.
+*
+* Pure — the same input always yields the same trace. The collector
+* exposes this as `toTrace` so callers can inspect the normalized shape
+* without dispatching to exporters.
+*
+* The optional `rootError` threads the failing run's envelope error
+* (`BaseResult.error`) onto the root span. The error lives on the result
+* envelope, never on the `BaseReport` tree, so without this a failed root
+* would export `status` with no error type/message. Applied only when the
+* root span carries none of its own; the subtree projection stays pure
+* (each child surfaces its own report-level error, if any).
+*
+* @example
+* const trace = reportToTrace(result.report, result.error);
+* console.log(trace.traceId, trace.usage.total, trace.duration);
+*/
+function reportToTrace(report, rootError) {
+	const root = reportToSpan(report);
+	if (root.error === void 0) {
+		const error = normalizeError(rootError);
+		if (error !== void 0) root.error = error;
+	}
+	const trace = {
+		traceId: root.traceId,
+		root,
+		startedAt: root.startedAt,
+		endedAt: root.endedAt,
+		duration: root.duration,
+		usage: root.usage
+	};
+	if (root.sessionId !== void 0) trace.sessionId = root.sessionId;
+	if (report.reportSchemaVersion !== void 0) trace.reportSchemaVersion = report.reportSchemaVersion;
+	return trace;
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/collector/collector.ts
+/**
+* Drive the source end of the Panoptic pipeline: ingest core
+* `@warlock.js/ai` {@link BaseReport} trees, project them into {@link
+* Trace}s, and fan each trace out to every registered exporter.
+*
+* Owns exporter registration (deduped by `ExporterContract.name`), the
+* report→trace projection, and graceful shutdown so exporters drain
+* before exit. Instantiated fresh per collector via {@link
+* createCollector}; callers never see `new`.
+*
+* **Failure isolation.** An exporter that throws never propagates back
+* into the originating run — `collect`, `flush`, and `shutdown` settle
+* every exporter independently (mirrors how the core event hooks
+* swallow consumer errors). One broken exporter can neither crash the
+* agent loop nor stop sibling exporters from receiving the trace.
+*/
+var Collector = class {
+	constructor() {
+		this.exporters = /* @__PURE__ */ new Map();
+	}
+	use(exporter) {
+		if (!this.exporters.has(exporter.name)) this.exporters.set(exporter.name, exporter);
+		return this;
+	}
+	toTrace(report, rootError) {
+		return reportToTrace(report, rootError);
+	}
+	async collect(report, rootError) {
+		const trace = this.toTrace(report, rootError);
+		await this.dispatch(trace);
+	}
+	async flush() {
+		await this.settleAll((exporter) => exporter.flush?.());
+	}
+	async shutdown() {
+		await this.flush();
+		await this.settleAll((exporter) => exporter.shutdown?.());
+		this.exporters.clear();
+	}
+	/**
+	* Fan one trace out to every exporter and, when an exporter advertises
+	* the per-span hook, deliver every span in the finalized tree to it as
+	* well. `exportSpan` is a post-completion per-span hook (not a live /
+	* streaming feed — the trace is already finalized): we walk the tree in
+	* pre-order with {@link walkSpans} so the exporter sees the root and
+	* every descendant exactly once. Every invocation is isolated so a
+	* throwing exporter can't abort the dispatch to its siblings or escape
+	* into the originating run.
+	*/
+	async dispatch(trace) {
+		await this.settleAll(async (exporter) => {
+			await exporter.export(trace);
+			if (exporter.exportSpan !== void 0) for (const span of walkSpans(trace.root)) await exporter.exportSpan(span);
+		});
+	}
+	/**
+	* Run `task` against every registered exporter and wait for all of
+	* them to settle, swallowing individual rejections. `Promise.allSettled`
+	* guarantees one failure neither rejects the batch nor blocks the
+	* others — the contract's failure-isolation requirement.
+	*/
+	async settleAll(task) {
+		const runs = [...this.exporters.values()].map((exporter) => Promise.resolve().then(() => task(exporter)));
+		await Promise.allSettled(runs);
+	}
+};
+/**
+* Create a Panoptic collector — the single integration point an app
+* wires into its agents/workflows (typically via the `onComplete`
+* report hook). Register exporters with `use`, then feed finalized root
+* reports to `collect`.
+*
+* @example
+* const collector = createCollector().use(otelExporter).use(langfuseExporter);
+* agent.on("onComplete", ({ result }) => collector.collect(result.report));
+* // on shutdown:
+* await collector.shutdown();
+*/
+function createCollector() {
+	return new Collector();
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/store/match-trace.ts
+/**
+* Test whether one trace satisfies a {@link TraceQuery}. Every declared
+* filter field must match (logical AND); absent fields are ignored, so
+* an empty / undefined filter matches every trace.
+*
+* Time bounds compare against the trace's root `startedAt`, parsed to
+* an epoch once per call, inclusive on both ends. Status accepts a
+* single value or an array (membership test). Identity fields are exact
+* string equality.
+*
+* Pure — used by the store's `query` and `aggregate` so both share one
+* matching definition.
+*/
+function matchTrace(trace, filter) {
+	if (!filter) return true;
+	if (filter.traceId !== void 0 && trace.traceId !== filter.traceId) return false;
+	if (filter.sessionId !== void 0 && trace.sessionId !== filter.sessionId) return false;
+	if (filter.status !== void 0 && !statusMatches(trace.root.status, filter.status)) return false;
+	const startedAt = Date.parse(trace.startedAt);
+	if (filter.startedAfter !== void 0 && startedAt < toEpoch(filter.startedAfter)) return false;
+	if (filter.startedBefore !== void 0 && startedAt > toEpoch(filter.startedBefore)) return false;
+	return true;
+}
+/**
+* Membership test for the status filter — true when `status` equals the
+* single wanted value, or is one of the wanted array.
+*/
+function statusMatches(status, wanted) {
+	if (Array.isArray(wanted)) return wanted.includes(status);
+	return status === wanted;
+}
+/**
+* Normalize a time bound (ISO string or `Date`) to epoch milliseconds
+* for comparison against a parsed `startedAt`.
+*/
+function toEpoch(bound) {
+	if (bound instanceof Date) return bound.getTime();
+	return Date.parse(bound);
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/store/sum-usage.ts
+/**
+* Fold a child {@link Usage} into a running accumulator. Token channels
+* (`input` / `output` / `total`) always sum; the optional cache /
+* reasoning channels (`cachedTokens` / `cacheWriteTokens` /
+* `reasoningTokens`) sum only when at least one side reported them, so
+* a provider that never meters a channel doesn't fabricate a `0` for
+* it. The `cost` breakdown is merged with the core framework's
+* {@link accumulateCost}, keeping cost-rollup semantics identical to a
+* native report tree — an unpriced contributor never erases a priced
+* one.
+*
+* Pure: returns a fresh `Usage`, never mutates either argument. Seed an
+* aggregation with {@link emptyUsage}.
+*
+* @example
+* let total = emptyUsage();
+* for (const trace of traces) {
+*   total = sumUsage(total, trace.usage);
+* }
+*/
+function sumUsage(accumulator, next) {
+	const merged = {
+		input: accumulator.input + next.input,
+		output: accumulator.output + next.output,
+		total: accumulator.total + next.total
+	};
+	const cachedTokens = sumOptional(accumulator.cachedTokens, next.cachedTokens);
+	if (cachedTokens !== void 0) merged.cachedTokens = cachedTokens;
+	const cacheWriteTokens = sumOptional(accumulator.cacheWriteTokens, next.cacheWriteTokens);
+	if (cacheWriteTokens !== void 0) merged.cacheWriteTokens = cacheWriteTokens;
+	const reasoningTokens = sumOptional(accumulator.reasoningTokens, next.reasoningTokens);
+	if (reasoningTokens !== void 0) merged.reasoningTokens = reasoningTokens;
+	const cost = (0, _warlock_js_ai.accumulateCost)(accumulator.cost, next.cost);
+	if (cost !== void 0) merged.cost = cost;
+	return merged;
+}
+/**
+* A zero-valued {@link Usage} to seed an aggregation. Only the required
+* token channels are set; optional channels stay absent until a
+* contributor reports them, preserving the "never reported" vs
+* "reported as 0" distinction.
+*/
+function emptyUsage() {
+	return {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+}
+/**
+* Add two optional token counts, treating either side's `undefined` as
+* zero — but return `undefined` when both are absent, so an unreported
+* channel stays unreported rather than collapsing to `0`.
+*/
+function sumOptional(accumulator, next) {
+	if (accumulator === void 0 && next === void 0) return;
+	return (accumulator ?? 0) + (next ?? 0);
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/store/in-memory-trace-store.ts
+/**
+* In-memory {@link TraceStoreContract} that doubles as an
+* {@link ExporterContract} — register it on a collector
+* (`collector.use(store)`) and it fills as traces complete, then query
+* or aggregate it after the fact.
+*
+* Backed by an insertion-ordered `Map` keyed by `traceId`, giving O(1)
+* `get` / `add` / overwrite and O(n) scans for `query` / `aggregate`
+* (the price of an in-memory store with no secondary indexes — fine for
+* the dev/test and modest-volume runtime use this targets). When a
+* `capacity` is configured, ingesting past the cap evicts the oldest
+* trace.
+*
+* Instantiated fresh per store via {@link createInMemoryTraceStore};
+* callers never see `new`.
+*/
+var InMemoryTraceStore = class {
+	constructor(options) {
+		this.name = "in-memory-trace-store";
+		this.traces = /* @__PURE__ */ new Map();
+		this.capacity = options?.capacity ?? 0;
+	}
+	get size() {
+		return this.traces.size;
+	}
+	add(trace) {
+		this.traces.delete(trace.traceId);
+		this.traces.set(trace.traceId, trace);
+		this.evictOverflow();
+	}
+	/**
+	* `ExporterContract.export` — a collector dispatches a completed
+	* trace here, which is exactly an `add`. Lets the store be wired into
+	* a collector as a sink without an adapter.
+	*/
+	export(trace) {
+		this.add(trace);
+	}
+	get(traceId) {
+		return this.traces.get(traceId);
+	}
+	query(filter) {
+		const matched = [];
+		for (const trace of this.traces.values()) if (matchTrace(trace, filter)) matched.push(trace);
+		return this.sortNewestFirst(matched);
+	}
+	aggregate(filter) {
+		const aggregate = {
+			traces: 0,
+			completed: 0,
+			failed: 0,
+			cancelled: 0,
+			usage: emptyUsage(),
+			totalDuration: 0
+		};
+		for (const trace of this.traces.values()) {
+			if (!matchTrace(trace, filter)) continue;
+			aggregate.traces += 1;
+			aggregate.totalDuration += trace.duration;
+			aggregate.usage = sumUsage(aggregate.usage, trace.usage);
+			this.countStatus(aggregate, trace);
+		}
+		if (aggregate.usage.cost !== void 0) aggregate.cost = aggregate.usage.cost;
+		return aggregate;
+	}
+	clear() {
+		this.traces.clear();
+	}
+	/**
+	* Increment the matching terminal-status counter for one trace.
+	* Non-terminal statuses (`awaiting-input`, `max-iterations`) are
+	* counted in `traces` but tracked by none of the three headline
+	* counters — intentional, those three answer the common
+	* "succeeded / errored / aborted" question.
+	*/
+	countStatus(aggregate, trace) {
+		switch (trace.root.status) {
+			case "completed":
+				aggregate.completed += 1;
+				break;
+			case "failed":
+				aggregate.failed += 1;
+				break;
+			case "cancelled":
+				aggregate.cancelled += 1;
+				break;
+			default: break;
+		}
+	}
+	/**
+	* Sort matched traces newest-started first. A copy is sorted so the
+	* underlying insertion order (which eviction depends on) is never
+	* disturbed.
+	*/
+	sortNewestFirst(traces) {
+		return traces.sort((left, right) => Date.parse(right.startedAt) - Date.parse(left.startedAt));
+	}
+	/**
+	* Evict oldest-inserted traces until the store is within `capacity`.
+	* No-op when unbounded. The `Map` iterator yields keys in insertion
+	* order, so the first key is always the oldest.
+	*/
+	evictOverflow() {
+		if (this.capacity <= 0) return;
+		while (this.traces.size > this.capacity) {
+			const oldest = this.traces.keys().next().value;
+			if (oldest === void 0) return;
+			this.traces.delete(oldest);
+		}
+	}
+};
+/**
+* Create an in-memory trace store. Optionally bound it with `capacity`
+* for long-lived processes; leave it unset for dev/test where you want
+* every trace retained.
+*
+* @example
+* const store = createInMemoryTraceStore({ capacity: 1000 });
+* collector.use(store);
+* // later:
+* const recentFailures = store.query({ status: "failed" });
+* const sessionSpend = store.aggregate({ sessionId });
+*/
+function createInMemoryTraceStore(options) {
+	return new InMemoryTraceStore(options);
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/exporters/utils/total-cost.ts
+/**
+* Collapse a {@link Usage.cost} breakdown into a single USD scalar by
+* summing every populated field. Mirrors the formula documented on
+* `Usage.cost` (input + output + cachedInput + cachedOutput), and also
+* folds in `reasoning` for forward-safety when a provider prices
+* reasoning tokens as a separate channel. Returns `undefined` when no
+* pricing was attached, so exporters can omit the cost attribute
+* entirely rather than reporting a misleading `0`.
+*
+* @example
+* totalCostUsd({ input: 1, output: 2, total: 3, cost: { input: 0.01, output: 0.04 } });
+* // => 0.05
+*/
+function totalCostUsd(usage) {
+	const cost = usage.cost;
+	if (!cost) return;
+	return (cost.input ?? 0) + (cost.output ?? 0) + (cost.cachedInput ?? 0) + (cost.cachedOutput ?? 0) + (cost.reasoning ?? 0);
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/exporters/utils/gen-ai-attributes.ts
+/**
+* Subset of the OpenTelemetry GenAI semantic-convention attribute keys
+* Panoptic emits. Kept as a named constant map (not inline string
+* literals scattered through the mapper) so the convention names live in
+* one place and a convention bump is a single edit.
+*
+* @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+*/
+const GEN_AI_ATTRIBUTES = {
+	operationName: "gen_ai.operation.name",
+	system: "gen_ai.system",
+	requestModel: "gen_ai.request.model",
+	responseModel: "gen_ai.response.model",
+	usageInputTokens: "gen_ai.usage.input_tokens",
+	usageOutputTokens: "gen_ai.usage.output_tokens",
+	conversationId: "gen_ai.conversation.id"
+};
+/**
+* Panoptic-specific attribute keys that have no GenAI-convention
+* equivalent. Namespaced under `warlock.*` so they never collide with a
+* future `gen_ai.*` key the spec might add.
+*/
+const WARLOCK_ATTRIBUTES = {
+	reportType: "warlock.report.type",
+	version: "warlock.version",
+	durationMs: "warlock.duration_ms",
+	totalTokens: "gen_ai.usage.total_tokens",
+	cachedTokens: "gen_ai.usage.cached_tokens",
+	reasoningTokens: "gen_ai.usage.reasoning_tokens",
+	costUsd: "warlock.cost.usd"
+};
+/**
+* Project a {@link TraceSpan} onto the OpenTelemetry GenAI
+* semantic-convention attribute set.
+*
+* The vendor-neutral {@link TraceSpan} carries identity, timing, status,
+* and rolled-up `usage` as first-class fields; model identity and other
+* provider detail live in the free-form `attributes` bag the collector
+* populated. This mapper folds both into a flat `gen_ai.*` /
+* `warlock.*` attribute map ready to set on an OTel span or hand to a
+* Langfuse generation.
+*
+* - `gen_ai.operation.name` / `gen_ai.system` / `gen_ai.request.model`
+*   are forwarded from the span's `attributes` when the collector set
+*   them; never invented here.
+* - Token counts come from the span's typed `usage` rollup.
+* - The free-form `attributes` are merged last so an explicit collector
+*   value wins over a derived one.
+*
+* @example
+* const attributes = toGenAiAttributes(span);
+* // { "gen_ai.usage.input_tokens": 150, "gen_ai.usage.output_tokens": 320, ... }
+*/
+function toGenAiAttributes(span) {
+	const attributes = {
+		[WARLOCK_ATTRIBUTES.reportType]: span.type,
+		[WARLOCK_ATTRIBUTES.durationMs]: span.duration,
+		[WARLOCK_ATTRIBUTES.totalTokens]: span.usage.total,
+		[GEN_AI_ATTRIBUTES.usageInputTokens]: span.usage.input,
+		[GEN_AI_ATTRIBUTES.usageOutputTokens]: span.usage.output
+	};
+	if (span.version !== void 0) attributes[WARLOCK_ATTRIBUTES.version] = span.version;
+	if (span.sessionId !== void 0) attributes[GEN_AI_ATTRIBUTES.conversationId] = span.sessionId;
+	if (span.usage.cachedTokens !== void 0) attributes[WARLOCK_ATTRIBUTES.cachedTokens] = span.usage.cachedTokens;
+	if (span.usage.reasoningTokens !== void 0) attributes[WARLOCK_ATTRIBUTES.reasoningTokens] = span.usage.reasoningTokens;
+	const cost = totalCostUsd(span.usage);
+	if (cost !== void 0) attributes[WARLOCK_ATTRIBUTES.costUsd] = cost;
+	mergeScalarAttributes(attributes, span.attributes);
+	return attributes;
+}
+/**
+* Copy the scalar entries of a free-form attribute bag onto the target
+* map. Non-scalar values (objects, arrays, functions) are skipped — OTel
+* and Langfuse attribute values must be primitives, and the collector's
+* bag may legitimately hold nested digests that don't belong on a span
+* attribute. Explicit collector values overwrite derived ones.
+*/
+function mergeScalarAttributes(target, source) {
+	if (!source) return;
+	for (const [key, value] of Object.entries(source)) if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") target[key] = value;
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/exporters/console/format-span-line.ts
+/**
+* Render a single {@link TraceSpan} as one scannable console line:
+* `<status> <type> "<name>" — <duration>ms, <tokens> tok[, $<cost>]`.
+* `depth` controls leading indentation when printing a tree. Pure — no
+* side effects — so it is trivially testable and reused by both the
+* per-trace summary and the per-span streaming line.
+*
+* @example
+* formatSpanLine(span, 1);
+* // '  ok agent "router" — 1240ms, 470 tok, $0.0021'
+*/
+function formatSpanLine(span, depth = 0) {
+	const indent = "  ".repeat(depth);
+	const marker = statusMarker(span.status);
+	const cost = totalCostUsd(span.usage);
+	const costSuffix = cost === void 0 ? "" : `, $${cost.toFixed(4)}`;
+	let line = `${indent}${marker} ${span.type} "${span.name}" — ${span.duration}ms, ${span.usage.total} tok${costSuffix}`;
+	if (span.error) line += ` [${span.error.type}: ${span.error.message}]`;
+	return line;
+}
+/**
+* Short ASCII marker for a span's terminal status. Plain ASCII (no
+* emoji/color codes) so output stays clean in log aggregators and CI.
+*/
+function statusMarker(status) {
+	switch (status) {
+		case "completed": return "ok";
+		case "failed": return "ERR";
+		case "cancelled": return "cancel";
+		case "max-iterations": return "max-iter";
+		case "awaiting-input": return "await";
+		default: return status;
+	}
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/exporters/console/console-exporter.ts
+const EXPORTER_NAME$3 = "console";
+/**
+* Zero-dependency {@link ExporterContract} that prints traces to a
+* console-like sink. The simplest exporter — useful in development and
+* as the reference implementation of the contract.
+*
+* By default it prints one summary line per completed trace. Set
+* `tree: true` to print the full indented span tree, and
+* `streaming: true` to also print each span the moment it finalizes
+* (via the optional `exportSpan` hook).
+*
+* @example
+* collector.use(consoleExporter());
+* // ok workflow "checkout" — 2103ms, 1820 tok, $0.0094
+*
+* @example
+* collector.use(consoleExporter({ tree: true }));
+*/
+function consoleExporter(options = {}) {
+	const sink = options.console ?? console;
+	const tree = options.tree ?? false;
+	const exporter = {
+		name: EXPORTER_NAME$3,
+		export(trace) {
+			writeTrace(sink, trace, tree);
+		}
+	};
+	if (options.streaming) exporter.exportSpan = (span) => {
+		sink.log(formatSpanLine(span));
+	};
+	return exporter;
+}
+/**
+* Write a completed trace — either a single root summary line or the
+* full indented tree. Failed traces are routed to `console.error` so
+* they surface at the right severity in log aggregators.
+*/
+function writeTrace(sink, trace, tree) {
+	if (!tree) {
+		const line = formatSpanLine(trace.root);
+		writeAtSeverity(sink, trace.root.status, line);
+		return;
+	}
+	for (const span of walkSpans(trace.root)) {
+		const line = formatSpanLine(span, spanDepth(trace.root, span.spanId));
+		writeAtSeverity(sink, span.status, line);
+	}
+}
+/**
+* Route a line to `error` when the span failed/cancelled, otherwise to
+* `log`. Keeps healthy traces out of the error stream.
+*/
+function writeAtSeverity(sink, status, line) {
+	if (status === "failed" || status === "cancelled") {
+		sink.error(line);
+		return;
+	}
+	sink.log(line);
+}
+/**
+* Depth of `targetSpanId` below `root` for indentation. Walks the tree
+* once; returns 0 when the span is the root or not found.
+*/
+function spanDepth(root, targetSpanId, depth = 0) {
+	if (root.spanId === targetSpanId) return depth;
+	for (const child of root.children) {
+		const found = spanDepth(child, targetSpanId, depth + 1);
+		if (found > 0) return found;
+	}
+	return 0;
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/exporters/file/file-exporter.ts
+const EXPORTER_NAME$2 = "file";
+/**
+* Zero-dependency {@link ExporterContract} that appends completed traces
+* to a JSON-Lines file (one JSON record per line by default). Buffers in
+* memory and flushes either every `flushEvery` traces or on an explicit
+* `flush()` / `shutdown()`, so a batch of traces costs one append.
+*
+* Useful as a durable local sink (replay traces later, ship the file to
+* a backend out of band) and as a test fixture for the pipeline without
+* a vendor SDK.
+*
+* @example
+* collector.use(fileExporter({ path: "storage/traces.jsonl" }));
+* // on shutdown:
+* await collector.shutdown(); // drains the buffer
+*/
+function fileExporter(options) {
+	const writer = new FileTraceWriter(options);
+	return {
+		name: EXPORTER_NAME$2,
+		async export(trace) {
+			await writer.add(trace);
+		},
+		async flush() {
+			await writer.flush();
+		},
+		async shutdown() {
+			await writer.flush();
+		}
+	};
+}
+/**
+* Internal buffered writer for {@link fileExporter}. Owns the pending
+* trace buffer and the directory-created guard across the exporter's
+* lifetime; kept unexported so callers only ever see the factory.
+*/
+var FileTraceWriter = class {
+	constructor(options) {
+		this.buffer = [];
+		this.directoryReady = false;
+		this.path = options.path;
+		this.flushEvery = Math.max(1, options.flushEvery ?? 1);
+		this.pretty = options.pretty ?? false;
+	}
+	/**
+	* Buffer one trace and flush when the buffer reaches `flushEvery`.
+	*/
+	async add(trace) {
+		this.buffer.push({
+			type: "trace",
+			exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			trace
+		});
+		if (this.buffer.length >= this.flushEvery) await this.flush();
+	}
+	/**
+	* Serialize and append every buffered record, then clear the buffer.
+	* No-op when nothing is pending so callers can flush defensively.
+	*/
+	async flush() {
+		if (this.buffer.length === 0) return;
+		const pending = this.buffer;
+		this.buffer = [];
+		await this.ensureDirectory();
+		const payload = pending.map((record) => this.serialize(record)).join("");
+		await (0, node_fs_promises.appendFile)(this.path, payload, "utf8");
+	}
+	/**
+	* Create the parent directory once, lazily, on the first write. Stores
+	* a guard so subsequent flushes skip the syscall.
+	*/
+	async ensureDirectory() {
+		if (this.directoryReady) return;
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(this.path), { recursive: true });
+		this.directoryReady = true;
+	}
+	/**
+	* Render one record as a newline-terminated JSON string. Pretty mode
+	* indents for human reading; compact mode keeps the file valid JSON
+	* Lines (exactly one record per physical line).
+	*/
+	serialize(record) {
+		return `${this.pretty ? JSON.stringify(record, void 0, 2) : JSON.stringify(record)}\n`;
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/exporters/langfuse/langfuse-exporter.ts
+const EXPORTER_NAME$1 = "langfuse";
+let LangfuseSdk;
+let isModuleExists$1 = null;
+let loadingPromise$1;
+const LANGFUSE_INSTALL_INSTRUCTIONS = `
+The Panoptic Langfuse exporter requires the langfuse package.
+Install it with:
+
+  npm install langfuse
+
+Or with your preferred package manager:
+
+  pnpm add langfuse
+  yarn add langfuse
+`.trim();
+/**
+* Settle the lazy import of `langfuse` once, concurrency-safe. Only
+* needed when the caller did not pass a ready `client`. A bare `catch`
+* flips the flag to `false`; the curated install string surfaces at use
+* time, never a raw module-resolution stack trace.
+*/
+function loadLangfuse() {
+	if (isModuleExists$1 !== null) return Promise.resolve();
+	if (loadingPromise$1) return loadingPromise$1;
+	loadingPromise$1 = (async () => {
+		try {
+			LangfuseSdk = await import("langfuse");
+			isModuleExists$1 = true;
+		} catch {
+			isModuleExists$1 = false;
+		}
+	})();
+	return loadingPromise$1;
+}
+/**
+* {@link ExporterContract} that maps Panoptic traces onto Langfuse
+* traces and observations. Lazily imports `langfuse` so it stays an
+* OPTIONAL peer — importing this module never forces the SDK to be
+* installed, and a missing SDK surfaces as a curated "install this"
+* error when the exporter first needs to build a client.
+*
+* The root {@link TraceSpan} becomes a Langfuse trace; each descendant
+* becomes a nested observation — a `generation` when it produced tokens
+* (LLM-backed agents, supervisors), otherwise a plain `span` (tools,
+* callbacks). Timing, status, version, and rolled-up `usage` are mapped
+* 1:1; the rest of the GenAI attributes ride along as observation
+* metadata.
+*
+* @example
+* collector.use(langfuseExporter({ publicKey: "pk-...", secretKey: "sk-..." }));
+* // or reuse an existing client:
+* collector.use(langfuseExporter({ client: myLangfuse }));
+*/
+function langfuseExporter(options) {
+	let client = options.client;
+	if (!client) loadLangfuse();
+	const resolveClient = async () => {
+		if (client) return client;
+		await loadLangfuse();
+		if (!isModuleExists$1) throw new Error(LANGFUSE_INSTALL_INSTRUCTIONS);
+		client = new LangfuseSdk.Langfuse({
+			publicKey: options.publicKey,
+			secretKey: options.secretKey,
+			baseUrl: options.baseUrl
+		});
+		return client;
+	};
+	return {
+		name: EXPORTER_NAME$1,
+		async export(trace) {
+			emitTrace(await resolveClient(), trace);
+		},
+		async flush() {
+			if (!client) return;
+			await client.flushAsync();
+		},
+		async shutdown() {
+			if (!client) return;
+			await client.shutdownAsync();
+		}
+	};
+}
+/**
+* Create the Langfuse trace from the root span, then recurse the
+* children into nested observations.
+*/
+function emitTrace(client, trace) {
+	const root = trace.root;
+	const langfuseTrace = client.trace({
+		id: root.traceId,
+		name: root.name,
+		sessionId: trace.sessionId,
+		version: root.version,
+		timestamp: new Date(root.startedAt),
+		metadata: toGenAiAttributes(root)
+	});
+	for (const child of root.children) emitObservation(langfuseTrace, child);
+}
+/**
+* Map one {@link TraceSpan} onto a Langfuse observation under `parent`,
+* then recurse its children. Token-producing spans become
+* `generation`s; everything else becomes a plain `span`.
+*/
+function emitObservation(parent, span) {
+	const body = {
+		id: span.spanId,
+		name: span.name,
+		startTime: new Date(span.startedAt),
+		endTime: new Date(span.endedAt),
+		level: toLevel(span),
+		statusMessage: span.error?.message,
+		version: span.version,
+		metadata: toGenAiAttributes(span)
+	};
+	let observation;
+	if (producedTokens(span)) {
+		body.usage = {
+			input: span.usage.input,
+			output: span.usage.output,
+			total: span.usage.total,
+			unit: "TOKENS"
+		};
+		observation = parent.generation(body);
+	} else observation = parent.span(body);
+	for (const child of span.children) emitObservation(observation, child);
+	observation.end({ endTime: body.endTime });
+}
+/**
+* A span counts as an LLM `generation` when it metered any tokens. Pure
+* tools/callbacks contribute zero own-cost and map to plain spans.
+*
+* **Known limitation.** `TraceSpan.usage` is the ROLLED-UP usage (this
+* node's own cost plus the sum of its children), not own-usage — the
+* core `BaseReport` exposes no separate own-usage field, so a composite
+* node (e.g. an agent that itself made no model call but whose tool
+* children did) is classified as a `generation` on its children's
+* tokens. We cannot classify on own-usage until the report shape carries
+* it; the rolled-up `usage` block emitted on such a generation therefore
+* double-counts tokens already attributed to descendant observations.
+*/
+function producedTokens(span) {
+	return span.usage.total > 0;
+}
+/**
+* Map the Panoptic span status onto a Langfuse observation level —
+* failed/cancelled spans surface as `ERROR`, everything else `DEFAULT`.
+*/
+function toLevel(span) {
+	if (span.status === "failed" || span.status === "cancelled") return "ERROR";
+	return "DEFAULT";
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/exporters/otel/otel-exporter.ts
+const EXPORTER_NAME = "otel";
+const DEFAULT_TRACER_NAME = "@warlock.js/ai-panoptic";
+let OtelApi;
+let isModuleExists = null;
+let loadingPromise;
+const OTEL_INSTALL_INSTRUCTIONS = `
+The Panoptic OpenTelemetry exporter requires the @opentelemetry/api package.
+Install it with:
+
+  npm install @opentelemetry/api
+
+Or with your preferred package manager:
+
+  pnpm add @opentelemetry/api
+  yarn add @opentelemetry/api
+`.trim();
+/**
+* Settle the lazy import of `@opentelemetry/api` once, concurrency-safe.
+* A bare `catch` flips the flag to `false`; the curated install string
+* surfaces at use time so a missing SDK never throws a raw module
+* resolution error.
+*/
+function loadOtel() {
+	if (isModuleExists !== null) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			OtelApi = await import("@opentelemetry/api");
+			isModuleExists = true;
+		} catch {
+			isModuleExists = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* {@link ExporterContract} that maps Panoptic traces onto OpenTelemetry
+* spans following the GenAI semantic conventions (`gen_ai.*`
+* attributes). Lazily imports `@opentelemetry/api` so it stays an
+* OPTIONAL peer — importing this module never forces the SDK to be
+* installed, and a missing SDK surfaces as a curated "install this"
+* error on first `export`, not a boot-time stack trace.
+*
+* The exporter emits onto a `Tracer` you supply (or fetches one from the
+* globally registered provider). It never configures the SDK — wiring a
+* `TracerProvider`, processors, and span exporters is the host app's
+* job, exactly as with any other OTel instrumentation.
+*
+* Each {@link TraceSpan} becomes one OTel span with the source span's
+* start/end times and parent relationship reconstructed, so the emitted
+* tree matches the original execution tree.
+*
+* @example
+* // app already set up @opentelemetry/sdk-trace-base + a provider
+* collector.use(otelExporter({ tracerName: "my-app", system: "openai" }));
+*/
+function otelExporter(options = {}) {
+	loadOtel();
+	return {
+		name: EXPORTER_NAME,
+		async export(trace) {
+			await loadOtel();
+			if (!isModuleExists) throw new Error(OTEL_INSTALL_INSTRUCTIONS);
+			emitSpan(resolveTracer(options), trace.root, void 0, options);
+		}
+	};
+}
+/**
+* Resolve the `Tracer` spans are emitted on — the caller-supplied one,
+* or one fetched from the globally registered provider by name.
+*/
+function resolveTracer(options) {
+	if (options.tracer) return options.tracer;
+	return OtelApi.trace.getTracer(options.tracerName ?? DEFAULT_TRACER_NAME, options.tracerVersion);
+}
+/**
+* Recreate one {@link TraceSpan} (and its subtree) as OTel spans. The
+* span is started with the source `startedAt`, parented under
+* `parentContext` so the tree is preserved, annotated with GenAI
+* attributes, given the mapped status, and ended at `endedAt`. Children
+* recurse under this span's context.
+*/
+function emitSpan(tracer, span, parentContext, options) {
+	const startTime = toEpochMillis(span.startedAt);
+	const baseContext = parentContext ?? OtelApi.context.active();
+	const otelSpan = tracer.startSpan(span.name, { startTime }, baseContext);
+	applyAttributes(otelSpan, span, options);
+	applyStatus(otelSpan, span);
+	const childContext = OtelApi.trace.setSpan(baseContext, otelSpan);
+	for (const child of span.children) emitSpan(tracer, child, childContext, options);
+	otelSpan.end(toEpochMillis(span.endedAt));
+}
+/**
+* Set the GenAI + Warlock attributes on the OTel span, defaulting
+* `gen_ai.system` from the exporter options when the span carried none.
+*/
+function applyAttributes(otelSpan, span, options) {
+	const attributes = toGenAiAttributes(span);
+	if (options.system !== void 0 && attributes[GEN_AI_ATTRIBUTES.system] === void 0) attributes[GEN_AI_ATTRIBUTES.system] = options.system;
+	otelSpan.setAttributes(attributes);
+}
+/**
+* Map the Panoptic span status onto the OTel span status, recording the
+* normalized error as an exception event + ERROR status when present.
+*/
+function applyStatus(otelSpan, span) {
+	const codes = OtelApi.SpanStatusCode;
+	if (span.error) otelSpan.recordException({
+		name: span.error.type,
+		message: span.error.message,
+		stack: span.error.stack
+	});
+	if (span.status === "failed" || span.status === "cancelled") {
+		otelSpan.setStatus({
+			code: codes.ERROR,
+			message: span.error?.message
+		});
+		return;
+	}
+	if (span.status === "max-iterations" || span.status === "awaiting-input") {
+		otelSpan.setStatus({
+			code: codes.UNSET,
+			message: span.status === "max-iterations" ? "Run hit the iteration cap without an explicit end" : "Run is awaiting the next input turn"
+		});
+		return;
+	}
+	otelSpan.setStatus({ code: codes.OK });
+}
+/**
+* Convert an ISO-8601 timestamp to epoch milliseconds — the `TimeInput`
+* form OTel's `startSpan` / `Span.end` accept directly.
+*/
+function toEpochMillis(isoTimestamp) {
+	return new Date(isoTimestamp).getTime();
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/panoptic/panoptic-middleware.ts
+/**
+* Build an {@link AgentMiddleware} that feeds a collector from the
+* `execute`- and `supervisor`-level hooks. An alternative wiring to event
+* subscription for apps that already compose cross-cutting concerns
+* through the agent middleware pipeline (`[cache, budget, guardrail,
+* observability]`). Declaring both hook maps lets a single middleware
+* object work uniformly on agents (which fire the `execute` map) and
+* supervisors (which fire the `supervisor` map) — registering it on a
+* supervisor would otherwise install and collect nothing silently.
+*
+* Both terminal paths are covered on each surface:
+* - `after` — fires on a run that produced a result. A run can complete
+*   with `result.error` populated (the engine still calls `after`), so
+*   the report AND the envelope error are collected; the error type and
+*   message land on the root span.
+* - `onError` — fires when the run threw before assembling a result. The
+*   error carries the partial result's report on its envelope; when
+*   present it is collected, with the error itself threaded onto the
+*   root span so failed runs still produce a trace.
+*
+* The hooks never return a value, so they never mutate the agent's /
+* supervisor's result. The `collect` call is fire-and-forget relative to
+* the run — the collector isolates exporter failures internally, and we
+* additionally swallow any rejection here so an observability fault can
+* never surface on the run's hot path.
+*
+* @param collector - the collector traces are fed into.
+* @param name - stable middleware name (kebab-case). Defaults to
+*   `"panoptic"`.
+*/
+function createPanopticMiddleware(collector, name = "panoptic") {
+	const collectReport = (report, rootError) => {
+		if (!isReport(report)) return;
+		collector.collect(report, rootError).catch(() => {});
+	};
+	const onResult = (result) => {
+		collectReport(result.report, result.error);
+	};
+	const onError = (error) => {
+		collectReport(error.report, error);
+	};
+	const terminalHooks = {
+		after(_ctx, result) {
+			onResult(result);
+		},
+		onError(_ctx, error) {
+			onError(error);
+		}
+	};
+	return {
+		name,
+		execute: terminalHooks,
+		supervisor: terminalHooks
+	};
+}
+/**
+* Narrow an unknown value to a `BaseReport`-shaped object. Structural
+* (checks the lineage fields the collector reads) so it accepts any
+* primitive's report subtype without importing each concrete type.
+*/
+function isReport(value) {
+	return typeof value === "object" && value !== null && typeof value.runId === "string" && typeof value.rootRunId === "string";
+}
+
+//#endregion
+//#region ../@warlock.js/ai-panoptic/src/panoptic/panoptic.ts
+/**
+* Terminal `*.completed` events of every core primitive that carries the
+* finalized `result` (and therefore the `report` tree). These fire once
+* per run regardless of outcome — the matching `*.error` event fires
+* first on failure, then `*.completed` still fires — so subscribing here
+* captures completed, failed, and cancelled runs alike.
+*
+* The orchestrator is intentionally absent: its `orchestrator.turn.*`
+* events carry only session identity, not a result. Collect an
+* orchestrator turn via {@link Panoptic.collect} with
+* `result.report` instead.
+*/
+const DEFAULT_COMPLETED_EVENTS = [
+	"agent.completed",
+	"workflow.completed",
+	"supervisor.completed"
+];
+/**
+* The Panoptic subscriber — binds a collector + its exporters to the
+* three feed paths (events, middleware, direct). Instantiated via
+* {@link panoptic}; callers never see `new`.
+*/
+var PanopticSubscriber = class {
+	constructor(options = {}) {
+		this.collector = options.collector ?? createCollector();
+		for (const exporter of options.exporters ?? []) this.collector.use(exporter);
+		this.completedEvents = options.completedEvents ?? [...DEFAULT_COMPLETED_EVENTS];
+		this.middlewareName = options.middlewareName ?? "panoptic";
+	}
+	use(exporter) {
+		this.collector.use(exporter);
+		return this;
+	}
+	attach(target) {
+		const unsubscribes = [];
+		for (const event of this.completedEvents) {
+			const unsubscribe = target.on(event, (payload) => {
+				this.handleCompleted(payload);
+			});
+			unsubscribes.push(unsubscribe);
+		}
+		return () => {
+			for (const unsubscribe of unsubscribes) unsubscribe();
+		};
+	}
+	middleware() {
+		return createPanopticMiddleware(this.collector, this.middlewareName);
+	}
+	async collect(report) {
+		await this.collector.collect(report);
+	}
+	toTrace(report) {
+		return this.collector.toTrace(report);
+	}
+	async flush() {
+		await this.collector.flush();
+	}
+	async shutdown() {
+		await this.collector.shutdown();
+	}
+	/**
+	* Project one terminal `*.completed` payload's report into the
+	* collector. The fan-out is fire-and-forget relative to the emitting
+	* run: the core swallows handler errors, the collector isolates
+	* exporter failures, and we additionally guard the rejection here so an
+	* observability fault never escapes the event handler.
+	*/
+	handleCompleted(payload) {
+		const report = readReport(payload);
+		if (!report) return;
+		const rootError = readResultError(payload);
+		this.collector.collect(report, rootError).catch(() => {});
+	}
+};
+/**
+* Read the envelope error off a primitive's completed-event payload
+* (`{ result: { error } }`). The error rides on the result envelope, not
+* the report tree, so the collector needs it separately to populate a
+* failed root span. Returns `undefined` when the run succeeded.
+*/
+function readResultError(payload) {
+	return (payload?.result)?.error;
+}
+/**
+* Read the `report` tree off a primitive's completed-event payload.
+* Structural (no concrete-type import) so it accepts every primitive's
+* result subtype; returns `undefined` when the payload isn't the
+* expected `{ result: { report } }` shape.
+*/
+function readReport(payload) {
+	const report = (payload?.result)?.report;
+	if (typeof report === "object" && report !== null && typeof report.runId === "string" && typeof report.rootRunId === "string") return report;
+}
+/**
+* Create a Panoptic subscriber — the one-call entry point that wires the
+* observability pipeline. Pass the exporters you want and Panoptic
+* builds a collector, registers them, and hands back a subscriber you can
+* `attach()` to any agent/workflow/supervisor, install as agent
+* `middleware()`, or feed reports to directly with `collect()`.
+*
+* @example
+* // Attach to a primitive's event stream (captures every run):
+* const observe = panoptic({
+*   exporters: [consoleExporter(), otelExporter({ tracerName: "app" })],
+* });
+*
+* const agent = ai.agent({ model });
+* const detach = observe.attach(agent);
+*
+* await agent.execute("Summarize this");
+* // ...later, on shutdown:
+* await observe.shutdown();
+*
+* @example
+* // Or wire it through the agent middleware pipeline:
+* const observe = panoptic({ exporters: [langfuseExporter({ ... })] });
+* const agent = ai.agent({ model, middleware: [observe.middleware()] });
+*
+* @example
+* // Orchestrator turns carry no result-bearing event — collect directly:
+* const result = await orchestrator.execute(input, { sessionId });
+* await observe.collect(result.report);
+*/
+function panoptic(options = {}) {
+	return new PanopticSubscriber(options);
+}
+
+//#endregion
+exports.GEN_AI_ATTRIBUTES = GEN_AI_ATTRIBUTES;
+exports.WARLOCK_ATTRIBUTES = WARLOCK_ATTRIBUTES;
+exports.consoleExporter = consoleExporter;
+exports.createCollector = createCollector;
+exports.createInMemoryTraceStore = createInMemoryTraceStore;
+exports.createPanopticMiddleware = createPanopticMiddleware;
+exports.emptyUsage = emptyUsage;
+exports.extractSpanAttributes = extractSpanAttributes;
+exports.fileExporter = fileExporter;
+exports.formatSpanLine = formatSpanLine;
+exports.langfuseExporter = langfuseExporter;
+exports.matchTrace = matchTrace;
+exports.normalizeError = normalizeError;
+exports.otelExporter = otelExporter;
+exports.panoptic = panoptic;
+exports.reportToSpan = reportToSpan;
+exports.reportToTrace = reportToTrace;
+exports.sumUsage = sumUsage;
+exports.toGenAiAttributes = toGenAiAttributes;
+exports.totalCostUsd = totalCostUsd;
+exports.walkSpans = walkSpans;
+//# sourceMappingURL=index.cjs.map