@warlock.js/ai-panoptic 4.3.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog — @warlock.js/ai-panoptic
+
+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.3.0 - 2026-06-21
+
+Initial release — observability collector + exporters for `@warlock.js/ai`.
+
+### Added
+
+- `panoptic()` — the one-call subscriber factory. Builds a collector, registers exporters, and feeds traces three ways: `attach()` to an agent/workflow/supervisor `*.completed` event stream, `middleware()` for the agent pipeline, and `collect()` for a report directly (e.g. an orchestrator turn). Plus `use()`, `toTrace()`, `flush()`, `shutdown()`, and a `collector` accessor.
+- `createPanopticMiddleware()` — the underlying `AgentMiddleware` adapter feeding the collector from the `execute.after` / `execute.onError` hooks
+- `Panoptic` / `PanopticOptions` / `PanopticTarget` / `CompletedEventPayload` types
+- `panoptic` + middleware + types exported from the root barrel
+- `scripts/generate-llms.mjs` and the generated `llms.txt` / `llms-full.txt` projections of `skills/`
+- `skills/observe-with-panoptic/SKILL.md` — wiring the subscriber into a run
+- `consoleExporter()` — zero-dep exporter printing trace summary or full span tree
+- `fileExporter()` — zero-dep buffered JSON-Lines exporter with `flushEvery`
+- `otelExporter()` — OpenTelemetry exporter mapping spans to GenAI semantic conventions (`gen_ai.*`)
+- `langfuseExporter()` — Langfuse exporter mapping spans to traces, generations, and spans
+- `toGenAiAttributes()` / `walkSpans()` / `totalCostUsd()` exporter utilities
+- Optional peers `@opentelemetry/api` and `langfuse` are lazily imported by their exporters
+- `createCollector()` — consumes the core `BaseReport` tree, projects it to a `Trace`, fans out to exporters
+- `reportToTrace()` / `reportToSpan()` pure projections of a report node to spans
+- `createInMemoryTraceStore()` — queryable in-memory store, doubles as an `ExporterContract`
+- `TraceStoreContract` with `query` / `aggregate` by runId, sessionId, status, and time window
+- `TraceQuery` and `TraceAggregate` types for slicing and rolling up usage + cost
+- `sumUsage()` usage + cost rollup across stored traces, backed by core `accumulateCost`
+- optional `capacity` cap on the in-memory store with FIFO eviction
+- contract surface: `CollectorContract`, `ExporterContract`, and the vendor-neutral trace types `Trace` / `TraceSpan` / `TraceSpanError`, derived 1:1 from the core `BaseReport` tree and event stream
+- `@opentelemetry/api`, `@opentelemetry/sdk-trace-base`, and `langfuse` declared as OPTIONAL peer dependencies (lazily imported by the exporters that need them)
+- `skills/query-traces/SKILL.md` — dedicated skill for the in-memory queryable trace store (`createInMemoryTraceStore`, `query` / `aggregate`, `TraceQuery` / `TraceAggregate`, `capacity` FIFO eviction, `sumUsage` / `emptyUsage` / `matchTrace` helpers)
+
+### Changed
+
+- `skills/export-traces/SKILL.md` — OTel attribute notes: `gen_ai.system` / `gen_ai.request.model` / `gen_ai.operation.name` are only forwarded when the span's attribute bag carried them (`system` backfilled from options), never invented
+
+### Fixed
+
+- **Failed root runs now carry their error in every export** — `collect()` / `reportToTrace()` / `attach()` / `middleware()` thread the result-envelope error (`BaseResult.error`) onto the root span (which `BaseReport` doesn't carry); `collect()` / `reportToTrace()` gained an optional `rootError` parameter
+- **Per-span exporters now receive every span** — the collector's `dispatch` walks the finalized tree (`walkSpans`), invoking `exportSpan` once per node (a post-completion per-span projection, not live streaming)
+- **`panoptic().middleware()` now works on a supervisor** — the middleware declares a `supervisor` hook map (not only `execute`), so `ai.supervisor({ middleware: [observe.middleware()] })` collects a trace
+- `totalCostUsd()` folds in `cost.reasoning`; the Langfuse exporter `end()`s every observation; the OTel exporter maps `max-iterations` / `awaiting-input` to `UNSET` (a hit cap no longer reads as clean success)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @warlock.js/ai-panoptic
+
+Observability collector + exporters for [`@warlock.js/ai`](../ai).
+
+Panoptic turns the execution reports that every `@warlock.js/ai`
+primitive already produces (the `BaseReport` tree from a `.execute()` /
+`.invoke()` call) into vendor-neutral traces, then fans them out to
+observability backends — OpenTelemetry, Langfuse, or a custom sink.
+
+```bash
+npm install @warlock.js/ai @warlock.js/ai-panoptic
+# plus whichever backend SDK you export to (all OPTIONAL peers):
+npm install @opentelemetry/api @opentelemetry/sdk-trace-base   # OTel
+npm install langfuse                                           # Langfuse
+```
+
+> The backend SDKs are **optional peer dependencies**. They are lazily
+> imported inside the exporter that needs them, so installing
+> `@warlock.js/ai-panoptic` never pulls in an SDK you don't use.
+
+## Quick start
+
+`panoptic(...)` is the one-call entry point. It builds a collector, registers
+your exporters, and hands back a subscriber you can feed three ways — all
+converging on the same collector so each run reaches every exporter exactly once.
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { panoptic, consoleExporter, otelExporter } from "@warlock.js/ai-panoptic";
+
+const observe = panoptic({
+  exporters: [consoleExporter({ tree: true }), otelExporter({ tracerName: "my-app" })],
+});
+
+// 1) Attach to an agent/workflow/supervisor event stream — every run is captured.
+const agent = ai.agent({ model });
+const detach = observe.attach(agent);
+
+await agent.execute("Summarize this");
+
+// ...later, on teardown:
+detach();
+await observe.shutdown();
+```
+
+```ts
+// 2) Or wire it through the agent middleware pipeline:
+const agent = ai.agent({ model, middleware: [observe.middleware()] });
+
+// 3) Or feed a report directly (the orchestrator turn carries no result event):
+const result = await orchestrator.execute(input, { sessionId });
+await observe.collect(result.report);
+```
+
+By default `attach` subscribes to `agent.completed` / `workflow.completed` /
+`supervisor.completed` — the terminal events that fire once per run (completed,
+failed, or cancelled) carrying the finalized report. An observability fault is
+fully isolated: a throwing exporter never crashes or blocks the AI run. See
+[`skills/observe-with-panoptic`](./skills/observe-with-panoptic/SKILL.md) for the
+three feed paths in depth, `completedEvents` overrides, and bring-your-own
+collector/store wiring.
+
+## Concepts
+
+- **Collector** (`CollectorContract`) — the source end. Ingests a core
+  `BaseReport` tree, projects it into a `Trace`, and dispatches that
+  trace to every registered exporter. Wire it into your agents via the
+  `onComplete` report hook.
+- **Trace / TraceSpan** (`Trace`, `TraceSpan`) — the vendor-neutral
+  projection of a `BaseReport`. A `TraceSpan` mirrors one execution node
+  (identity, timing, status, rolled-up `usage`, error) in the span
+  vocabulary shared across observability backends.
+- **Exporter** (`ExporterContract`) — the sink end. Translates traces
+  into a backend's wire format (`export` per trace, optional
+  `exportSpan` for live streaming, `flush` / `shutdown` for draining).
+
+## Exporters
+
+Four exporters ship today, each a factory returning an `ExporterContract`:
+
+```ts
+import {
+  consoleExporter, // zero-dep — print trace summary or full span tree
+  fileExporter,    // zero-dep — append traces as JSON Lines, buffered
+  otelExporter,    // OpenTelemetry — gen_ai.* semantic conventions (lazy @opentelemetry/api)
+  langfuseExporter, // Langfuse — traces + generations (lazy langfuse)
+} from "@warlock.js/ai-panoptic";
+
+collector
+  .use(consoleExporter({ tree: true }))
+  .use(fileExporter({ path: "storage/traces.jsonl" }))
+  .use(otelExporter({ tracerName: "my-app", system: "openai" }))
+  .use(langfuseExporter({ publicKey: "pk-...", secretKey: "sk-..." }));
+```
+
+`otelExporter` and `langfuseExporter` lazily import their SDK, so it stays
+an optional peer — a missing SDK surfaces as a curated "install this"
+error on first export, never a boot-time stack trace. See
+[`skills/export-traces`](./skills/export-traces/SKILL.md) for the full
+mapping (GenAI attribute keys, generation-vs-span rules) and how to write
+a custom exporter.
+
+## Tests
+
+```bash
+npm test
+```
+
+## License
+
+MIT