@warlock.js/ai-panoptic 4.4.0 → 4.6.0

package/esm/store/in-memory-trace-store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory-trace-store.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/store/in-memory-trace-store.ts"],"sourcesContent":["import type { ExporterContract } from \"../contracts/exporter.contract\";\nimport type { Trace } from \"../contracts/trace.type\";\nimport { matchTrace } from \"./match-trace\";\nimport { emptyUsage, sumUsage } from \"./sum-usage\";\nimport type { TraceAggregate } from \"./trace-aggregate.type\";\nimport type { TraceQuery } from \"./trace-query.type\";\nimport type { TraceStoreContract } from \"./trace-store.contract\";\n\n/**\n * Options for {@link createInMemoryTraceStore}.\n */\nexport type InMemoryTraceStoreOptions = {\n  /**\n   * Maximum number of traces to retain. When set and exceeded, the\n   * oldest-ingested trace is evicted (insertion-order FIFO) so the\n   * store stays bounded for long-lived processes. Absent / `0` =\n   * unbounded (keep everything until `clear`).\n   */\n  capacity?: number;\n};\n\n/**\n * In-memory {@link TraceStoreContract} that doubles as an\n * {@link ExporterContract} — register it on a collector\n * (`collector.use(store)`) and it fills as traces complete, then query\n * or aggregate it after the fact.\n *\n * Backed by an insertion-ordered `Map` keyed by `traceId`, giving O(1)\n * `get` / `add` / overwrite and O(n) scans for `query` / `aggregate`\n * (the price of an in-memory store with no secondary indexes — fine for\n * the dev/test and modest-volume runtime use this targets). When a\n * `capacity` is configured, ingesting past the cap evicts the oldest\n * trace.\n *\n * Instantiated fresh per store via {@link createInMemoryTraceStore};\n * callers never see `new`.\n */\nclass InMemoryTraceStore implements TraceStoreContract, ExporterContract {\n  /** Stable exporter id so a collector can dedupe / log this sink. */\n  public readonly name = \"in-memory-trace-store\";\n\n  /**\n   * Retained traces keyed by `traceId`. A `Map` preserves insertion\n   * order, which is what FIFO eviction and newest-first `query` ordering\n   * both rely on.\n   */\n  private readonly traces = new Map<string, Trace>();\n\n  private readonly capacity: number;\n\n  public constructor(options?: InMemoryTraceStoreOptions) {\n    this.capacity = options?.capacity ?? 0;\n  }\n\n  public get size(): number {\n    return this.traces.size;\n  }\n\n  public add(trace: Trace): void {\n    // Re-insert so an overwrite also refreshes insertion position —\n    // keeps \"oldest\" honest for FIFO eviction.\n    this.traces.delete(trace.traceId);\n    this.traces.set(trace.traceId, trace);\n\n    this.evictOverflow();\n  }\n\n  /**\n   * `ExporterContract.export` — a collector dispatches a completed\n   * trace here, which is exactly an `add`. Lets the store be wired into\n   * a collector as a sink without an adapter.\n   */\n  public export(trace: Trace): void {\n    this.add(trace);\n  }\n\n  public get(traceId: string): Trace | undefined {\n    return this.traces.get(traceId);\n  }\n\n  public query(filter?: TraceQuery): Trace[] {\n    const matched: Trace[] = [];\n\n    for (const trace of this.traces.values()) {\n      if (matchTrace(trace, filter)) {\n        matched.push(trace);\n      }\n    }\n\n    return this.sortNewestFirst(matched);\n  }\n\n  public aggregate(filter?: TraceQuery): TraceAggregate {\n    const aggregate: TraceAggregate = {\n      traces: 0,\n      completed: 0,\n      failed: 0,\n      cancelled: 0,\n      usage: emptyUsage(),\n      totalDuration: 0,\n    };\n\n    for (const trace of this.traces.values()) {\n      if (!matchTrace(trace, filter)) {\n        continue;\n      }\n\n      aggregate.traces += 1;\n      aggregate.totalDuration += trace.duration;\n      aggregate.usage = sumUsage(aggregate.usage, trace.usage);\n\n      this.countStatus(aggregate, trace);\n    }\n\n    if (aggregate.usage.cost !== undefined) {\n      aggregate.cost = aggregate.usage.cost;\n    }\n\n    return aggregate;\n  }\n\n  public clear(): void {\n    this.traces.clear();\n  }\n\n  /**\n   * Increment the matching terminal-status counter for one trace.\n   * Non-terminal statuses (`awaiting-input`, `max-iterations`) are\n   * counted in `traces` but tracked by none of the three headline\n   * counters — intentional, those three answer the common\n   * \"succeeded / errored / aborted\" question.\n   */\n  private countStatus(aggregate: TraceAggregate, trace: Trace): void {\n    switch (trace.root.status) {\n      case \"completed\": {\n        aggregate.completed += 1;\n        break;\n      }\n\n      case \"failed\": {\n        aggregate.failed += 1;\n        break;\n      }\n\n      case \"cancelled\": {\n        aggregate.cancelled += 1;\n        break;\n      }\n\n      default: {\n        break;\n      }\n    }\n  }\n\n  /**\n   * Sort matched traces newest-started first. A copy is sorted so the\n   * underlying insertion order (which eviction depends on) is never\n   * disturbed.\n   */\n  private sortNewestFirst(traces: Trace[]): Trace[] {\n    return traces.sort((left, right) => Date.parse(right.startedAt) - Date.parse(left.startedAt));\n  }\n\n  /**\n   * Evict oldest-inserted traces until the store is within `capacity`.\n   * No-op when unbounded. The `Map` iterator yields keys in insertion\n   * order, so the first key is always the oldest.\n   */\n  private evictOverflow(): void {\n    if (this.capacity <= 0) {\n      return;\n    }\n\n    while (this.traces.size > this.capacity) {\n      const oldest = this.traces.keys().next().value;\n\n      if (oldest === undefined) {\n        return;\n      }\n\n      this.traces.delete(oldest);\n    }\n  }\n}\n\n/**\n * Create an in-memory trace store. Optionally bound it with `capacity`\n * for long-lived processes; leave it unset for dev/test where you want\n * every trace retained.\n *\n * @example\n * const store = createInMemoryTraceStore({ capacity: 1000 });\n * collector.use(store);\n * // later:\n * const recentFailures = store.query({ status: \"failed\" });\n * const sessionSpend = store.aggregate({ sessionId });\n */\nexport function createInMemoryTraceStore(options?: InMemoryTraceStoreOptions): TraceStoreContract & ExporterContract {\n  return new InMemoryTraceStore(options);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqCA,IAAM,qBAAN,MAAyE;CAavE,AAAO,YAAY,SAAqC;cAXjC;gCAOG,IAAI,IAAmB;EAK/C,KAAK,WAAW,SAAS,YAAY;CACvC;CAEA,IAAW,OAAe;EACxB,OAAO,KAAK,OAAO;CACrB;CAEA,AAAO,IAAI,OAAoB;EAG7B,KAAK,OAAO,OAAO,MAAM,OAAO;EAChC,KAAK,OAAO,IAAI,MAAM,SAAS,KAAK;EAEpC,KAAK,cAAc;CACrB;;;;;;CAOA,AAAO,OAAO,OAAoB;EAChC,KAAK,IAAI,KAAK;CAChB;CAEA,AAAO,IAAI,SAAoC;EAC7C,OAAO,KAAK,OAAO,IAAI,OAAO;CAChC;CAEA,AAAO,MAAM,QAA8B;EACzC,MAAM,UAAmB,CAAC;EAE1B,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GACrC,IAAI,WAAW,OAAO,MAAM,GAC1B,QAAQ,KAAK,KAAK;EAItB,OAAO,KAAK,gBAAgB,OAAO;CACrC;CAEA,AAAO,UAAU,QAAqC;EACpD,MAAM,YAA4B;GAChC,QAAQ;GACR,WAAW;GACX,QAAQ;GACR,WAAW;GACX,OAAO,WAAW;GAClB,eAAe;EACjB;EAEA,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GAAG;GACxC,IAAI,CAAC,WAAW,OAAO,MAAM,GAC3B;GAGF,UAAU,UAAU;GACpB,UAAU,iBAAiB,MAAM;GACjC,UAAU,QAAQ,SAAS,UAAU,OAAO,MAAM,KAAK;GAEvD,KAAK,YAAY,WAAW,KAAK;EACnC;EAEA,IAAI,UAAU,MAAM,SAAS,QAC3B,UAAU,OAAO,UAAU,MAAM;EAGnC,OAAO;CACT;CAEA,AAAO,QAAc;EACnB,KAAK,OAAO,MAAM;CACpB;;;;;;;;CASA,AAAQ,YAAY,WAA2B,OAAoB;EACjE,QAAQ,MAAM,KAAK,QAAnB;GACE,KAAK;IACH,UAAU,aAAa;IACvB;GAGF,KAAK;IACH,UAAU,UAAU;IACpB;GAGF,KAAK;IACH,UAAU,aAAa;IACvB;GAGF,SACE;EAEJ;CACF;;;;;;CAOA,AAAQ,gBAAgB,QAA0B;EAChD,OAAO,OAAO,MAAM,MAAM,UAAU,KAAK,MAAM,MAAM,SAAS,IAAI,KAAK,MAAM,KAAK,SAAS,CAAC;CAC9F;;;;;;CAOA,AAAQ,gBAAsB;EAC5B,IAAI,KAAK,YAAY,GACnB;EAGF,OAAO,KAAK,OAAO,OAAO,KAAK,UAAU;GACvC,MAAM,SAAS,KAAK,OAAO,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;GAEzC,IAAI,WAAW,QACb;GAGF,KAAK,OAAO,OAAO,MAAM;EAC3B;CACF;AACF;;;;;;;;;;;;;AAcA,SAAgB,yBAAyB,SAA4E;CACnH,OAAO,IAAI,mBAAmB,OAAO;AACvC"}
+{"version":3,"file":"in-memory-trace-store.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/store/in-memory-trace-store.ts"],"sourcesContent":["import type { ExporterContract } from \"../contracts/exporter.contract\";\nimport type { Trace } from \"../contracts/trace.type\";\nimport { matchTrace } from \"./match-trace\";\nimport { emptyUsage, sumUsage } from \"./sum-usage\";\nimport type { TraceAggregate } from \"./trace-aggregate.type\";\nimport type { TraceQuery } from \"./trace-query.type\";\nimport type { TraceStoreContract } from \"./trace-store.contract\";\n\n/**\n * Options for {@link createInMemoryTraceStore}.\n */\nexport type InMemoryTraceStoreOptions = {\n  /**\n   * Maximum number of traces to retain. When set and exceeded, the\n   * oldest-ingested trace is evicted (insertion-order FIFO) so the\n   * store stays bounded for long-lived processes. Absent / `0` =\n   * unbounded (keep everything until `clear`).\n   */\n  capacity?: number;\n};\n\n/**\n * In-memory {@link TraceStoreContract} that doubles as an\n * {@link ExporterContract} — register it on a collector\n * (`collector.use(store)`) and it fills as traces complete, then query\n * or aggregate it after the fact.\n *\n * Backed by an insertion-ordered `Map` keyed by `traceId`, giving O(1)\n * `get` / `add` / overwrite and O(n) scans for `query` / `aggregate`\n * (the price of an in-memory store with no secondary indexes — fine for\n * the dev/test and modest-volume runtime use this targets). When a\n * `capacity` is configured, ingesting past the cap evicts the oldest\n * trace.\n *\n * Instantiated fresh per store via {@link createInMemoryTraceStore};\n * callers never see `new`.\n */\nclass InMemoryTraceStore implements TraceStoreContract, ExporterContract {\n  /** Stable exporter id so a collector can dedupe / log this sink. */\n  public readonly name = \"in-memory-trace-store\";\n\n  /**\n   * Retained traces keyed by `traceId`. A `Map` preserves insertion\n   * order, which is what FIFO eviction and newest-first `query` ordering\n   * both rely on.\n   */\n  private readonly traces = new Map<string, Trace>();\n\n  private readonly capacity: number;\n\n  public constructor(options?: InMemoryTraceStoreOptions) {\n    this.capacity = options?.capacity ?? 0;\n  }\n\n  public get size(): number {\n    return this.traces.size;\n  }\n\n  public add(trace: Trace): void {\n    // Re-insert so an overwrite also refreshes insertion position —\n    // keeps \"oldest\" honest for FIFO eviction.\n    this.traces.delete(trace.traceId);\n    this.traces.set(trace.traceId, trace);\n\n    this.evictOverflow();\n  }\n\n  /**\n   * `ExporterContract.export` — a collector dispatches a completed\n   * trace here, which is exactly an `add`. Lets the store be wired into\n   * a collector as a sink without an adapter.\n   */\n  public export(trace: Trace): void {\n    this.add(trace);\n  }\n\n  public get(traceId: string): Trace | undefined {\n    return this.traces.get(traceId);\n  }\n\n  public query(filter?: TraceQuery): Trace[] {\n    const matched: Trace[] = [];\n\n    for (const trace of this.traces.values()) {\n      if (matchTrace(trace, filter)) {\n        matched.push(trace);\n      }\n    }\n\n    return this.sortNewestFirst(matched);\n  }\n\n  public aggregate(filter?: TraceQuery): TraceAggregate {\n    const aggregate: TraceAggregate = {\n      traces: 0,\n      completed: 0,\n      failed: 0,\n      cancelled: 0,\n      usage: emptyUsage(),\n      totalDuration: 0,\n    };\n\n    for (const trace of this.traces.values()) {\n      if (!matchTrace(trace, filter)) {\n        continue;\n      }\n\n      aggregate.traces += 1;\n      aggregate.totalDuration += trace.duration;\n      aggregate.usage = sumUsage(aggregate.usage, trace.usage);\n\n      this.countStatus(aggregate, trace);\n    }\n\n    if (aggregate.usage.cost !== undefined) {\n      aggregate.cost = aggregate.usage.cost;\n    }\n\n    return aggregate;\n  }\n\n  public clear(): void {\n    this.traces.clear();\n  }\n\n  /**\n   * Increment the matching terminal-status counter for one trace.\n   * Non-terminal statuses (`awaiting-input`, `max-iterations`) are\n   * counted in `traces` but tracked by none of the three headline\n   * counters — intentional, those three answer the common\n   * \"succeeded / errored / aborted\" question.\n   */\n  private countStatus(aggregate: TraceAggregate, trace: Trace): void {\n    switch (trace.root.status) {\n      case \"completed\": {\n        aggregate.completed += 1;\n        break;\n      }\n\n      case \"failed\": {\n        aggregate.failed += 1;\n        break;\n      }\n\n      case \"cancelled\": {\n        aggregate.cancelled += 1;\n        break;\n      }\n\n      default: {\n        break;\n      }\n    }\n  }\n\n  /**\n   * Sort matched traces newest-started first. A copy is sorted so the\n   * underlying insertion order (which eviction depends on) is never\n   * disturbed.\n   */\n  private sortNewestFirst(traces: Trace[]): Trace[] {\n    return traces.sort((left, right) => Date.parse(right.startedAt) - Date.parse(left.startedAt));\n  }\n\n  /**\n   * Evict oldest-inserted traces until the store is within `capacity`.\n   * No-op when unbounded. The `Map` iterator yields keys in insertion\n   * order, so the first key is always the oldest.\n   */\n  private evictOverflow(): void {\n    if (this.capacity <= 0) {\n      return;\n    }\n\n    while (this.traces.size > this.capacity) {\n      const oldest = this.traces.keys().next().value;\n\n      if (oldest === undefined) {\n        return;\n      }\n\n      this.traces.delete(oldest);\n    }\n  }\n}\n\n/**\n * Create an in-memory trace store. Optionally bound it with `capacity`\n * for long-lived processes; leave it unset for dev/test where you want\n * every trace retained.\n *\n * @example\n * const store = createInMemoryTraceStore({ capacity: 1000 });\n * collector.use(store);\n * // later:\n * const recentFailures = store.query({ status: \"failed\" });\n * const sessionSpend = store.aggregate({ sessionId });\n */\nexport function createInMemoryTraceStore(options?: InMemoryTraceStoreOptions): TraceStoreContract & ExporterContract {\n  return new InMemoryTraceStore(options);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqCA,IAAM,qBAAN,MAAyE;;CAEvE,AAAgB,OAAO;;;;;;CAOvB,AAAiB,yBAAS,IAAI,IAAmB;CAEjD,AAAiB;CAEjB,AAAO,YAAY,SAAqC;EACtD,KAAK,WAAW,SAAS,YAAY;CACvC;CAEA,IAAW,OAAe;EACxB,OAAO,KAAK,OAAO;CACrB;CAEA,AAAO,IAAI,OAAoB;EAG7B,KAAK,OAAO,OAAO,MAAM,OAAO;EAChC,KAAK,OAAO,IAAI,MAAM,SAAS,KAAK;EAEpC,KAAK,cAAc;CACrB;;;;;;CAOA,AAAO,OAAO,OAAoB;EAChC,KAAK,IAAI,KAAK;CAChB;CAEA,AAAO,IAAI,SAAoC;EAC7C,OAAO,KAAK,OAAO,IAAI,OAAO;CAChC;CAEA,AAAO,MAAM,QAA8B;EACzC,MAAM,UAAmB,CAAC;EAE1B,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GACrC,IAAI,WAAW,OAAO,MAAM,GAC1B,QAAQ,KAAK,KAAK;EAItB,OAAO,KAAK,gBAAgB,OAAO;CACrC;CAEA,AAAO,UAAU,QAAqC;EACpD,MAAM,YAA4B;GAChC,QAAQ;GACR,WAAW;GACX,QAAQ;GACR,WAAW;GACX,OAAO,WAAW;GAClB,eAAe;EACjB;EAEA,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GAAG;GACxC,IAAI,CAAC,WAAW,OAAO,MAAM,GAC3B;GAGF,UAAU,UAAU;GACpB,UAAU,iBAAiB,MAAM;GACjC,UAAU,QAAQ,SAAS,UAAU,OAAO,MAAM,KAAK;GAEvD,KAAK,YAAY,WAAW,KAAK;EACnC;EAEA,IAAI,UAAU,MAAM,SAAS,QAC3B,UAAU,OAAO,UAAU,MAAM;EAGnC,OAAO;CACT;CAEA,AAAO,QAAc;EACnB,KAAK,OAAO,MAAM;CACpB;;;;;;;;CASA,AAAQ,YAAY,WAA2B,OAAoB;EACjE,QAAQ,MAAM,KAAK,QAAnB;GACE,KAAK;IACH,UAAU,aAAa;IACvB;GAGF,KAAK;IACH,UAAU,UAAU;IACpB;GAGF,KAAK;IACH,UAAU,aAAa;IACvB;GAGF,SACE;EAEJ;CACF;;;;;;CAOA,AAAQ,gBAAgB,QAA0B;EAChD,OAAO,OAAO,MAAM,MAAM,UAAU,KAAK,MAAM,MAAM,SAAS,IAAI,KAAK,MAAM,KAAK,SAAS,CAAC;CAC9F;;;;;;CAOA,AAAQ,gBAAsB;EAC5B,IAAI,KAAK,YAAY,GACnB;EAGF,OAAO,KAAK,OAAO,OAAO,KAAK,UAAU;GACvC,MAAM,SAAS,KAAK,OAAO,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;GAEzC,IAAI,WAAW,QACb;GAGF,KAAK,OAAO,OAAO,MAAM;EAC3B;CACF;AACF;;;;;;;;;;;;;AAcA,SAAgB,yBAAyB,SAA4E;CACnH,OAAO,IAAI,mBAAmB,OAAO;AACvC"}

package/esm/store/index.d.mts

@@ -1,6 +1,7 @@
 import { TraceAggregate } from "./trace-aggregate.type.mjs";
 import { TraceQuery } from "./trace-query.type.mjs";
 import { TraceStoreContract } from "./trace-store.contract.mjs";
+import { CacheDriverInput, CacheTraceStoreHandle, CacheTraceStoreOptions, createCacheTraceStore } from "./cache-trace-store.mjs";
 import { InMemoryTraceStoreOptions, createInMemoryTraceStore } from "./in-memory-trace-store.mjs";
 import { matchTrace } from "./match-trace.mjs";
 import { emptyUsage, sumUsage } from "./sum-usage.mjs";

package/esm/store/index.mjs

@@ -1,5 +1,6 @@
 import { matchTrace } from "./match-trace.mjs";
 import { emptyUsage, sumUsage } from "./sum-usage.mjs";
+import { createCacheTraceStore } from "./cache-trace-store.mjs";
 import { createInMemoryTraceStore } from "./in-memory-trace-store.mjs";
 
 export {  };

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 ---
 name: export-traces
-description: 'Send @warlock.js/ai-panoptic traces to an observability backend via pluggable exporters. Triggers: `consoleExporter`, `fileExporter`, `otelExporter`, `langfuseExporter`, `ExporterContract`, `toGenAiAttributes`, `walkSpans`, `totalCostUsd`, `GEN_AI_ATTRIBUTES`, `WARLOCK_ATTRIBUTES`, `reportToTrace`, `reportToSpan`, `extractSpanAttributes`, `normalizeError`, `formatSpanLine`, `createPanopticMiddleware`; ''export AI traces to OpenTelemetry'', ''send traces to Langfuse'', ''log traces to console / a file'', ''gen_ai semantic conventions'', ''write a custom exporter''; typical import `import { otelExporter, langfuseExporter, consoleExporter, fileExporter } from "@warlock.js/ai-panoptic"`. Skip: wiring the subscriber/collector into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`; the core report shape — `@warlock.js/ai/run-ai-agent/SKILL.md`.'
+description: 'Send @warlock.js/ai-panoptic traces to an observability backend via pluggable exporters, including capturing prompt/response content onto spans. Triggers: `consoleExporter`, `fileExporter`, `otelExporter`, `langfuseExporter`, `ExporterContract`, `ContentCaptureOptions`, `captureContent`, `redactContent`, `fullHistory`, `ContentRedactor`, `toGenAiAttributes`, `walkSpans`, `totalCostUsd`, `GEN_AI_ATTRIBUTES`, `WARLOCK_ATTRIBUTES`, `reportToTrace`, `reportToSpan`, `extractSpanAttributes`, `normalizeError`, `formatSpanLine`, `createPanopticMiddleware`; ''export AI traces to OpenTelemetry'', ''send traces to Langfuse'', ''log traces to console / a file'', ''capture the full prompt/conversation onto a span'', ''gen_ai semantic conventions'', ''write a custom exporter''; typical import `import { otelExporter, langfuseExporter, consoleExporter, fileExporter } from "@warlock.js/ai-panoptic"`. Skip: wiring the subscriber/collector into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`; the core report shape — `@warlock.js/ai/run-ai-agent/SKILL.md`.'
 ---
 
 # Export traces — the sink end of Panoptic
@@ -102,6 +102,38 @@ collector.use(langfuseExporter({ client: myLangfuse }));
 - Children nest under their parent observation; timing, `version`, and status (failed → `ERROR` level) are mapped.
 - `flush()` / `shutdown()` delegate to the client's `flushAsync()` / `shutdownAsync()` — call `collector.shutdown()` on teardown so buffered observations are sent.
 
+## Content capture — what reaches the `input` / `output` fields
+
+Exporters surface `span.input` / `span.output` (console `in:` / `out:`, file JSON, OTel `gen_ai.prompt` / `gen_ai.completion`, Langfuse native `input` / `output`) only when **content capture** is enabled on the collector or subscriber. It's `ContentCaptureOptions`, set on `createCollector(...)` or `panoptic(...)`:
+
+```ts
+panoptic({
+  exporters: [langfuseExporter({ /* ... */ })],
+  captureContent: true,                 // copy prompts/responses + tool args/results onto spans
+  redactContent: (value, { field }) =>  // optional masker, per value
+    field === "input" ? "[redacted]" : value,
+  fullHistory: true,                    // emit the WHOLE conversation as span.input (see below)
+});
+```
+
+Off by default — payloads are large and frequently sensitive. With `captureContent`, an agent span's `input` is a `[system, user]` chat array (or the bare user string when there's no system prompt) and its `output` is the last non-empty trip's text; a tool span carries its call args + result.
+
+### `fullHistory` — emit the entire `CapturedMessage[]`
+
+`fullHistory: true` replaces the `[system, user]` first-trip array on `span.input` with the agent's **complete assembled conversation** — every trip, every role (system / user / assistant / tool). The `output` stays the final response text.
+
+```ts
+// upstream: the agent run MUST opt into capturing its messages
+const result = await agent.execute(input, { captureMessages: true });
+//                                          ^ core @warlock.js/ai — makes report.messages present
+
+panoptic({ exporters: [...], captureContent: true, fullHistory: true });
+```
+
+**Requires the upstream `captureMessages`.** `fullHistory` reads `report.messages` (the captured `CapturedMessage[]`). When the run did NOT opt into `captureMessages`, `report.messages` is absent and the branch **degrades gracefully** to today's first-trip `[system, user]` capture — never an error, just less history. The whole array is passed through `ContentRedactor` as a single value, so masking still applies to captured history.
+
+Reach for `fullHistory` when a backend (Langfuse) should show the full multi-turn / tool-loop transcript a run actually sent, not just its opening prompt.
+
 ## Shared utilities
 
 Reusable when authoring a **custom exporter**:
@@ -164,12 +196,58 @@ Reach for `reportToTrace` when you already hold a finished `result.report` and w
 
 ---
 name: observe-with-panoptic
-description: 'Wire @warlock.js/ai-panoptic into an agent/workflow/supervisor/orchestrator with the one-call `panoptic({ exporters })` subscriber. Triggers: `panoptic`, `Panoptic`, `PanopticOptions`, `.attach`, `.middleware`, `.collect`, `.toTrace`, `observe.attach(agent)`, `panoptic().middleware()`, `completedEvents`, `middlewareName`; ''observe a warlock agent'', ''trace an agent run'', ''attach observability to a workflow/supervisor'', ''add a tracing middleware'', ''collect an orchestrator turn report'', ''wire OTel/Langfuse into my agent''; typical import `import { panoptic } from "@warlock.js/ai-panoptic"`. Skip: writing/choosing an exporter (the sink end) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; the core report shape / running the agent itself — `@warlock.js/ai/run-ai-agent/SKILL.md`.'
+description: 'Wire @warlock.js/ai-panoptic into an agent/workflow/supervisor/orchestrator — declaratively via `ai.config({ panoptic })` (registers panoptic on core''s Observer seam) or with the one-call `panoptic({ exporters })` subscriber. Triggers: `panoptic`, `Panoptic`, `PanopticOptions`, `PanopticConfig`, `ai.config({ panoptic })`, `observeAll`, per-flow `observe`, `FlowObserveOption`, `registerObserver`, `Observer`, `.attach`, `.middleware`, `.collect`, `.toTrace`, `observe.attach(agent)`, `panoptic().middleware()`, `completedEvents`, `middlewareName`; ''observe a warlock agent'', ''trace an agent run'', ''attach observability to a workflow/supervisor'', ''observe every flow by default'', ''add a tracing middleware'', ''collect an orchestrator turn report'', ''wire OTel/Langfuse into my agent''; typical import `import { ai } from "@warlock.js/ai"` + `import "@warlock.js/ai-panoptic"` (or `import { panoptic } from "@warlock.js/ai-panoptic"`). Skip: the zero-setup local dashboard — `@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md`; writing/choosing an exporter (the sink end) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; the core report shape / running the agent itself — `@warlock.js/ai/run-ai-agent/SKILL.md`.'
 ---
 
 # Observe a run with Panoptic — the one-call subscriber
 
-`panoptic(...)` is the entry point. It builds a collector, registers your exporters on it, and hands back a subscriber with **three ways to feed traces** in. All three converge on the same collector, so each run reaches every exporter exactly once.
+There are two levels. **Declarative** (`ai.config({ panoptic })`) is the high-level path: panoptic registers itself on core's generic `Observer` seam and every observed flow routes its report in automatically — no per-target wiring. **Imperative** (`panoptic(...)`) is the underlying subscriber, with three explicit feed paths. The declarative path is sugar over the imperative one; both reuse the same collection pipeline.
+
+## Declarative — `ai.config({ panoptic })` + the Observer seam
+
+The simplest wiring. Importing `@warlock.js/ai-panoptic` (even bare, for side effects) subscribes panoptic to core's config seam; a later `ai.config({ panoptic })` then builds the collector and **registers it once on core's `Observer` registry** via `registerObserver`. Core itself never imports panoptic — it depends only on the structural `Observer` interface (`{ collect(report) }`), the dependency inversion that keeps the two sides decoupled.
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-panoptic"; // side-effect wiring — do this once at boot
+
+ai.config({
+  panoptic: {
+    exporters: [consoleExporter()],   // optional; a store-shaped exporter also feeds the dashboard
+    observeAll: true,                 // observe every flow by default
+    dashboard: true,                  // optional local viewer — see use-local-dashboard
+  },
+});
+```
+
+`PanopticConfig`: `exporters?` (the collector's sinks), `observeAll?` (default `false`), `dashboard?` (`boolean | DashboardOptions`). Applying it is **idempotent** — the observer registers once, the dashboard starts at most once; repeat `ai.config(...)` merges only refresh `observeAll`.
+
+### `observeAll` + per-flow `observe`
+
+Once a collector is registered, which flows actually route to it is controlled by core's `observe` seam:
+
+| Setting | Effect |
+|---|---|
+| `observeAll: true` (config) | Every `ai.agent` / `ai.workflow` / `ai.supervisor` / `ai.team` that left `observe` unset routes its completed report to the registered observers. |
+| `observe: true` (per-flow) | Force-observe **this** flow even when `observeAll` is off → the globally registered observers. |
+| `observe: false` (per-flow) | Opt **this** flow out entirely, even when `observeAll` is on. |
+| `observe: <Observer>` (per-flow) | A **flow-local** collector — only this flow's report, routed only to it (the global observers are skipped). A panoptic flow-local collector implements `Observer`, so pass it directly. |
+| (unset, `observeAll: false`) | Not observed — opt-in default, identical to legacy behavior. |
+
+```ts
+ai.agent({ model, observe: true });                       // always traced
+ai.workflow({ name: "billing", steps, observe: true });   // always traced
+ai.supervisor({ name: "triage", ..., observe: false });   // never traced, even under observeAll
+
+const flowLocal = panoptic({ exporters: [fileExporter({ path: "billing.jsonl" })] });
+ai.team({ name: "research", ..., observe: flowLocal });   // only this flow, only this collector
+```
+
+The flow awaits each observer's `collect`, and a throwing observer is **swallowed** — observability never breaks the run (mirrors `onUsage` / `onComplete`). `observe` lives on **all four** flow configs — `ai.agent`, `ai.workflow`, `ai.supervisor`, and `ai.team` (the agent additionally supports the imperative `attach()` / `middleware()` paths below).
+
+## Imperative — `panoptic(...)`, the one-call subscriber
+
+`panoptic(...)` builds a collector, registers your exporters on it, and hands back a subscriber with **three ways to feed traces** in. All three converge on the same collector, so each run reaches every exporter exactly once. Use it when you want explicit control, a flow-local collector, or to wire a target the declarative seam doesn't cover (the orchestrator).
 
 ```ts
 import { panoptic } from "@warlock.js/ai-panoptic";
@@ -287,6 +365,7 @@ Add exporters after construction with `observe.use(exporter)` (chainable, dedupe
 
 ## See also
 
+- [`@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md`](@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md) — the zero-setup local viewer the `ai.config({ panoptic: { dashboard } })` switch starts over the collector's store.
 - [`@warlock.js/ai-panoptic/export-traces/SKILL.md`](@warlock.js/ai-panoptic/export-traces/SKILL.md) — the sink end: choosing/writing an exporter, the `gen_ai.*` / `warlock.*` attribute mapping.
 - [`@warlock.js/ai-panoptic/query-traces/SKILL.md`](@warlock.js/ai-panoptic/query-traces/SKILL.md) — retaining traces in the queryable in-memory store and slicing them (`query` / `aggregate` / `capacity`).
 - [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — running the agent and the `BaseReport` shape Panoptic consumes.
@@ -296,7 +375,7 @@ Add exporters after construction with `observe.use(exporter)` (chainable, dedupe
 
 ---
 name: query-traces
-description: 'Retain @warlock.js/ai-panoptic traces in a queryable in-memory store and slice them after the fact — get one run by id, list a session, filter failed runs in a window, roll up usage + cost. Triggers: `createInMemoryTraceStore`, `TraceStoreContract`, `TraceQuery`, `TraceAggregate`, `InMemoryTraceStoreOptions`, `store.query`, `store.aggregate`, `store.get`, `store.add`, `store.clear`, `store.size`, `capacity`, `sumUsage`, `emptyUsage`, `matchTrace`; ''query collected traces'', ''aggregate AI cost per session'', ''how much did this session spend'', ''list failed runs'', ''retain traces in memory'', ''roll up token usage''; typical import `import { createInMemoryTraceStore } from "@warlock.js/ai-panoptic"`. Skip: sending traces to an external backend (OTel/Langfuse/console/file) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; wiring the subscriber into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`.'
+description: 'Retain @warlock.js/ai-panoptic traces in a queryable store — in-memory, or cache-backed so they survive a process restart — and slice them after the fact: get one run by id, list a session, filter failed runs in a window, roll up usage + cost. Triggers: `createInMemoryTraceStore`, `createCacheTraceStore`, `CacheTraceStoreHandle`, `CacheTraceStoreOptions`, `CacheDriverInput`, `store.ready`, `TraceStoreContract`, `TraceQuery`, `TraceAggregate`, `InMemoryTraceStoreOptions`, `store.query`, `store.aggregate`, `store.get`, `store.add`, `store.clear`, `store.size`, `capacity`, `prefix`, `onError`, `sumUsage`, `emptyUsage`, `matchTrace`; ''query collected traces'', ''aggregate AI cost per session'', ''how much did this session spend'', ''list failed runs'', ''retain traces in memory'', ''persist traces across a restart'', ''cache-backed trace store'', ''Redis trace store'', ''roll up token usage''; typical import `import { createInMemoryTraceStore, createCacheTraceStore } from "@warlock.js/ai-panoptic"`. Skip: sending traces to an external backend (OTel/Langfuse/console/file) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; wiring the subscriber into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`.'
 ---
 
 # Query traces — the in-memory queryable store
@@ -426,6 +505,57 @@ Overwriting an existing `traceId` refreshes its insertion position, so a re-coll
 
 > The in-memory store has no secondary indexes: `get` / `add` are O(1), `query` / `aggregate` are O(n) scans. That is the right trade-off for dev/test and modest-volume runtime use. For high-volume or durable retention, write a custom `TraceStoreContract` (or export to a backend with [`export-traces`](@warlock.js/ai-panoptic/export-traces/SKILL.md)) backed by a real datastore.
 
+## Persisting across a restart — `createCacheTraceStore`
+
+The in-memory store loses everything when the process exits. `createCacheTraceStore(cache, options?)` is a **durable** `TraceStoreContract` (and `ExporterContract`) backed by any `@warlock.js/cache` `CacheDriver` — Redis, file, Postgres, … — so traces survive a restart and the dashboard re-opens with history intact.
+
+```ts
+import { createCacheTraceStore } from "@warlock.js/ai-panoptic";
+import { RedisCacheDriver } from "@warlock.js/cache";
+
+// A driver instance, or a (possibly async) FACTORY resolved lazily on first
+// use — the factory form defers the Redis connect until the first trace is
+// collected, so module import stays connection-free.
+const store = createCacheTraceStore(async () => {
+  const driver = new RedisCacheDriver();
+  await driver.connect();
+  return driver;
+});
+
+await store.ready();   // hydrate the in-memory mirror from a prior run
+collector.use(store);  // fills as traces complete; reads stay synchronous
+
+const failed = store.query({ status: "failed" }); // queryable like any store
+```
+
+**Write-through over a sync contract.** The store keeps the same insertion-ordered in-memory **mirror** the in-memory store uses and serves every read (`get` / `query` / `aggregate` / `size`) from it synchronously — the dashboard polls these and can't await a cache. Writes go **through**: `add` updates the mirror immediately, then *fire-and-forget* persists the trace + a newest-first index to the cache. So:
+
+- **Reads never wait on the cache** — the mirror is the runtime source of truth; the cache is the durable backing store.
+- **A flaky cache never throws into the hot path** — a rejected write is routed to the optional `onError` hook and swallowed; the trace stays visible in the mirror for the life of the process, it just won't survive a restart.
+- **`ready()` re-hydrates** the mirror from the persisted index on startup (await it once — `ai.config({ panoptic: { cache } })` does this for you before serving the dashboard).
+
+```ts
+type CacheDriverInput =
+  | CacheDriver           // a live driver
+  | (() => CacheDriver | Promise<CacheDriver>); // lazy (sync or async) factory
+
+type CacheTraceStoreOptions = {
+  prefix?: string;   // key namespace; per-trace keys `${prefix}:trace:${id}`,
+                     // index at `${prefix}:index`. Default "panoptic".
+  capacity?: number; // FIFO cap (oldest-ingested evicted from cache + mirror);
+                     // absent / 0 = unbounded.
+  onError?: (error: unknown) => void; // swallowed cache-write failures land here.
+};
+
+type CacheTraceStoreHandle = TraceStoreContract & ExporterContract & {
+  ready(): Promise<void>; // hydrate the mirror from the cache on startup
+};
+```
+
+Ordering uses an **internal monotonic counter**, not `Date.now()`, so the persisted index stays a stable total order even when many traces land in the same millisecond — FIFO eviction stays honest across a restart.
+
+> The usual path is declarative: `ai.config({ panoptic: { cache, dashboard: true } })` constructs this store, awaits `ready()`, and wires it under the dashboard for you — see [`use-local-dashboard/SKILL.md`](@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md). Reach for `createCacheTraceStore` directly only when you manage the store / collector yourself.
+
 ## Summing usage yourself
 
 `sumUsage` / `emptyUsage` are the pure folds `aggregate` is built on — reuse them to roll a `Usage` set the store didn't produce (e.g. a list of traces you filtered by hand):
@@ -448,3 +578,220 @@ for (const trace of store.query({ sessionId })) {
 - [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — the `BaseReport` the collector projects into the `Trace` this store retains.
 
 
+## use-local-dashboard  `@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md`
+
+---
+name: use-local-dashboard
+description: 'Run the zero-setup local Panoptic dashboard — a loopback `node:http` server over a trace store served from `ai.config({ panoptic: { dashboard } })`, with a two-pane call-tree + metadata UI (light/dark/system theme, search/filter, session + prompt-version grouping, cost heatmap, Gantt timeline, errors filter, hash deep-links) and an optional cache-backed persistent store. Triggers: `dashboard`, `DashboardOptions`, `DashboardHandle`, `ai.config({ panoptic })`, `panoptic.dashboard`, `panoptic.cache`, `port: 4319`, `basePath`, `open`, `/api/traces`, `/api/aggregate`, `/api/traces/:id`, `createRequestHandler`, `dashboardHtml`, `ServeConfig`, `TraceStoreContract`, `createCacheTraceStore`, theme, dark mode, call tree, metadata panel, cost heatmap, timeline / Gantt, errors only, deep-link, group by session, prompt version, group by type, type stats panel, started / ended timestamps, team type; ''open a local AI trace dashboard'', ''view agent traces in the browser'', ''self-hosted panoptic UI'', ''inspect traces without Langfuse'', ''spin up a dev observability server'', ''dark mode dashboard'', ''persist traces across restart'', ''group traces by session / prompt version / type'', ''cost heatmap'', ''timeline / waterfall view'', ''filter failed runs in the dashboard'', ''per-type stats panel''; typical import `import { ai } from "@warlock.js/ai"` + `import "@warlock.js/ai-panoptic"`. Skip: shipping traces to a backend (OTel / Langfuse / file) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; the queryable store API the dashboard reads — `@warlock.js/ai-panoptic/query-traces/SKILL.md`; wiring the subscriber by hand — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`.'
+---
+
+# The local Panoptic dashboard — zero-setup trace viewing
+
+A loopback-only `node:http` server that serves one self-contained HTML page polling a read-only JSON API over a trace store. No external backend and no build step; it binds `127.0.0.1` with no auth by default, and gains optional bearer-token auth + a Host allowlist (`authToken` / `allowedHosts`, **required** off-loopback). The store is the live object the collector fills, so each poll reflects the latest completed traces.
+
+## The documented path — `ai.config({ panoptic: { dashboard } })`
+
+You almost never call `dashboard(...)` directly. Set it declaratively and the side-effect import wires the store, the collector, and the server for you:
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-panoptic"; // side-effect: subscribes panoptic to the config seam
+
+ai.config({
+  panoptic: {
+    dashboard: true,    // serve on http://127.0.0.1:4319/
+    observeAll: true,   // route every workflow/supervisor/team run to the collector
+  },
+});
+```
+
+`dashboard: true` uses the defaults. Pass an object to override:
+
+```ts
+ai.config({
+  panoptic: {
+    exporters: [createInMemoryTraceStore({ capacity: 5000 })],
+    dashboard: { port: 4319, open: true, title: "My App — AI traces" },
+    observeAll: true,
+  },
+});
+```
+
+**Where the dashboard reads its traces from.** It needs a queryable store (a `TraceStoreContract`). Panoptic resolves one in this order:
+
+1. The first **store-shaped exporter** in `config.exporters` — `createInMemoryTraceStore()` doubles as an `ExporterContract`, so a store passed in `exporters` is reused (captured AND served from the same object).
+2. If none was supplied but `dashboard` is set, panoptic creates a fresh in-memory store and registers it as an exporter so the collector fills it.
+
+So `dashboard: true` with no exporters Just Works — you get a store for free. Supply your own when you want a capacity cap or want to `query` / `aggregate` it from app code too.
+
+**Idempotent.** Applying the config is safe on every `ai.config(...)` merge: the collector is registered as a core `Observer` exactly once and the dashboard is started at most once. Repeat calls only refresh the `observeAll` flag (latest config wins). `panoptic` undefined in the config is a no-op.
+
+## What the UI shows
+
+The page is one self-contained, dependency-free vanilla-JS file (no bundler, no framework, works offline). It polls the JSON API every 2s and renders:
+
+- **Header** — the Warlock logo + your `title`, the `TraceAggregate` headline counts (traces / completed / failed / cancelled), tokens as **`↓input · ↑output · total`**, total cost, an **errors-only** toggle, a **search** box, and a **light / dark / system** theme switch (persisted to `localStorage`, so the choice survives a reload; `system` follows the OS `prefers-color-scheme`).
+- **Trace list** — newest-first clickable master rows, each led by a **colour-coded Title-case type label** (`Supervisor` / `Team` / `Workflow` / `Agent` / `Tool` / …; `ai.team` reports its own `team` type rather than `supervisor`, so it groups, filters, and labels separately). An optional **group-by-session** view collapses runs under collapsible session headers; a **group-by-prompt** view does the same over the `name@version` prompt key (see *Prompt-version linkage* below); a **group-by-type** view buckets the list by root type under collapsible `Type (N)` headers (`Agent (12)`, `Team (3)`, …). The three groupings are mutually exclusive.
+- **Two-pane drawer** (click a row) — a collapsible **nested call tree** on the left and the **selected node's detail** on the right: rich structured input/output (chat bubbles / key-value / Markdown), a per-node **token breakdown** (`↓in · ↑out · total`), the node's **rollup cost** (its own cost, else the sum of its children — so wrapper nodes that carry tokens but no cost don't double-count), and a **metadata panel** with humanized keys (`Supervisor Terminated By`, `Span ID` — not raw `supervisor.terminatedBy`), and **started** / **ended** wall-clock timestamps (`28 Jun 2026 03:16 PM` — named month, 12-hour, minute precision) alongside the elapsed duration. Zero-valued token/cost rows are hidden so the panel stays readable.
+- **Cost heatmap** — every tree node and trace row carries a left accent tinted by its rollup cost relative to the trace's most expensive node, with a small legend, so the spend hot-spots jump out at a glance.
+- **Timeline view** — the drawer's left pane toggles between the nested call **Tree** and a Gantt **Timeline** (each span drawn at its offset from the root start, width = duration, critical path highlighted).
+- **Stats panel** — a header **Stats** toggle shows a per-type aggregate table above the trace list, one row per root type (`Agent` / `Team` / `Workflow` / …) with Count, Failed (rate), p50 / p95 latency, total Tokens, and total Cost, computed over the active filtered set. Distinct from the headline counts in the header.
+
+All UI state (selected trace, selected span, collapsed nodes, theme, filters) lives in JS, **not** the DOM, so the 2s poll never disturbs an open drawer.
+
+### Filtering & grouping (all client-side over the polled list)
+
+The list narrows entirely in the browser — no server round-trip per keystroke:
+
+- **Search** — free-text, case-insensitive, matched against root span name + session id.
+- **Status / type chips** — restrict to selected terminal statuses or executable types. Chip, badge, drawer, and group-header labels are **Title-cased** everywhere (`Completed`, `Workflow`, `Team`); the underlying filter keys stay lowercase (`completed`, `workflow`, `team`).
+- **Errors-only** — header toggle that keeps just `failed` / `cancelled` runs.
+- **Session chip** — exact `sessionId`; **prompt chip** — exact `name@version` key.
+- **Group-by-type** — buckets the list by root type under `Type (N)` headers; mutually exclusive with group-by-session and group-by-prompt.
+
+The pure matching/grouping rules are unit-tested in `trace-filter.ts` and mirrored 1:1 by the inlined dashboard JS, exported for reuse / your own list views:
+
+```ts
+import {
+  filterTraces, matchesFilter, groupBySession, rollupCost, maxNodeCost, heatIntensity,
+  type TraceFilter, type SessionGroup,
+} from "@warlock.js/ai-panoptic"; // dashboard helpers, re-exported
+
+const failed = filterTraces(traces, { errorsOnly: true });
+const bySession = groupBySession(failed); // SessionGroup[], sessionless → "(no session)"
+```
+
+`TraceFilter` is `{ text?, statuses?, types?, sessionId?, promptKey?, errorsOnly? }` — every field optional and ANDed, so `{}` matches everything. `rollupCost(span)` / `maxNodeCost(root)` / `heatIntensity(nodeCost, maxCost)` are the pure heatmap folds (intensity in `[0,1]`, `0` for a free trace rather than dividing by zero).
+
+### Deep-links
+
+The open trace + span are reflected in the URL hash (`#trace=<id>&span=<id>`) and re-opened from it on load — so a drawer view is **shareable / bookmarkable**. (A live socket tail is a noted follow-up; this pass stays on the 2s poll.)
+
+### Prompt-version linkage
+
+When an agent ran against a *named* `ai.prompts` builder, the collector stamps `agent.promptName` / `agent.promptVersion` onto the root span. The dashboard derives a `name@version` key from them (`tracePromptKey(trace)`) and offers **filter-by-prompt** and **group-by-prompt** beside session — so a reviewer sees every run of `support@2` together and compares its cost / failure rate against `support@3`. Runs with no named prompt bucket under `"(no prompt)"`.
+
+```ts
+import { tracePromptKey, groupByPrompt, type PromptGroup } from "@warlock.js/ai-panoptic";
+
+const byPrompt = groupByPrompt(store.query()); // PromptGroup[] keyed by name@version
+```
+
+## Persistent traces — `cache` (survive a restart)
+
+By default the dashboard reads a fresh **in-memory** store, so traces vanish on restart. Point `panoptic.cache` at a `@warlock.js/cache` `CacheDriver` (Redis, file, …) and panoptic serves the dashboard from a **cache-backed** store instead — traces persist and re-hydrate on the next boot:
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-panoptic";
+import { RedisCacheDriver } from "@warlock.js/cache";
+
+ai.config({
+  panoptic: {
+    dashboard: true,
+    observeAll: true,
+    // A driver, or a (possibly async) factory resolved lazily on first use —
+    // the factory form defers the Redis connect until the first trace lands.
+    cache: async () => {
+      const driver = new RedisCacheDriver();
+      await driver.connect();
+      return driver;
+    },
+  },
+});
+```
+
+Panoptic awaits the store's `ready()` hydration **before** the server starts serving, so a restart surfaces previously-persisted traces immediately. Reads stay synchronous (served from an in-memory mirror); writes go through to the cache fire-and-forget, so a flaky cache never throws into the collector's hot path. A store-shaped exporter you pass via `exporters` still wins over `cache`. The store building block (`createCacheTraceStore`) and its durability contract live in [`query-traces/SKILL.md`](@warlock.js/ai-panoptic/query-traces/SKILL.md).
+
+## The low-level building block — `dashboard(store, options)`
+
+Reach for this directly only when you manage the store yourself (e.g. a long-lived store you also query elsewhere, or a non-default lifecycle). It returns a `Promise<DashboardHandle>`:
+
+```ts
+import { dashboard, createInMemoryTraceStore } from "@warlock.js/ai-panoptic";
+
+const store = createInMemoryTraceStore();
+const handle = await dashboard(store, { port: 4319, open: true });
+
+console.log(handle.url);  // http://127.0.0.1:4319/
+console.log(handle.port); // 4319 (the REAL OS port when port: 0 was passed)
+
+// ...on teardown:
+await handle.close();
+```
+
+The store is the same object the collector writes to — wire the collector to it (pass it as an exporter to `panoptic({ exporters: [store] })` or via `ai.config`) and the dashboard reflects new traces on its next poll.
+
+### `DashboardOptions`
+
+Every field optional, every default safe:
+
+| Option | Default | Notes |
+|---|---|---|
+| `port` | `4319` | Pass `0` for an ephemeral port — the resolved port comes back on `handle.port`. A busy port rejects with a clear `Error` (`port N in use; pass { port: 0 }`), not raw `EADDRINUSE`. |
+| `host` | `"127.0.0.1"` | **Loopback only** by default, so prompt content is never exposed to the LAN. Binding a non-loopback interface is gated — it requires `authToken` (see below) or `dashboard()` rejects. |
+| `basePath` | `"/"` | Mount-path prefix for both the page and every `/api/...` route, e.g. `"/panoptic"`. Normalized to leading + trailing slash. |
+| `open` | `false` | Open the default browser at the resolved URL once listening. Best-effort and fully swallowed — failing to open a browser never rejects the start. |
+| `title` | `"Panoptic"` | Header title baked into the served page. |
+| `authToken` | _unset_ | Bearer token required on every request (`Authorization: Bearer <token>` or `?token=`); missing/wrong → `401`. **Required** when `host` is non-loopback. |
+| `allowedHosts` | loopback names | `Host`-header allowlist (DNS-rebind guard); an unlisted `Host` → `403`. Defaults to `localhost` / `127.0.0.1` / `[::1]` for a loopback bind. |
+
+### `DashboardHandle`
+
+```ts
+type DashboardHandle = {
+  readonly url: string;            // http://host:port{basePath}
+  readonly port: number;           // real OS port (when port: 0 was requested)
+  close(): Promise<void>;          // stop the server, release the port
+};
+```
+
+## The JSON API
+
+All routes are **`GET`-only and read-only** (non-`GET` → `405`), mounted under `basePath`. The page polls them; you can curl them too. Store shapes are already JSON-safe, so responses are a plain `JSON.stringify`.
+
+| Route | Returns |
+|---|---|
+| `GET /api/traces` | `store.query(...)` — the trace list, filtered by the query string (`id` / `sessionId` / `status` / time window, parsed by `parseQuery`). |
+| `GET /api/traces/:id` | `store.get(id)` — one full trace, or `404 { error: "trace_not_found" }`. |
+| `GET /api/aggregate` | `store.aggregate(...)` — the usage + cost + status rollup over the same query filter. |
+| `GET /` (basePath) | the self-contained HTML page. |
+
+Query-string filters map 1:1 onto `TraceQuery`:
+
+```sh
+curl 'http://127.0.0.1:4319/api/traces?status=failed'
+curl 'http://127.0.0.1:4319/api/aggregate?sessionId=sess_42'
+```
+
+(The exact filter keys and the aggregate shape live in [`query-traces/SKILL.md`](@warlock.js/ai-panoptic/query-traces/SKILL.md).)
+
+## Advanced — build the handler yourself
+
+`createRequestHandler(store, config)` is the bare `(req, res) => void` the server closes over — split out from the lifecycle so it unit-tests without binding a port, and so you can mount the same routes inside an existing server:
+
+```ts
+import { createRequestHandler } from "@warlock.js/ai-panoptic";
+import { createServer } from "node:http";
+
+const handler = createRequestHandler(store, {
+  basePath: "/",
+  title: "Panoptic",
+  allowedHosts: ["127.0.0.1", "localhost"],
+});
+createServer(handler).listen(4319, "127.0.0.1");
+```
+
+`dashboardHtml(basePath, title)` returns the served page as a string if you embed it elsewhere. `ServeConfig` is `{ basePath; title; allowedHosts; authToken? }`.
+
+## Security note
+
+The dashboard surfaces whatever the store holds — including captured prompt/response content when content capture is on (`captureContent`). It binds **loopback-only** by default precisely so that content never leaves the machine. Binding a non-loopback host is gated — it requires an `authToken` (and checks a `Host` allowlist, sending `nosniff` / CSP / `X-Frame-Options: DENY` on every response) — but still prefer loopback for dev, and for production ship to a real backend via an exporter rather than exposing the dashboard.
+
+## See also
+
+- [`@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`](@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md) — the `ai.config({ panoptic })` wiring and the underlying `panoptic(...)` subscriber that fills the store.
+- [`@warlock.js/ai-panoptic/query-traces/SKILL.md`](@warlock.js/ai-panoptic/query-traces/SKILL.md) — the `TraceStoreContract` (`query` / `get` / `aggregate`) the dashboard reads, the `TraceQuery` filter, and capacity eviction.
+- [`@warlock.js/ai-panoptic/export-traces/SKILL.md`](@warlock.js/ai-panoptic/export-traces/SKILL.md) — shipping traces to OTel / Langfuse / a file instead of (or alongside) the local dashboard.
+
+

package/llms.txt

@@ -6,6 +6,7 @@
 
 ## Skills
 
-- [export-traces](@warlock.js/ai-panoptic/export-traces/SKILL.md): Send @warlock.js/ai-panoptic traces to an observability backend via pluggable exporters. Triggers: `consoleExporter`, `fileExporter`, `otelExporter`, `langfuseExporter`, `ExporterContract`, `toGenAiAttributes`, `walkSpans`, `totalCostUsd`, `GEN_AI_ATTRIBUTES`, `WARLOCK_ATTRIBUTES`, `reportToTrace`, `reportToSpan`, `extractSpanAttributes`, `normalizeError`, `formatSpanLine`, `createPanopticMiddleware`; 'export AI traces to OpenTelemetry', 'send traces to Langfuse', 'log traces to console / a file', 'gen_ai semantic conventions', 'write a custom exporter'; typical import `import { otelExporter, langfuseExporter, consoleExporter, fileExporter } from "@warlock.js/ai-panoptic"`. Skip: wiring the subscriber/collector into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`; the core report shape — `@warlock.js/ai/run-ai-agent/SKILL.md`.
-- [observe-with-panoptic](@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md): Wire @warlock.js/ai-panoptic into an agent/workflow/supervisor/orchestrator with the one-call `panoptic({ exporters })` subscriber. Triggers: `panoptic`, `Panoptic`, `PanopticOptions`, `.attach`, `.middleware`, `.collect`, `.toTrace`, `observe.attach(agent)`, `panoptic().middleware()`, `completedEvents`, `middlewareName`; 'observe a warlock agent', 'trace an agent run', 'attach observability to a workflow/supervisor', 'add a tracing middleware', 'collect an orchestrator turn report', 'wire OTel/Langfuse into my agent'; typical import `import { panoptic } from "@warlock.js/ai-panoptic"`. Skip: writing/choosing an exporter (the sink end) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; the core report shape / running the agent itself — `@warlock.js/ai/run-ai-agent/SKILL.md`.
-- [query-traces](@warlock.js/ai-panoptic/query-traces/SKILL.md): Retain @warlock.js/ai-panoptic traces in a queryable in-memory store and slice them after the fact — get one run by id, list a session, filter failed runs in a window, roll up usage + cost. Triggers: `createInMemoryTraceStore`, `TraceStoreContract`, `TraceQuery`, `TraceAggregate`, `InMemoryTraceStoreOptions`, `store.query`, `store.aggregate`, `store.get`, `store.add`, `store.clear`, `store.size`, `capacity`, `sumUsage`, `emptyUsage`, `matchTrace`; 'query collected traces', 'aggregate AI cost per session', 'how much did this session spend', 'list failed runs', 'retain traces in memory', 'roll up token usage'; typical import `import { createInMemoryTraceStore } from "@warlock.js/ai-panoptic"`. Skip: sending traces to an external backend (OTel/Langfuse/console/file) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; wiring the subscriber into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`.
+- [export-traces](@warlock.js/ai-panoptic/export-traces/SKILL.md): Send @warlock.js/ai-panoptic traces to an observability backend via pluggable exporters, including capturing prompt/response content onto spans. Triggers: `consoleExporter`, `fileExporter`, `otelExporter`, `langfuseExporter`, `ExporterContract`, `ContentCaptureOptions`, `captureContent`, `redactContent`, `fullHistory`, `ContentRedactor`, `toGenAiAttributes`, `walkSpans`, `totalCostUsd`, `GEN_AI_ATTRIBUTES`, `WARLOCK_ATTRIBUTES`, `reportToTrace`, `reportToSpan`, `extractSpanAttributes`, `normalizeError`, `formatSpanLine`, `createPanopticMiddleware`; 'export AI traces to OpenTelemetry', 'send traces to Langfuse', 'log traces to console / a file', 'capture the full prompt/conversation onto a span', 'gen_ai semantic conventions', 'write a custom exporter'; typical import `import { otelExporter, langfuseExporter, consoleExporter, fileExporter } from "@warlock.js/ai-panoptic"`. Skip: wiring the subscriber/collector into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`; the core report shape — `@warlock.js/ai/run-ai-agent/SKILL.md`.
+- [observe-with-panoptic](@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md): Wire @warlock.js/ai-panoptic into an agent/workflow/supervisor/orchestrator — declaratively via `ai.config({ panoptic })` (registers panoptic on core's Observer seam) or with the one-call `panoptic({ exporters })` subscriber. Triggers: `panoptic`, `Panoptic`, `PanopticOptions`, `PanopticConfig`, `ai.config({ panoptic })`, `observeAll`, per-flow `observe`, `FlowObserveOption`, `registerObserver`, `Observer`, `.attach`, `.middleware`, `.collect`, `.toTrace`, `observe.attach(agent)`, `panoptic().middleware()`, `completedEvents`, `middlewareName`; 'observe a warlock agent', 'trace an agent run', 'attach observability to a workflow/supervisor', 'observe every flow by default', 'add a tracing middleware', 'collect an orchestrator turn report', 'wire OTel/Langfuse into my agent'; typical import `import { ai } from "@warlock.js/ai"` + `import "@warlock.js/ai-panoptic"` (or `import { panoptic } from "@warlock.js/ai-panoptic"`). Skip: the zero-setup local dashboard — `@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md`; writing/choosing an exporter (the sink end) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; the core report shape / running the agent itself — `@warlock.js/ai/run-ai-agent/SKILL.md`.
+- [query-traces](@warlock.js/ai-panoptic/query-traces/SKILL.md): Retain @warlock.js/ai-panoptic traces in a queryable store — in-memory, or cache-backed so they survive a process restart — and slice them after the fact: get one run by id, list a session, filter failed runs in a window, roll up usage + cost. Triggers: `createInMemoryTraceStore`, `createCacheTraceStore`, `CacheTraceStoreHandle`, `CacheTraceStoreOptions`, `CacheDriverInput`, `store.ready`, `TraceStoreContract`, `TraceQuery`, `TraceAggregate`, `InMemoryTraceStoreOptions`, `store.query`, `store.aggregate`, `store.get`, `store.add`, `store.clear`, `store.size`, `capacity`, `prefix`, `onError`, `sumUsage`, `emptyUsage`, `matchTrace`; 'query collected traces', 'aggregate AI cost per session', 'how much did this session spend', 'list failed runs', 'retain traces in memory', 'persist traces across a restart', 'cache-backed trace store', 'Redis trace store', 'roll up token usage'; typical import `import { createInMemoryTraceStore, createCacheTraceStore } from "@warlock.js/ai-panoptic"`. Skip: sending traces to an external backend (OTel/Langfuse/console/file) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; wiring the subscriber into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`.
+- [use-local-dashboard](@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md): Run the zero-setup local Panoptic dashboard — a loopback `node:http` server over a trace store served from `ai.config({ panoptic: { dashboard } })`, with a two-pane call-tree + metadata UI (light/dark/system theme, search/filter, session + prompt-version grouping, cost heatmap, Gantt timeline, errors filter, hash deep-links) and an optional cache-backed persistent store. Triggers: `dashboard`, `DashboardOptions`, `DashboardHandle`, `ai.config({ panoptic })`, `panoptic.dashboard`, `panoptic.cache`, `port: 4319`, `basePath`, `open`, `/api/traces`, `/api/aggregate`, `/api/traces/:id`, `createRequestHandler`, `dashboardHtml`, `ServeConfig`, `TraceStoreContract`, `createCacheTraceStore`, theme, dark mode, call tree, metadata panel, cost heatmap, timeline / Gantt, errors only, deep-link, group by session, prompt version, group by type, type stats panel, started / ended timestamps, team type; 'open a local AI trace dashboard', 'view agent traces in the browser', 'self-hosted panoptic UI', 'inspect traces without Langfuse', 'spin up a dev observability server', 'dark mode dashboard', 'persist traces across restart', 'group traces by session / prompt version / type', 'cost heatmap', 'timeline / waterfall view', 'filter failed runs in the dashboard', 'per-type stats panel'; typical import `import { ai } from "@warlock.js/ai"` + `import "@warlock.js/ai-panoptic"`. Skip: shipping traces to a backend (OTel / Langfuse / file) — `@warlock.js/ai-panoptic/export-traces/SKILL.md`; the queryable store API the dashboard reads — `@warlock.js/ai-panoptic/query-traces/SKILL.md`; wiring the subscriber by hand — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`.

package/package.json

@@ -15,13 +15,17 @@
     "type": "git",
     "url": "https://github.com/warlockjs/ai-panoptic"
   },
+  "dependencies": {
+    "langfuse": "^3.38.20"
+  },
   "peerDependencies": {
-    "@warlock.js/ai": "4.4.0",
     "@opentelemetry/api": "*",
     "@opentelemetry/sdk-trace-base": "*",
+    "@warlock.js/ai": "4.6.0",
+    "@warlock.js/cache": "4.6.0",
     "langfuse": "*"
   },
-  "version": "4.4.0",
+  "version": "4.6.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/README.md

@@ -6,12 +6,16 @@ Per-task skills. All cross-references use the form `@warlock.js/<pkg>/<skill>/SK
 
 ### [`observe-with-panoptic/`](./observe-with-panoptic/SKILL.md)
 
-Wire Panoptic into a run with the one-call `panoptic({ exporters })` subscriber — `attach()` to an agent/workflow/supervisor event stream (every run captured automatically), `middleware()` for the agent pipeline, or `collect()` a report directly (the orchestrator turn). Covers the three feed paths, the default `*.completed` event surface and `completedEvents` override, failure isolation, `flush()` / `shutdown()`, and bringing your own collector/store. Load when attaching observability to a primitive, adding a tracing middleware, or collecting an orchestrator turn report.
+Wire Panoptic into a run — declaratively via `ai.config({ panoptic })` (registers panoptic on core's `Observer` seam; `observeAll` + per-flow `observe` decide which workflow/supervisor/team runs route in), or imperatively with the one-call `panoptic({ exporters })` subscriber (`attach()` to an event stream, `middleware()` for the agent pipeline, or `collect()` a report directly — the orchestrator turn). Covers the side-effect import, the three imperative feed paths, the default `*.completed` event surface and `completedEvents` override, failure isolation, `flush()` / `shutdown()`, and bringing your own collector/store. Load when attaching observability to a primitive, observing every flow by default, adding a tracing middleware, or collecting an orchestrator turn report.
 
 ### [`export-traces/`](./export-traces/SKILL.md)
 
-Send Panoptic traces to an observability backend via pluggable exporters — `consoleExporter` / `fileExporter` (zero-dep) and `otelExporter` (OpenTelemetry GenAI semantic conventions) / `langfuseExporter` (both lazily import their optional-peer SDK). Covers picking an exporter, the `ExporterContract`, the `gen_ai.*` / `warlock.*` attribute mapping, the shared `walkSpans` / `toGenAiAttributes` / `totalCostUsd` utilities, and authoring a custom exporter. Load when wiring `collector.use(...)` with an exporter, exporting to OTel / Langfuse / console / a file, or writing a custom sink.
+Send Panoptic traces to an observability backend via pluggable exporters — `consoleExporter` / `fileExporter` (zero-dep) and `otelExporter` (OpenTelemetry GenAI semantic conventions) / `langfuseExporter` (both lazily import their optional-peer SDK). Covers picking an exporter, the `ExporterContract`, the `gen_ai.*` / `warlock.*` attribute mapping, opt-in content capture (`captureContent` / `redactContent` / `fullHistory` to emit the whole `CapturedMessage[]`), the shared `walkSpans` / `toGenAiAttributes` / `totalCostUsd` utilities, and authoring a custom exporter. Load when wiring `collector.use(...)` with an exporter, exporting to OTel / Langfuse / console / a file, capturing prompt/response content onto spans, or writing a custom sink.
 
 ### [`query-traces/`](./query-traces/SKILL.md)
 
-Retain traces in the queryable in-memory store and slice them after the fact — `createInMemoryTraceStore` (doubles as an `ExporterContract`), `get` / `query` / `aggregate` / `clear` / `size`, the `TraceQuery` filter (id / session / status / time window), the `TraceAggregate` usage + cost + status rollup, `capacity` FIFO eviction, and the pure `sumUsage` / `emptyUsage` / `matchTrace` helpers. Load when querying collected traces, aggregating AI cost/usage per session, listing failed runs, or retaining traces in memory.
+Retain traces in a queryable store — in-memory (`createInMemoryTraceStore`) or **cache-backed and restart-durable** (`createCacheTraceStore` over any `@warlock.js/cache` `CacheDriver` / async factory, with a synchronous in-memory read mirror, write-through persistence, `ready()` hydration, `prefix` / `capacity` / `onError`) — and slice them after the fact: `get` / `query` / `aggregate` / `clear` / `size`, the `TraceQuery` filter (id / session / status / time window), the `TraceAggregate` usage + cost + status rollup, `capacity` FIFO eviction, and the pure `sumUsage` / `emptyUsage` / `matchTrace` helpers. Load when querying collected traces, aggregating AI cost/usage per session, listing failed runs, retaining traces in memory, or persisting them across a restart.
+
+### [`use-local-dashboard/`](./use-local-dashboard/SKILL.md)
+
+Run the zero-setup local Panoptic dashboard — a loopback `node:http` server over a trace store served from `ai.config({ panoptic: { dashboard } })`. Covers the redesigned UI (light/dark/system theme, two-pane nested call tree + metadata panel, colour-coded Title-case type labels including the first-class `Team` type, started/ended wall-clock timestamps, arrow-coded `↓in · ↑out · total` tokens, per-node rollup cost, hide-zero rows, Warlock logo), the new dashboard features (client-side search/filter, group-by-session + group-by-prompt + group-by-type, per-type stats panel, cost heatmap, Gantt timeline, errors-only toggle, hash deep-links) and their pure `trace-filter.ts` helpers (`filterTraces` / `groupBySession` / `groupByPrompt` / `rollupCost` / `maxNodeCost` / `heatIntensity` / `tracePromptKey`), the persistent `cache` store wiring, the declarative path (which store it reads, idempotent wiring), the low-level `dashboard(store, options)` building block, `DashboardOptions` (port `4319`, loopback host, `basePath`, `open`, `title`), the `DashboardHandle`, the read-only `/api/traces` / `/api/aggregate` / `/api/traces/:id` JSON API, `createRequestHandler` / `dashboardHtml` for embedding, prompt-version linkage, and the loopback-only security posture. Load when opening a local AI trace viewer in the browser, theming/filtering it, inspecting traces without a backend, persisting them across a restart, or spinning up a dev observability server.

package/skills/export-traces/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: export-traces
-description: 'Send @warlock.js/ai-panoptic traces to an observability backend via pluggable exporters. Triggers: `consoleExporter`, `fileExporter`, `otelExporter`, `langfuseExporter`, `ExporterContract`, `toGenAiAttributes`, `walkSpans`, `totalCostUsd`, `GEN_AI_ATTRIBUTES`, `WARLOCK_ATTRIBUTES`, `reportToTrace`, `reportToSpan`, `extractSpanAttributes`, `normalizeError`, `formatSpanLine`, `createPanopticMiddleware`; ''export AI traces to OpenTelemetry'', ''send traces to Langfuse'', ''log traces to console / a file'', ''gen_ai semantic conventions'', ''write a custom exporter''; typical import `import { otelExporter, langfuseExporter, consoleExporter, fileExporter } from "@warlock.js/ai-panoptic"`. Skip: wiring the subscriber/collector into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`; the core report shape — `@warlock.js/ai/run-ai-agent/SKILL.md`.'
+description: 'Send @warlock.js/ai-panoptic traces to an observability backend via pluggable exporters, including capturing prompt/response content onto spans. Triggers: `consoleExporter`, `fileExporter`, `otelExporter`, `langfuseExporter`, `ExporterContract`, `ContentCaptureOptions`, `captureContent`, `redactContent`, `fullHistory`, `ContentRedactor`, `toGenAiAttributes`, `walkSpans`, `totalCostUsd`, `GEN_AI_ATTRIBUTES`, `WARLOCK_ATTRIBUTES`, `reportToTrace`, `reportToSpan`, `extractSpanAttributes`, `normalizeError`, `formatSpanLine`, `createPanopticMiddleware`; ''export AI traces to OpenTelemetry'', ''send traces to Langfuse'', ''log traces to console / a file'', ''capture the full prompt/conversation onto a span'', ''gen_ai semantic conventions'', ''write a custom exporter''; typical import `import { otelExporter, langfuseExporter, consoleExporter, fileExporter } from "@warlock.js/ai-panoptic"`. Skip: wiring the subscriber/collector into a run — `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`; the core report shape — `@warlock.js/ai/run-ai-agent/SKILL.md`.'
 ---
 
 # Export traces — the sink end of Panoptic
@@ -94,6 +94,38 @@ collector.use(langfuseExporter({ client: myLangfuse }));
 - Children nest under their parent observation; timing, `version`, and status (failed → `ERROR` level) are mapped.
 - `flush()` / `shutdown()` delegate to the client's `flushAsync()` / `shutdownAsync()` — call `collector.shutdown()` on teardown so buffered observations are sent.
 
+## Content capture — what reaches the `input` / `output` fields
+
+Exporters surface `span.input` / `span.output` (console `in:` / `out:`, file JSON, OTel `gen_ai.prompt` / `gen_ai.completion`, Langfuse native `input` / `output`) only when **content capture** is enabled on the collector or subscriber. It's `ContentCaptureOptions`, set on `createCollector(...)` or `panoptic(...)`:
+
+```ts
+panoptic({
+  exporters: [langfuseExporter({ /* ... */ })],
+  captureContent: true,                 // copy prompts/responses + tool args/results onto spans
+  redactContent: (value, { field }) =>  // optional masker, per value
+    field === "input" ? "[redacted]" : value,
+  fullHistory: true,                    // emit the WHOLE conversation as span.input (see below)
+});
+```
+
+Off by default — payloads are large and frequently sensitive. With `captureContent`, an agent span's `input` is a `[system, user]` chat array (or the bare user string when there's no system prompt) and its `output` is the last non-empty trip's text; a tool span carries its call args + result.
+
+### `fullHistory` — emit the entire `CapturedMessage[]`
+
+`fullHistory: true` replaces the `[system, user]` first-trip array on `span.input` with the agent's **complete assembled conversation** — every trip, every role (system / user / assistant / tool). The `output` stays the final response text.
+
+```ts
+// upstream: the agent run MUST opt into capturing its messages
+const result = await agent.execute(input, { captureMessages: true });
+//                                          ^ core @warlock.js/ai — makes report.messages present
+
+panoptic({ exporters: [...], captureContent: true, fullHistory: true });
+```
+
+**Requires the upstream `captureMessages`.** `fullHistory` reads `report.messages` (the captured `CapturedMessage[]`). When the run did NOT opt into `captureMessages`, `report.messages` is absent and the branch **degrades gracefully** to today's first-trip `[system, user]` capture — never an error, just less history. The whole array is passed through `ContentRedactor` as a single value, so masking still applies to captured history.
+
+Reach for `fullHistory` when a backend (Langfuse) should show the full multi-turn / tool-loop transcript a run actually sent, not just its opening prompt.
+
 ## Shared utilities
 
 Reusable when authoring a **custom exporter**: