@warlock.js/ai-panoptic 4.3.0

package/esm/collector/report-to-span.mjs

@@ -0,0 +1,53 @@
+import { normalizeError } from "./normalize-error.mjs";
+import { extractSpanAttributes } from "./extract-span-attributes.mjs";
+
+//#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
+export { reportToSpan };
+//# sourceMappingURL=report-to-span.mjs.map

package/esm/collector/report-to-span.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-to-span.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/collector/report-to-span.ts"],"sourcesContent":["import type { BaseReport } from \"@warlock.js/ai\";\nimport type { TraceSpan } from \"../contracts/trace.type\";\nimport { extractSpanAttributes } from \"./extract-span-attributes\";\nimport { normalizeError } from \"./normalize-error\";\n\n/**\n * Project one {@link BaseReport} node — and its entire subtree — into a\n * {@link TraceSpan}. Pure and recursive: identity, timing, status, and\n * the rolled-up `usage` map across 1:1 from the report; lineage maps\n * `runId → spanId`, `parentRunId → parentSpanId`, `rootRunId → traceId`;\n * children recurse in invocation order so the span tree mirrors the\n * report tree exactly.\n *\n * The error is normalized to the JSON-safe {@link\n * import(\"../contracts/trace.type\").TraceSpanError} shape only when the\n * node carried one (failed / cancelled). Primitive-specific detail that\n * has no first-class span field (trip / step / iteration counts, model\n * identity, tool trip index) is routed into the optional `attributes`\n * bag via {@link extractSpanAttributes}.\n *\n * No external lookup is needed — a `BaseReport` already carries\n * everything a span requires, so a collector can flatten a tree without\n * consulting any other source.\n *\n * @example\n * const root = reportToSpan(result.report);\n * console.log(root.spanId, root.traceId, root.children.length);\n */\nexport function reportToSpan(report: BaseReport): TraceSpan {\n  const span: TraceSpan = {\n    spanId: report.runId,\n    traceId: report.rootRunId,\n    name: report.name,\n    type: report.type,\n    status: report.status,\n    startedAt: report.startedAt,\n    endedAt: report.endedAt,\n    duration: report.duration,\n    usage: report.usage,\n    children: report.children.map(reportToSpan),\n  };\n\n  if (report.parentRunId !== undefined) {\n    span.parentSpanId = report.parentRunId;\n  }\n\n  if (report.sessionId !== undefined) {\n    span.sessionId = report.sessionId;\n  }\n\n  if (report.version !== undefined) {\n    span.version = report.version;\n  }\n\n  const error = normalizeError((report as { error?: unknown }).error);\n  if (error !== undefined) {\n    span.error = error;\n  }\n\n  const attributes = extractSpanAttributes(report);\n  if (attributes !== undefined) {\n    span.attributes = attributes;\n  }\n\n  return span;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,aAAa,QAA+B;CAC1D,MAAM,OAAkB;EACtB,QAAQ,OAAO;EACf,SAAS,OAAO;EAChB,MAAM,OAAO;EACb,MAAM,OAAO;EACb,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,UAAU,OAAO;EACjB,OAAO,OAAO;EACd,UAAU,OAAO,SAAS,IAAI,YAAY;CAC5C;CAEA,IAAI,OAAO,gBAAgB,QACzB,KAAK,eAAe,OAAO;CAG7B,IAAI,OAAO,cAAc,QACvB,KAAK,YAAY,OAAO;CAG1B,IAAI,OAAO,YAAY,QACrB,KAAK,UAAU,OAAO;CAGxB,MAAM,QAAQ,eAAgB,OAA+B,KAAK;CAClE,IAAI,UAAU,QACZ,KAAK,QAAQ;CAGf,MAAM,aAAa,sBAAsB,MAAM;CAC/C,IAAI,eAAe,QACjB,KAAK,aAAa;CAGpB,OAAO;AACT"}

package/esm/collector/report-to-trace.d.mts

@@ -0,0 +1,35 @@
+import { Trace } from "../contracts/trace.type.mjs";
+import { BaseReport } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-panoptic/src/collector/report-to-trace.d.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);
+ */
+declare function reportToTrace(report: BaseReport, rootError?: unknown): Trace;
+//#endregion
+export { reportToTrace };
+//# sourceMappingURL=report-to-trace.d.mts.map

package/esm/collector/report-to-trace.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-to-trace.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/collector/report-to-trace.ts"],"mappings":";;;;;;AAgCA;;;;;;;;;AAA6E;;;;;;;;;;;;;;;;iBAA7D,aAAA,CAAc,MAAA,EAAQ,UAAA,EAAY,SAAA,aAAsB,KAAK"}

package/esm/collector/report-to-trace.mjs

@@ -0,0 +1,53 @@
+import { normalizeError } from "./normalize-error.mjs";
+import { reportToSpan } from "./report-to-span.mjs";
+
+//#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
+export { reportToTrace };
+//# sourceMappingURL=report-to-trace.mjs.map

package/esm/collector/report-to-trace.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-to-trace.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/collector/report-to-trace.ts"],"sourcesContent":["import type { BaseReport } from \"@warlock.js/ai\";\nimport type { Trace } from \"../contracts/trace.type\";\nimport { normalizeError } from \"./normalize-error\";\nimport { reportToSpan } from \"./report-to-span\";\n\n/**\n * Project an outermost {@link BaseReport} (one whole `.execute()` /\n * `.invoke()` run) into a {@link Trace} — the root {@link\n * import(\"../contracts/trace.type\").TraceSpan} plus the trace-wide\n * rollups exporters need without re-walking the tree.\n *\n * The trace-level identity and rollups all read off the root span the\n * projection already built (`traceId`, `usage`, timing), so the trace\n * envelope never disagrees with its own root. `reportSchemaVersion` is\n * mirrored from the root report when present (it is stamped only on\n * root nodes upstream) so exporters can branch on the source shape.\n *\n * Pure — the same input always yields the same trace. The collector\n * exposes this as `toTrace` so callers can inspect the normalized shape\n * without dispatching to exporters.\n *\n * The optional `rootError` threads the failing run's envelope error\n * (`BaseResult.error`) onto the root span. The error lives on the result\n * envelope, never on the `BaseReport` tree, so without this a failed root\n * would export `status` with no error type/message. Applied only when the\n * root span carries none of its own; the subtree projection stays pure\n * (each child surfaces its own report-level error, if any).\n *\n * @example\n * const trace = reportToTrace(result.report, result.error);\n * console.log(trace.traceId, trace.usage.total, trace.duration);\n */\nexport function reportToTrace(report: BaseReport, rootError?: unknown): Trace {\n  const root = reportToSpan(report);\n\n  if (root.error === undefined) {\n    const error = normalizeError(rootError);\n\n    if (error !== undefined) {\n      root.error = error;\n    }\n  }\n\n  const trace: Trace = {\n    traceId: root.traceId,\n    root,\n    startedAt: root.startedAt,\n    endedAt: root.endedAt,\n    duration: root.duration,\n    usage: root.usage,\n  };\n\n  if (root.sessionId !== undefined) {\n    trace.sessionId = root.sessionId;\n  }\n\n  if (report.reportSchemaVersion !== undefined) {\n    trace.reportSchemaVersion = report.reportSchemaVersion;\n  }\n\n  return trace;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,cAAc,QAAoB,WAA4B;CAC5E,MAAM,OAAO,aAAa,MAAM;CAEhC,IAAI,KAAK,UAAU,QAAW;EAC5B,MAAM,QAAQ,eAAe,SAAS;EAEtC,IAAI,UAAU,QACZ,KAAK,QAAQ;CAEjB;CAEA,MAAM,QAAe;EACnB,SAAS,KAAK;EACd;EACA,WAAW,KAAK;EAChB,SAAS,KAAK;EACd,UAAU,KAAK;EACf,OAAO,KAAK;CACd;CAEA,IAAI,KAAK,cAAc,QACrB,MAAM,YAAY,KAAK;CAGzB,IAAI,OAAO,wBAAwB,QACjC,MAAM,sBAAsB,OAAO;CAGrC,OAAO;AACT"}

package/esm/contracts/collector.contract.d.mts

@@ -0,0 +1,63 @@
+import { Trace } from "./trace.type.mjs";
+import { ExporterContract } from "./exporter.contract.mjs";
+import { BaseReport } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-panoptic/src/contracts/collector.contract.d.ts
+/**
+ * Contract for the Panoptic collector — the source end of the
+ * observability pipeline. A collector ingests core `@warlock.js/ai`
+ * execution reports (a {@link BaseReport} tree), normalizes them into a
+ * {@link Trace}, and fans the result out to every registered
+ * {@link ExporterContract}.
+ *
+ * The collector is the single integration point an app wires into its
+ * agents/workflows (typically via the `onComplete` report hook). It
+ * owns exporter registration, the report-to-trace projection, and
+ * graceful shutdown so exporters drain before exit.
+ *
+ * @example
+ * collector.use(otelExporter).use(langfuseExporter);
+ * agent.on("onComplete", (report) => collector.collect(report));
+ * // on shutdown:
+ * await collector.shutdown();
+ */
+interface CollectorContract {
+  /**
+   * Register an exporter. Returns the collector for chaining. Duplicate
+   * registration (same `ExporterContract.name`) is ignored.
+   */
+  use(exporter: ExporterContract): this;
+  /**
+   * Ingest one finalized root report, project it into a {@link Trace},
+   * and dispatch it to every registered exporter. Resolves once all
+   * exporters have been invoked; individual exporter failures are
+   * isolated and never propagate back into the originating run.
+   *
+   * `rootError` threads the failing run's envelope error (`BaseResult.error`)
+   * onto the root span — the error lives on the result envelope, not on the
+   * `BaseReport` tree, so a failed root would otherwise carry `status` with
+   * no error type/message. Applied only when the root span has none of its
+   * own.
+   */
+  collect(report: BaseReport, rootError?: unknown): Promise<void>;
+  /**
+   * Pure projection of a report tree into a {@link Trace}, exposed so
+   * callers can inspect or test the normalized shape without dispatching
+   * to exporters. `collect` uses this internally. `rootError` threads the
+   * envelope error onto the root span exactly as in {@link collect}.
+   */
+  toTrace(report: BaseReport, rootError?: unknown): Trace;
+  /**
+   * Flush every registered exporter that supports it. Useful between
+   * batches or before a checkpoint.
+   */
+  flush(): Promise<void>;
+  /**
+   * Flush and shut down every registered exporter, then release the
+   * collector. Call once during process teardown.
+   */
+  shutdown(): Promise<void>;
+}
+//#endregion
+export { CollectorContract };
+//# sourceMappingURL=collector.contract.d.mts.map

package/esm/contracts/collector.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/contracts/collector.contract.ts"],"mappings":";;;;;;;AAsBA;;;;;;;;;;;;;;;;UAAiB,iBAAA;EAmBP;;;;EAdR,GAAA,CAAI,QAAA,EAAU,gBAAA;EAsBN;;;;;;;;AAYW;;;;EApBnB,OAAA,CAAQ,MAAA,EAAQ,UAAA,EAAY,SAAA,aAAsB,OAAA;;;;;;;EAQlD,OAAA,CAAQ,MAAA,EAAQ,UAAA,EAAY,SAAA,aAAsB,KAAA;;;;;EAMlD,KAAA,IAAS,OAAA;;;;;EAMT,QAAA,IAAY,OAAA;AAAA"}

package/esm/contracts/exporter.contract.d.mts

@@ -0,0 +1,76 @@
+import { Trace, TraceSpan } from "./trace.type.mjs";
+
+//#region ../@warlock.js/ai-panoptic/src/contracts/exporter.contract.d.ts
+/**
+ * Contract every Panoptic exporter implements. An exporter is the sink
+ * end of the observability pipeline: a `Collector` flattens core
+ * `@warlock.js/ai` reports into {@link Trace} / {@link TraceSpan}
+ * values and hands them to one or more exporters, which translate them
+ * into a backend's wire format (OpenTelemetry spans, Langfuse
+ * generations, a console table, …).
+ *
+ * **Optional-peer rule.** Concrete exporters that wrap a third-party
+ * SDK (`@opentelemetry/*`, `langfuse`) MUST lazily import that SDK
+ * inside the factory/`export` path — never at module top level — so
+ * the SDK stays an OPTIONAL peer dependency and importing this package
+ * never forces an unused vendor SDK to be installed.
+ *
+ * **Lifecycle.** A collector calls {@link ExporterContract.export} once
+ * per completed trace (and, when the exporter advertises it, also calls
+ * {@link ExporterContract.exportSpan} once for every span in the
+ * finalized tree — a post-completion per-span hook, not a live stream).
+ * `flush` / `shutdown` let buffered exporters drain before process
+ * exit.
+ *
+ * All methods may be async; the collector awaits them. An exporter that
+ * throws must not crash the originating run — the collector isolates
+ * exporter failures the same way the core event hooks swallow consumer
+ * errors.
+ *
+ * @example
+ * const exporter: ExporterContract = {
+ *   name: "console",
+ *   async export(trace) {
+ *     console.log(trace.traceId, trace.usage.total, "tokens");
+ *   },
+ * };
+ */
+interface ExporterContract {
+  /**
+   * Stable identifier for this exporter (e.g. `"otel"`, `"langfuse"`,
+   * `"console"`). Used in logs and to de-duplicate exporters registered
+   * on a collector.
+   */
+  readonly name: string;
+  /**
+   * Emit one completed trace. Called once per outermost run after the
+   * root report is finalized. The exporter translates `trace` into its
+   * backend format and dispatches it.
+   */
+  export(trace: Trace): void | Promise<void>;
+  /**
+   * Optional per-span hook — invoked once for every span in the
+   * finalized trace tree (root first, then each descendant in
+   * invocation order), after `export`. A post-completion projection of
+   * the same tree, not a live feed: it lets flat-stream backends emit
+   * one record per node without re-walking `children` themselves.
+   * Collectors only invoke this when present; exporters that consume the
+   * whole tree in `export` may omit it.
+   */
+  exportSpan?(span: TraceSpan): void | Promise<void>;
+  /**
+   * Optional — flush any buffered traces/spans to the backend without
+   * tearing the exporter down. Collectors call this on demand (e.g.
+   * between batches) and during `shutdown`.
+   */
+  flush?(): void | Promise<void>;
+  /**
+   * Optional — flush and release resources (close HTTP clients, OTel
+   * processors). Called once when the owning collector is disposed.
+   * After `shutdown`, the exporter should not be reused.
+   */
+  shutdown?(): void | Promise<void>;
+}
+//#endregion
+export { ExporterContract };
+//# sourceMappingURL=exporter.contract.d.mts.map

package/esm/contracts/exporter.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/contracts/exporter.contract.ts"],"mappings":";;;;;AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;AAsC6B;;;;;;;UAtCZ,gBAAA;;;;;;WAMN,IAAA;;;;;;EAOT,MAAA,CAAO,KAAA,EAAO,KAAA,UAAe,OAAA;;;;;;;;;;EAW7B,UAAA,EAAY,IAAA,EAAM,SAAA,UAAmB,OAAA;;;;;;EAOrC,KAAA,YAAiB,OAAA;;;;;;EAOjB,QAAA,YAAoB,OAAA;AAAA"}

package/esm/contracts/index.d.mts

@@ -0,0 +1,3 @@
+import { Trace, TraceSpan, TraceSpanError } from "./trace.type.mjs";
+import { ExporterContract } from "./exporter.contract.mjs";
+import { CollectorContract } from "./collector.contract.mjs";

package/esm/contracts/trace.type.d.mts

@@ -0,0 +1,122 @@
+import { ReportStatus, ReportType, Usage } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-panoptic/src/contracts/trace.type.d.ts
+/**
+ * A single node in a Panoptic trace tree, derived 1:1 from a core
+ * `@warlock.js/ai` {@link BaseReport} node. Where `BaseReport` is the
+ * framework's native execution report, a {@link TraceSpan} is its
+ * observability-vendor projection: the same identity and timing
+ * normalized to the span vocabulary shared by OpenTelemetry, Langfuse,
+ * and similar backends.
+ *
+ * The mapping is intentionally lossless on the fields exporters care
+ * about — identity (`spanId` / `parentSpanId` / `traceId`), timing
+ * (`startedAt` / `endedAt` / `duration`), outcome (`status` / `error`),
+ * and cost (`usage`) — so a collector can flatten a `BaseReport` tree
+ * into spans without consulting any other source.
+ *
+ * @example
+ * const root: TraceSpan = {
+ *   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: [],
+ * };
+ */
+type TraceSpan = {
+  /**
+   * Stable id for this span. Mirrors `BaseReport.runId` — one span per
+   * execution node.
+   */
+  spanId: string;
+  /**
+   * Id of the immediate parent span, mirroring `BaseReport.parentRunId`.
+   * Absent on the root span of a trace.
+   */
+  parentSpanId?: string;
+  /**
+   * Id of the top-level trace this span belongs to. Mirrors
+   * `BaseReport.rootRunId`; equals `spanId` on the root span. Exporters
+   * map this onto the backend's trace id (OTel `traceId`, Langfuse
+   * trace).
+   */
+  traceId: string;
+  /**
+   * Caller-supplied grouping id mirrored from `BaseReport.sessionId`.
+   * Surfaces as a session/thread dimension in backends that model
+   * conversations. Absent when the caller didn't supply one.
+   */
+  sessionId?: string; /** Executable identity — the tool/agent/workflow/supervisor name. */
+  name: string;
+  /**
+   * Dev-curated version string mirrored from `BaseReport.version`.
+   * Free-form; surfaced as a span attribute so dashboards can slice
+   * runs of "agent X v2.1" from "v2.2". Absent when undeclared.
+   */
+  version?: string; /** Discriminator for the kind of executable that produced this span. */
+  type: ReportType; /** Terminal status of this execution, mirrored from `BaseReport.status`. */
+  status: ReportStatus; /** ISO-8601 wall-clock timestamp when execution began. */
+  startedAt: string; /** ISO-8601 wall-clock timestamp when execution finished. */
+  endedAt: string; /** Monotonic duration in milliseconds. */
+  duration: number; /** Rolled-up usage for this node (own cost + sum of children). */
+  usage: Usage;
+  /**
+   * Normalized error description when `status` is `"failed"` /
+   * `"cancelled"`. Carried separately from status so exporters can set
+   * a backend error event/attribute. Absent on successful spans.
+   */
+  error?: TraceSpanError;
+  /**
+   * Free-form attribute bag forwarded verbatim onto the backend span
+   * (OTel attributes, Langfuse metadata). Collectors populate this with
+   * primitive-specific detail (trip index, step name, tool args digest)
+   * that has no first-class field here. Absent when empty.
+   */
+  attributes?: Record<string, unknown>;
+  /**
+   * Child spans, mirroring `BaseReport.children` in invocation order.
+   * Empty for leaf spans (pure tools). Exporters that emit a flat
+   * stream may ignore this and rely on `parentSpanId` instead.
+   */
+  children: TraceSpan[];
+};
+/**
+ * Normalized error attached to a failed / cancelled {@link TraceSpan}.
+ * Kept structural (not an `Error` instance) so it survives JSON
+ * serialization to a backend collector unchanged.
+ */
+type TraceSpanError = {
+  /** Stable error identifier (typed framework error name when available). */type: string; /** Human-readable message. */
+  message: string; /** Optional captured stack trace, when the source error carried one. */
+  stack?: string;
+};
+/**
+ * The root of a Panoptic trace — a top-level {@link TraceSpan} plus the
+ * trace-wide rollups exporters need without re-walking the tree. One
+ * `Trace` corresponds to one outermost `BaseReport` (a single
+ * `.execute()` / `.invoke()` call).
+ */
+type Trace = {
+  /** Trace id — equals the root span's `traceId` / `rootRunId`. */traceId: string; /** Session grouping id, when the originating run carried one. */
+  sessionId?: string; /** Root span of this trace. */
+  root: TraceSpan; /** Wall-clock start of the trace (root span `startedAt`). */
+  startedAt: string; /** Wall-clock end of the trace (root span `endedAt`). */
+  endedAt: string; /** Total trace duration in milliseconds (root span `duration`). */
+  duration: number; /** Trace-wide usage rollup (root span `usage`). */
+  usage: Usage;
+  /**
+   * Wire-format version of the source `BaseReport` shape, mirrored from
+   * `BaseReport.reportSchemaVersion`. Exporters branch on this to parse
+   * older stored traces with their original-shape rules.
+   */
+  reportSchemaVersion?: number;
+};
+//#endregion
+export { Trace, TraceSpan, TraceSpanError };
+//# sourceMappingURL=trace.type.d.mts.map

package/esm/contracts/trace.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/contracts/trace.type.ts"],"mappings":";;;;;AA8BA;;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,SAAA;EAiDF;;;;EA5CR,MAAA;EAyDmB;AAAA;AAQrB;;EA5DE,YAAA;EA4DwB;;;;;AAMnB;EA3DL,OAAA;EAoEe;;;;;EA9Df,SAAA,WAoEM;EAlEN,IAAA;EAsEA;;;;;EAhEA,OAAA,WA0EmB;EAxEnB,IAAA,EAAM,UAAA;EAEN,MAAA,EAAQ,YAAA;EAER,SAAA;EAEA,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAA;;;;;;EAMP,KAAA,GAAQ,cAAA;;;;;;;EAOR,UAAA,GAAa,MAAA;;;;;;EAMb,QAAA,EAAU,SAAA;AAAA;;;;;;KAQA,cAAA;6EAEV,IAAA;EAEA,OAAA;EAEA,KAAA;AAAA;;;;;;;KASU,KAAA;mEAEV,OAAA;EAEA,SAAA;EAEA,IAAA,EAAM,SAAA;EAEN,SAAA;EAEA,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAK;;;;;;EAMZ,mBAAA;AAAA"}

package/esm/exporters/console/console-exporter.d.mts

@@ -0,0 +1,25 @@
+import { ExporterContract } from "../../contracts/exporter.contract.mjs";
+import { ConsoleExporterOptions } from "./console-exporter.type.mjs";
+
+//#region ../@warlock.js/ai-panoptic/src/exporters/console/console-exporter.d.ts
+/**
+ * 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 }));
+ */
+declare function consoleExporter(options?: ConsoleExporterOptions): ExporterContract;
+//#endregion
+export { consoleExporter };
+//# sourceMappingURL=console-exporter.d.mts.map

package/esm/exporters/console/console-exporter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-exporter.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai-panoptic/src/exporters/console/console-exporter.ts"],"mappings":";;;;;;;AAwBA;;;;;;;;AAAuF;;;;;;iBAAvE,eAAA,CAAgB,OAAA,GAAS,sBAAA,GAA8B,gBAAgB"}

package/esm/exporters/console/console-exporter.mjs

@@ -0,0 +1,79 @@
+import { walkSpans } from "../utils/walk-spans.mjs";
+import { formatSpanLine } from "./format-span-line.mjs";
+
+//#region ../@warlock.js/ai-panoptic/src/exporters/console/console-exporter.ts
+const EXPORTER_NAME = "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,
+		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
+export { consoleExporter };
+//# sourceMappingURL=console-exporter.mjs.map

package/esm/exporters/console/console-exporter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-exporter.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai-panoptic/src/exporters/console/console-exporter.ts"],"sourcesContent":["import type { ExporterContract, Trace, TraceSpan } from \"../../contracts\";\nimport { walkSpans } from \"../utils\";\nimport type { ConsoleExporterOptions, ConsoleLike } from \"./console-exporter.type\";\nimport { formatSpanLine } from \"./format-span-line\";\n\nconst EXPORTER_NAME = \"console\";\n\n/**\n * Zero-dependency {@link ExporterContract} that prints traces to a\n * console-like sink. The simplest exporter — useful in development and\n * as the reference implementation of the contract.\n *\n * By default it prints one summary line per completed trace. Set\n * `tree: true` to print the full indented span tree, and\n * `streaming: true` to also print each span the moment it finalizes\n * (via the optional `exportSpan` hook).\n *\n * @example\n * collector.use(consoleExporter());\n * // ok workflow \"checkout\" — 2103ms, 1820 tok, $0.0094\n *\n * @example\n * collector.use(consoleExporter({ tree: true }));\n */\nexport function consoleExporter(options: ConsoleExporterOptions = {}): ExporterContract {\n  const sink: ConsoleLike = options.console ?? console;\n  const tree = options.tree ?? false;\n\n  const exporter: ExporterContract = {\n    name: EXPORTER_NAME,\n    export(trace: Trace): void {\n      writeTrace(sink, trace, tree);\n    },\n  };\n\n  if (options.streaming) {\n    exporter.exportSpan = (span: TraceSpan): void => {\n      sink.log(formatSpanLine(span));\n    };\n  }\n\n  return exporter;\n}\n\n/**\n * Write a completed trace — either a single root summary line or the\n * full indented tree. Failed traces are routed to `console.error` so\n * they surface at the right severity in log aggregators.\n */\nfunction writeTrace(sink: ConsoleLike, trace: Trace, tree: boolean): void {\n  if (!tree) {\n    const line = formatSpanLine(trace.root);\n    writeAtSeverity(sink, trace.root.status, line);\n    return;\n  }\n\n  for (const span of walkSpans(trace.root)) {\n    const depth = spanDepth(trace.root, span.spanId);\n    const line = formatSpanLine(span, depth);\n    writeAtSeverity(sink, span.status, line);\n  }\n}\n\n/**\n * Route a line to `error` when the span failed/cancelled, otherwise to\n * `log`. Keeps healthy traces out of the error stream.\n */\nfunction writeAtSeverity(sink: ConsoleLike, status: TraceSpan[\"status\"], line: string): void {\n  if (status === \"failed\" || status === \"cancelled\") {\n    sink.error(line);\n    return;\n  }\n\n  sink.log(line);\n}\n\n/**\n * Depth of `targetSpanId` below `root` for indentation. Walks the tree\n * once; returns 0 when the span is the root or not found.\n */\nfunction spanDepth(root: TraceSpan, targetSpanId: string, depth = 0): number {\n  if (root.spanId === targetSpanId) {\n    return depth;\n  }\n\n  for (const child of root.children) {\n    const found = spanDepth(child, targetSpanId, depth + 1);\n\n    if (found > 0) {\n      return found;\n    }\n  }\n\n  return 0;\n}\n"],"mappings":";;;;AAKA,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;AAmBtB,SAAgB,gBAAgB,UAAkC,CAAC,GAAqB;CACtF,MAAM,OAAoB,QAAQ,WAAW;CAC7C,MAAM,OAAO,QAAQ,QAAQ;CAE7B,MAAM,WAA6B;EACjC,MAAM;EACN,OAAO,OAAoB;GACzB,WAAW,MAAM,OAAO,IAAI;EAC9B;CACF;CAEA,IAAI,QAAQ,WACV,SAAS,cAAc,SAA0B;EAC/C,KAAK,IAAI,eAAe,IAAI,CAAC;CAC/B;CAGF,OAAO;AACT;;;;;;AAOA,SAAS,WAAW,MAAmB,OAAc,MAAqB;CACxE,IAAI,CAAC,MAAM;EACT,MAAM,OAAO,eAAe,MAAM,IAAI;EACtC,gBAAgB,MAAM,MAAM,KAAK,QAAQ,IAAI;EAC7C;CACF;CAEA,KAAK,MAAM,QAAQ,UAAU,MAAM,IAAI,GAAG;EAExC,MAAM,OAAO,eAAe,MADd,UAAU,MAAM,MAAM,KAAK,MACH,CAAC;EACvC,gBAAgB,MAAM,KAAK,QAAQ,IAAI;CACzC;AACF;;;;;AAMA,SAAS,gBAAgB,MAAmB,QAA6B,MAAoB;CAC3F,IAAI,WAAW,YAAY,WAAW,aAAa;EACjD,KAAK,MAAM,IAAI;EACf;CACF;CAEA,KAAK,IAAI,IAAI;AACf;;;;;AAMA,SAAS,UAAU,MAAiB,cAAsB,QAAQ,GAAW;CAC3E,IAAI,KAAK,WAAW,cAClB,OAAO;CAGT,KAAK,MAAM,SAAS,KAAK,UAAU;EACjC,MAAM,QAAQ,UAAU,OAAO,cAAc,QAAQ,CAAC;EAEtD,IAAI,QAAQ,GACV,OAAO;CAEX;CAEA,OAAO;AACT"}

package/esm/exporters/console/console-exporter.type.d.mts

@@ -0,0 +1,36 @@
+//#region ../@warlock.js/ai-panoptic/src/exporters/console/console-exporter.type.d.ts
+/**
+ * Sink a {@link ConsoleExporter} writes formatted lines to. Defaults to
+ * the global `console`; injectable so tests can capture output without
+ * monkey-patching the global. Only the two levels the exporter uses are
+ * required.
+ */
+type ConsoleLike = {
+  log(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+};
+/**
+ * Options for {@link consoleExporter}.
+ */
+type ConsoleExporterOptions = {
+  /**
+   * Where to write. Defaults to the global `console`. Inject a custom
+   * sink in tests or to redirect to a structured logger.
+   */
+  console?: ConsoleLike;
+  /**
+   * Emit one indented line per span in the trace tree (`true`) instead
+   * of a single summary line for the whole trace (`false`). Defaults to
+   * `false` — one line per trace keeps long-running processes readable.
+   */
+  tree?: boolean;
+  /**
+   * Also print live `exportSpan` lines as each span finalizes. Defaults
+   * to `false`; the collector only calls `exportSpan` when the method is
+   * present, so leaving this off omits the method entirely.
+   */
+  streaming?: boolean;
+};
+//#endregion
+export { ConsoleExporterOptions, ConsoleLike };
+//# sourceMappingURL=console-exporter.type.d.mts.map

package/esm/exporters/console/console-exporter.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-exporter.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai-panoptic/src/exporters/console/console-exporter.type.ts"],"mappings":";;AAMA;;;;;KAAY,WAAA;EACV,GAAA,IAAO,IAAA;EACP,KAAA,IAAS,IAAA;AAAA;AAAI;AAMf;;AANe,KAMH,sBAAA;EAKW;;;;EAArB,OAAA,GAAU,WAAW;EAYZ;AAAA;;;;EANT,IAAA;;;;;;EAMA,SAAA;AAAA"}

package/esm/exporters/console/format-span-line.d.mts

@@ -0,0 +1,17 @@
+import { TraceSpan } from "../../contracts/trace.type.mjs";
+//#region ../@warlock.js/ai-panoptic/src/exporters/console/format-span-line.d.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'
+ */
+declare function formatSpanLine(span: TraceSpan, depth?: number): string;
+//#endregion
+export { formatSpanLine };
+//# sourceMappingURL=format-span-line.d.mts.map

package/esm/exporters/console/format-span-line.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-span-line.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai-panoptic/src/exporters/console/format-span-line.ts"],"mappings":";;;;;AAcA;;;;;;;;iBAAgB,cAAA,CAAe,IAAA,EAAM,SAAS,EAAE,KAAA"}