@warlock.js/ai-panoptic 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -4,7 +4,15 @@ All notable changes to `@warlock.js/ai-panoptic` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
-## [Unreleased]
+## 4.4.0 - 2026-06-21
+
+### Added
+
+- **Opt-in content capture.** `createCollector` / `panoptic({ captureContent, redactContent })` copies the agent prompt/response (first-trip input, last non-empty trip output) and each tool's args/result onto `TraceSpan.input` / `output`. Surfaced by `consoleExporter({ io, ioMaxChars })` (new `in:` / `out:` lines), the file exporter's JSON, OTel `gen_ai.prompt` / `gen_ai.completion`, and Langfuse native `input` / `output`. Off by default — payloads are large and often sensitive; a `ContentRedactor` masks each value. New exports: `ContentCaptureOptions`, `ContentRedactor`, `formatSpanIO`.
+
+### Fixed
+
+- **Langfuse token accounting.** Generations now meter their OWN usage (rolled-up minus children); composite nodes with no own tokens emit as plain spans; the root execution is now emitted as an observation (its own tokens were previously unmetered); and the rolled-up usage/cost is stripped from observation metadata (the `usage` block is authoritative). Together these stop the trace total from double-counting nested spans.
 
 ## 4.3.0 - 2026-06-21
 

package/cjs/index.cjs

@@ -159,6 +159,12 @@ function addToolAttributes(attributes, extensions) {
 * identity, tool trip index) is routed into the optional `attributes`
 * bag via {@link extractSpanAttributes}.
 *
+* When {@link ContentCaptureOptions.captureContent} is set, the raw
+* prompt/response (agents) and args/result (tools) are additionally
+* copied onto `span.input` / `span.output` — off by default because
+* payloads are large and often sensitive. A {@link ContentRedactor} can
+* mask each value first.
+*
 * 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.
@@ -167,7 +173,7 @@ function addToolAttributes(attributes, extensions) {
 * const root = reportToSpan(result.report);
 * console.log(root.spanId, root.traceId, root.children.length);
 */
-function reportToSpan(report) {
+function reportToSpan(report, options) {
 	const span = {
 		spanId: report.runId,
 		traceId: report.rootRunId,
@@ -178,7 +184,7 @@ function reportToSpan(report) {
 		endedAt: report.endedAt,
 		duration: report.duration,
 		usage: report.usage,
-		children: report.children.map(reportToSpan)
+		children: report.children.map((child) => reportToSpan(child, options))
 	};
 	if (report.parentRunId !== void 0) span.parentSpanId = report.parentRunId;
 	if (report.sessionId !== void 0) span.sessionId = report.sessionId;
@@ -187,8 +193,66 @@ function reportToSpan(report) {
 	if (error !== void 0) span.error = error;
 	const attributes = extractSpanAttributes(report);
 	if (attributes !== void 0) span.attributes = attributes;
+	if (options?.captureContent) captureContent(span, report, options.redactContent);
 	return span;
 }
+/**
+* Copy the node's raw content onto `span.input` / `span.output`.
+*
+* - Tools carry the call arguments + return value directly on the report
+*   (`ToolCall.input` / `ToolCall.output`).
+* - Agents carry a `trips[]` history; the first trip's `input` is the
+*   real user prompt, and the last NON-EMPTY trip `output` is the final
+*   response text. (A failed / max-trips run can end on a trip whose
+*   `output` is `""` or tool-call-only, so we scan back for the last one
+*   that carried text rather than surfacing an empty string. Intermediate
+*   trips also store a `"[tool results]"` placeholder upstream.)
+*
+* Each value is passed through the optional {@link ContentRedactor};
+* a redactor returning `undefined` drops the field.
+*/
+function captureContent(span, report, redact) {
+	const node = report;
+	let input;
+	let output;
+	if (report.type === "tool") {
+		input = node.input;
+		output = node.output;
+	} else if (Array.isArray(node.trips) && node.trips.length > 0) {
+		input = node.trips[0]?.input;
+		output = lastNonEmptyOutput(node.trips);
+	}
+	if (input !== void 0) {
+		const value = redact ? redact(input, {
+			name: span.name,
+			type: span.type,
+			field: "input"
+		}) : input;
+		if (value !== void 0) span.input = value;
+	}
+	if (output !== void 0) {
+		const value = redact ? redact(output, {
+			name: span.name,
+			type: span.type,
+			field: "output"
+		}) : output;
+		if (value !== void 0) span.output = value;
+	}
+}
+/**
+* The last trip output that actually carries text — the agent's final
+* response on the happy path. A failed or max-trips run can end on a trip
+* whose `output` is `""` or tool-call-only, so we scan backwards for the
+* last trip that produced text rather than blindly taking the final trip
+* (which would surface an empty string). Returns `undefined` when no trip
+* produced any output.
+*/
+function lastNonEmptyOutput(trips) {
+	for (let i = trips.length - 1; i >= 0; i -= 1) {
+		const out = trips[i]?.output;
+		if (typeof out === "string" ? out.length > 0 : out !== void 0) return out;
+	}
+}
 
 //#endregion
 //#region ../@warlock.js/ai-panoptic/src/collector/report-to-trace.ts
@@ -219,8 +283,8 @@ function reportToSpan(report) {
 * const trace = reportToTrace(result.report, result.error);
 * console.log(trace.traceId, trace.usage.total, trace.duration);
 */
-function reportToTrace(report, rootError) {
-	const root = reportToSpan(report);
+function reportToTrace(report, rootError, options) {
+	const root = reportToSpan(report, options);
 	if (root.error === void 0) {
 		const error = normalizeError(rootError);
 		if (error !== void 0) root.error = error;
@@ -257,7 +321,13 @@ function reportToTrace(report, rootError) {
 * agent loop nor stop sibling exporters from receiving the trace.
 */
 var Collector = class {
-	constructor() {
+	/**
+	* Content-capture options threaded into every `toTrace` projection.
+	* When `captureContent` is set, projected spans carry `input` /
+	* `output`; otherwise they stay metadata-only.
+	*/
+	constructor(options = {}) {
+		this.options = options;
 		this.exporters = /* @__PURE__ */ new Map();
 	}
 	use(exporter) {
@@ -265,7 +335,7 @@ var Collector = class {
 		return this;
 	}
 	toTrace(report, rootError) {
-		return reportToTrace(report, rootError);
+		return reportToTrace(report, rootError, this.options);
 	}
 	async collect(report, rootError) {
 		const trace = this.toTrace(report, rootError);
@@ -318,8 +388,8 @@ var Collector = class {
 * // on shutdown:
 * await collector.shutdown();
 */
-function createCollector() {
-	return new Collector();
+function createCollector(options = {}) {
+	return new Collector(options);
 }
 
 //#endregion
@@ -592,7 +662,11 @@ const GEN_AI_ATTRIBUTES = {
 	responseModel: "gen_ai.response.model",
 	usageInputTokens: "gen_ai.usage.input_tokens",
 	usageOutputTokens: "gen_ai.usage.output_tokens",
-	conversationId: "gen_ai.conversation.id"
+	conversationId: "gen_ai.conversation.id",
+	/** Captured prompt/input (set only under content capture). */
+	prompt: "gen_ai.prompt",
+	/** Captured completion/output (set only under content capture). */
+	completion: "gen_ai.completion"
 };
 /**
 * Panoptic-specific attribute keys that have no GenAI-convention
@@ -659,6 +733,56 @@ function mergeScalarAttributes(target, source) {
 	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-io.ts
+/** Default cap on how many characters of captured content a console line shows. */
+const DEFAULT_IO_MAX_CHARS = 500;
+/**
+* Render a span's captured content ({@link TraceSpan.input} /
+* {@link TraceSpan.output}) as extra indented console lines, one level
+* below the span's own line:
+*
+* ```text
+*   ok agent "market-research" — 1794ms, 224 tok, $0.0008
+*       in:  Research the market for Acme Coffee Roasters …
+*       out: Demand is steady; specialty buyers skew premium …
+* ```
+*
+* Returns `[]` when the span carries no content — capture disabled, or a
+* composite node with no own I/O. Each value is stringified (JSON for
+* non-strings), whitespace-collapsed to stay scannable, and truncated to
+* `maxChars` (default {@link DEFAULT_IO_MAX_CHARS}) with an ellipsis. Use
+* the file exporter for the full, untruncated payload.
+*
+* @example
+* formatSpanIO(toolSpan, 1);
+* // ['    in:  {"query":"specialty coffee demand"}', '    out: {"results":[…]}']
+*/
+function formatSpanIO(span, depth = 0, maxChars = DEFAULT_IO_MAX_CHARS) {
+	const lines = [];
+	const indent = "  ".repeat(depth + 1);
+	if (span.input !== void 0) lines.push(`${indent}in:  ${preview(span.input, maxChars)}`);
+	if (span.output !== void 0) lines.push(`${indent}out: ${preview(span.output, maxChars)}`);
+	return lines;
+}
+/**
+* One-line, length-capped preview of a captured value. Strings pass
+* through; everything else is JSON-stringified (falling back to
+* `String()` on a circular / unstringifiable value). Internal whitespace
+* is collapsed so the preview never breaks the tree layout.
+*/
+function preview(value, maxChars) {
+	const collapsed = (typeof value === "string" ? value : stringify(value)).replace(/\s+/g, " ").trim();
+	return collapsed.length > maxChars ? `${collapsed.slice(0, maxChars)}…` : collapsed;
+}
+function stringify(value) {
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+
 //#endregion
 //#region ../@warlock.js/ai-panoptic/src/exporters/console/format-span-line.ts
 /**
@@ -705,9 +829,10 @@ const EXPORTER_NAME$3 = "console";
 * 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).
+* `tree: true` to print the full indented span tree, `io: true` to also
+* print each span's captured `input` / `output` (needs the collector's
+* `captureContent`), and `streaming: true` to print each span the moment
+* it finalizes (via the optional `exportSpan` hook).
 *
 * @example
 * collector.use(consoleExporter());
@@ -715,36 +840,52 @@ const EXPORTER_NAME$3 = "console";
 *
 * @example
 * collector.use(consoleExporter({ tree: true }));
+*
+* @example
+* // Full content trace — prompts, responses, and tool I/O:
+* const observe = panoptic({
+*   captureContent: true,
+*   exporters: [consoleExporter({ tree: true, io: true })],
+* });
 */
 function consoleExporter(options = {}) {
 	const sink = options.console ?? console;
 	const tree = options.tree ?? false;
+	const io = options.io ?? false;
+	const ioMaxChars = options.ioMaxChars;
 	const exporter = {
 		name: EXPORTER_NAME$3,
 		export(trace) {
-			writeTrace(sink, trace, tree);
+			writeTrace(sink, trace, tree, io, ioMaxChars);
 		}
 	};
 	if (options.streaming) exporter.exportSpan = (span) => {
 		sink.log(formatSpanLine(span));
+		if (io) for (const line of formatSpanIO(span, 0, ioMaxChars)) sink.log(line);
 	};
 	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.
+* full indented tree, each span optionally followed by its captured
+* `input` / `output`. Failed / cancelled spans route to `console.error`
+* so they surface at the right severity in log aggregators.
 */
-function writeTrace(sink, trace, tree) {
+function writeTrace(sink, trace, tree, io, ioMaxChars) {
 	if (!tree) {
-		const line = formatSpanLine(trace.root);
-		writeAtSeverity(sink, trace.root.status, line);
+		writeSpan(sink, trace.root, 0, io, ioMaxChars);
 		return;
 	}
-	for (const span of walkSpans(trace.root)) {
-		const line = formatSpanLine(span, spanDepth(trace.root, span.spanId));
-		writeAtSeverity(sink, span.status, line);
-	}
+	for (const span of walkSpans(trace.root)) writeSpan(sink, span, spanDepth(trace.root, span.spanId), io, ioMaxChars);
+}
+/**
+* Write one span's line and — when `io` is on — its captured content,
+* all routed at the span's own severity so a failed span keeps its
+* content beside it in the error stream.
+*/
+function writeSpan(sink, span, depth, io, ioMaxChars) {
+	writeAtSeverity(sink, span.status, formatSpanLine(span, depth));
+	if (io) for (const line of formatSpanIO(span, depth, ioMaxChars)) writeAtSeverity(sink, span.status, line);
 }
 /**
 * Route a line to `error` when the span failed/cancelled, otherwise to
@@ -901,12 +1042,16 @@ function loadLangfuse() {
 * 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.
+* The root {@link TraceSpan} becomes a Langfuse trace AND its top
+* observation (so the root execution's own tokens are metered, not just
+* its children's); every node is an observation — a `generation` when it
+* metered its OWN tokens (LLM-backed agents, supervisors), otherwise a
+* plain `span` (tools, callbacks, and composite nodes whose tokens came
+* only from children). Timing, status, and version map 1:1; each
+* generation reports its own token usage (rolled-up minus children) so
+* the trace total isn't double-counted; non-usage GenAI attributes ride
+* along as metadata, and captured content (under `captureContent`)
+* surfaces as native `input` / `output`.
 *
 * @example
 * collector.use(langfuseExporter({ publicKey: "pk-...", secretKey: "sk-..." }));
@@ -948,20 +1093,20 @@ function langfuseExporter(options) {
 */
 function emitTrace(client, trace) {
 	const root = trace.root;
-	const langfuseTrace = client.trace({
+	emitObservation(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);
+		metadata: langfuseMetadata(root)
+	}), root);
 }
 /**
 * 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`.
+* then recurse its children. Spans that metered their OWN tokens become
+* `generation`s; everything else (tools, callbacks, composite nodes)
+* becomes a plain `span`.
 */
 function emitObservation(parent, span) {
 	const body = {
@@ -972,14 +1117,17 @@ function emitObservation(parent, span) {
 		level: toLevel(span),
 		statusMessage: span.error?.message,
 		version: span.version,
-		metadata: toGenAiAttributes(span)
+		metadata: langfuseMetadata(span)
 	};
+	if (span.input !== void 0) body.input = span.input;
+	if (span.output !== void 0) body.output = span.output;
 	let observation;
-	if (producedTokens(span)) {
+	const own = ownUsage(span);
+	if (own.total > 0) {
 		body.usage = {
-			input: span.usage.input,
-			output: span.usage.output,
-			total: span.usage.total,
+			input: own.input,
+			output: own.output,
+			total: own.total,
 			unit: "TOKENS"
 		};
 		observation = parent.generation(body);
@@ -988,20 +1136,60 @@ function emitObservation(parent, span) {
 	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.
+* Own token usage for a span — its rolled-up {@link TraceSpan.usage}
+* minus the rolled-up usage of its direct children. `TraceSpan.usage` is
+* the subtree total (this node plus every descendant), so subtracting the
+* children leaves the tokens THIS node alone metered, clamped at zero
+* defensively.
 *
-* **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.
+* Langfuse sums observation usage into the trace total, so reporting
+* own-usage on each generation (rather than the subtree rollup) is what
+* keeps the trace total correct instead of multiply-counting nested
+* spans. A composite node with no own tokens (e.g. a workflow whose
+* tokens all came from agent children) yields `total: 0` and is emitted
+* as a plain span, not a generation.
 */
-function producedTokens(span) {
-	return span.usage.total > 0;
+function ownUsage(span) {
+	let childInput = 0;
+	let childOutput = 0;
+	let childTotal = 0;
+	for (const child of span.children) {
+		childInput += child.usage.input;
+		childOutput += child.usage.output;
+		childTotal += child.usage.total;
+	}
+	return {
+		input: Math.max(0, span.usage.input - childInput),
+		output: Math.max(0, span.usage.output - childOutput),
+		total: Math.max(0, span.usage.total - childTotal)
+	};
+}
+/**
+* Token-usage + cost keys that the per-observation `usage` block already
+* carries authoritatively (as OWN usage). Omitting them from `metadata`
+* avoids a confusing contradiction — metadata would otherwise show the
+* rolled-up subtree totals next to an own-usage `usage` block. Cost is
+* omitted for the same reason; Langfuse prices the own tokens itself.
+*/
+const LANGFUSE_METADATA_OMIT = new Set([
+	GEN_AI_ATTRIBUTES.usageInputTokens,
+	GEN_AI_ATTRIBUTES.usageOutputTokens,
+	WARLOCK_ATTRIBUTES.totalTokens,
+	WARLOCK_ATTRIBUTES.cachedTokens,
+	WARLOCK_ATTRIBUTES.reasoningTokens,
+	WARLOCK_ATTRIBUTES.costUsd
+]);
+/**
+* Observation metadata — the GenAI attribute set minus the usage/cost
+* keys that live authoritatively on the `usage` block (see
+* {@link LANGFUSE_METADATA_OMIT}). Keeps model identity, report type,
+* version, session id, and any collector-set attributes.
+*/
+function langfuseMetadata(span) {
+	const all = toGenAiAttributes(span);
+	const metadata = {};
+	for (const [key, value] of Object.entries(all)) if (!LANGFUSE_METADATA_OMIT.has(key)) metadata[key] = value;
+	return metadata;
 }
 /**
 * Map the Panoptic span status onto a Langfuse observation level —
@@ -1113,9 +1301,24 @@ function emitSpan(tracer, span, parentContext, options) {
 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;
+	if (span.input !== void 0) attributes[GEN_AI_ATTRIBUTES.prompt] = stringifyContent(span.input);
+	if (span.output !== void 0) attributes[GEN_AI_ATTRIBUTES.completion] = stringifyContent(span.output);
 	otelSpan.setAttributes(attributes);
 }
 /**
+* Coerce a captured content value to a string OTel attribute. Strings
+* pass through; structured values are JSON-encoded (falling back to
+* `String()` if they can't be serialized).
+*/
+function stringifyContent(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+/**
 * Map the Panoptic span status onto the OTel span status, recording the
 * normalized error as an exception event + ERROR status when present.
 */
@@ -1242,7 +1445,10 @@ const DEFAULT_COMPLETED_EVENTS = [
 */
 var PanopticSubscriber = class {
 	constructor(options = {}) {
-		this.collector = options.collector ?? createCollector();
+		this.collector = options.collector ?? createCollector({
+			captureContent: options.captureContent,
+			redactContent: options.redactContent
+		});
 		for (const exporter of options.exporters ?? []) this.collector.use(exporter);
 		this.completedEvents = options.completedEvents ?? [...DEFAULT_COMPLETED_EVENTS];
 		this.middlewareName = options.middlewareName ?? "panoptic";
@@ -1355,6 +1561,7 @@ exports.createPanopticMiddleware = createPanopticMiddleware;
 exports.emptyUsage = emptyUsage;
 exports.extractSpanAttributes = extractSpanAttributes;
 exports.fileExporter = fileExporter;
+exports.formatSpanIO = formatSpanIO;
 exports.formatSpanLine = formatSpanLine;
 exports.langfuseExporter = langfuseExporter;
 exports.matchTrace = matchTrace;