@warlock.js/ai-panoptic 4.3.0 → 4.5.0

package/esm/config/apply-panoptic-config.d.mts

@@ -0,0 +1,27 @@
+import { PanopticConfig } from "./panoptic-config.type.mjs";
+
+//#region ../@warlock.js/ai-panoptic/src/config/apply-panoptic-config.d.ts
+/**
+ * Read a {@link PanopticConfig} and wire panoptic onto the core observe
+ * seam — the bridge `ai.config({ panoptic })` resolves through. Builds a
+ * collector via the EXISTING {@link panoptic} factory (reusing its
+ * collection pipeline, not reinventing it), registers it once via core's
+ * `registerObserver` (the subscriber's `collect(report)` structurally IS
+ * an {@link Observer}, threaded through a thin wrapper), sets
+ * `observeAll`, and — when `config.dashboard` is set — starts the
+ * dashboard over the config's store (a store-shaped exporter, or a fresh
+ * in-memory store panoptic registers when none was supplied).
+ *
+ * **Idempotent.** Safe to call on every `onConfigApplied` notification:
+ * the observer is registered once, the dashboard started once. Repeat
+ * calls update `observeAll` to the latest value but never double-register
+ * or double-start. `undefined` config is a no-op (nothing wired).
+ *
+ * @returns the resolved store-shaped exporter when the dashboard needs
+ * one and a fresh store was created — primarily for tests; callers can
+ * ignore it.
+ */
+declare function applyPanopticConfig(config?: PanopticConfig): void;
+//#endregion
+export { applyPanopticConfig };
+//# sourceMappingURL=apply-panoptic-config.d.mts.map

package/esm/config/apply-panoptic-config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-panoptic-config.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/config/apply-panoptic-config.ts"],"mappings":";;;;AAgDA;;;;AAA2D;;;;;;;;;;;;;;;iBAA3C,mBAAA,CAAoB,MAAuB,GAAd,cAAc"}

package/esm/config/apply-panoptic-config.mjs

@@ -0,0 +1,89 @@
+import { createCacheTraceStore } from "../store/cache-trace-store.mjs";
+import { createInMemoryTraceStore } from "../store/in-memory-trace-store.mjs";
+import { panoptic } from "../panoptic/panoptic.mjs";
+import { dashboard } from "../dashboard/dashboard.mjs";
+import { registerObserver, setObserveAll } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-panoptic/src/config/apply-panoptic-config.ts
+let applied;
+/**
+* Read a {@link PanopticConfig} and wire panoptic onto the core observe
+* seam — the bridge `ai.config({ panoptic })` resolves through. Builds a
+* collector via the EXISTING {@link panoptic} factory (reusing its
+* collection pipeline, not reinventing it), registers it once via core's
+* `registerObserver` (the subscriber's `collect(report)` structurally IS
+* an {@link Observer}, threaded through a thin wrapper), sets
+* `observeAll`, and — when `config.dashboard` is set — starts the
+* dashboard over the config's store (a store-shaped exporter, or a fresh
+* in-memory store panoptic registers when none was supplied).
+*
+* **Idempotent.** Safe to call on every `onConfigApplied` notification:
+* the observer is registered once, the dashboard started once. Repeat
+* calls update `observeAll` to the latest value but never double-register
+* or double-start. `undefined` config is a no-op (nothing wired).
+*
+* @returns the resolved store-shaped exporter when the dashboard needs
+* one and a fresh store was created — primarily for tests; callers can
+* ignore it.
+*/
+function applyPanopticConfig(config) {
+	if (config === void 0) return;
+	setObserveAll(Boolean(config.observeAll));
+	if (applied === void 0) {
+		const exporters = [...config.exporters ?? []];
+		let store = findStore(exporters);
+		let cacheStore;
+		if (store === void 0 && config.dashboard) {
+			if (config.cache !== void 0) {
+				cacheStore = createCacheTraceStore(config.cache);
+				store = cacheStore;
+			} else store = createInMemoryTraceStore();
+			exporters.push(store);
+		}
+		const panopticInstance = panoptic({
+			exporters,
+			captureContent: config.captureContent,
+			fullHistory: config.fullHistory
+		});
+		registerObserver(toObserver(panopticInstance));
+		applied = { panopticInstance };
+		if (config.dashboard && store !== void 0) {
+			const resolvedStore = store;
+			(cacheStore !== void 0 ? cacheStore.ready() : Promise.resolve()).catch(() => {}).then(() => startDashboard(resolvedStore, config.dashboard ?? {})).then((handle) => {
+				if (applied !== void 0) applied.dashboardHandle = handle;
+			});
+		}
+	}
+}
+/**
+* Wrap a {@link Panoptic} subscriber as a core {@link Observer}. The
+* subscriber already exposes `collect(report)` with a matching signature,
+* but the thin wrapper makes the structural adaptation explicit and keeps
+* the registered object a minimal `Observer` rather than the whole
+* subscriber surface.
+*/
+function toObserver(instance) {
+	return { collect(report) {
+		return instance.collect(report);
+	} };
+}
+/**
+* Find the first exporter that satisfies the {@link TraceStoreContract}
+* read surface (`query` / `get` / `aggregate`) — the in-memory store
+* doubles as an exporter, so a store passed via `exporters` is reused for
+* the dashboard rather than creating a second one.
+*/
+function findStore(exporters) {
+	for (const exporter of exporters) {
+		const candidate = exporter;
+		if (typeof candidate.query === "function" && typeof candidate.get === "function" && typeof candidate.aggregate === "function") return candidate;
+	}
+}
+/** Start the dashboard, normalizing the `true | DashboardOptions` switch. */
+function startDashboard(store, dashboardConfig) {
+	return dashboard(store, typeof dashboardConfig === "object" ? dashboardConfig : {});
+}
+
+//#endregion
+export { applyPanopticConfig };
+//# sourceMappingURL=apply-panoptic-config.mjs.map

package/esm/config/apply-panoptic-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-panoptic-config.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/config/apply-panoptic-config.ts"],"sourcesContent":["import type { ExecutionReport, Observer } from \"@warlock.js/ai\";\nimport { registerObserver, setObserveAll } from \"@warlock.js/ai\";\nimport type { ExporterContract } from \"../contracts/exporter.contract\";\nimport { dashboard } from \"../dashboard/dashboard\";\nimport type { DashboardHandle, DashboardOptions } from \"../dashboard/dashboard.type\";\nimport { panoptic } from \"../panoptic/panoptic\";\nimport type { Panoptic } from \"../panoptic/panoptic.type\";\nimport { createCacheTraceStore } from \"../store/cache-trace-store\";\nimport type { CacheTraceStoreHandle } from \"../store/cache-trace-store\";\nimport { createInMemoryTraceStore } from \"../store/in-memory-trace-store\";\nimport type { TraceStoreContract } from \"../store/trace-store.contract\";\nimport type { PanopticConfig } from \"./panoptic-config.type\";\n\n/**\n * Module-level applied state. Applying panoptic config is idempotent:\n * the collector is registered as a core `Observer` exactly once, the\n * dashboard is started at most once, and repeat calls only refresh the\n * `observeAll` flag (the latest config wins) without double-registering.\n */\ntype AppliedState = {\n  /** The single collector registered as a core `Observer`. */\n  panopticInstance: Panoptic;\n  /** The dashboard handle, once started. Started at most once. */\n  dashboardHandle?: DashboardHandle;\n};\n\nlet applied: AppliedState | undefined;\n\n/**\n * Read a {@link PanopticConfig} and wire panoptic onto the core observe\n * seam — the bridge `ai.config({ panoptic })` resolves through. Builds a\n * collector via the EXISTING {@link panoptic} factory (reusing its\n * collection pipeline, not reinventing it), registers it once via core's\n * `registerObserver` (the subscriber's `collect(report)` structurally IS\n * an {@link Observer}, threaded through a thin wrapper), sets\n * `observeAll`, and — when `config.dashboard` is set — starts the\n * dashboard over the config's store (a store-shaped exporter, or a fresh\n * in-memory store panoptic registers when none was supplied).\n *\n * **Idempotent.** Safe to call on every `onConfigApplied` notification:\n * the observer is registered once, the dashboard started once. Repeat\n * calls update `observeAll` to the latest value but never double-register\n * or double-start. `undefined` config is a no-op (nothing wired).\n *\n * @returns the resolved store-shaped exporter when the dashboard needs\n * one and a fresh store was created — primarily for tests; callers can\n * ignore it.\n */\nexport function applyPanopticConfig(config?: PanopticConfig): void {\n  if (config === undefined) {\n    return;\n  }\n\n  // observeAll always tracks the latest config, even on a repeat call.\n  setObserveAll(Boolean(config.observeAll));\n\n  if (applied === undefined) {\n    const exporters = [...(config.exporters ?? [])];\n    let store = findStore(exporters);\n\n    // Track a cache store separately so we can await its hydration before\n    // the dashboard reads it — the in-memory store needs no warm-up.\n    let cacheStore: CacheTraceStoreHandle | undefined;\n\n    // The dashboard needs a queryable store. If none was supplied via\n    // exporters but a dashboard is requested, create one and register it\n    // as an exporter so the collector fills it. A configured `cache` picks\n    // the durable cache-backed store; otherwise fall back to in-memory so\n    // the dashboard works with no cache configured.\n    if (store === undefined && config.dashboard) {\n      if (config.cache !== undefined) {\n        cacheStore = createCacheTraceStore(config.cache);\n        store = cacheStore;\n      } else {\n        store = createInMemoryTraceStore();\n      }\n\n      exporters.push(store as unknown as ExporterContract);\n    }\n\n    const panopticInstance = panoptic({\n      exporters,\n      captureContent: config.captureContent,\n      fullHistory: config.fullHistory,\n    });\n    registerObserver(toObserver(panopticInstance));\n\n    applied = { panopticInstance };\n\n    if (config.dashboard && store !== undefined) {\n      const resolvedStore = store;\n\n      // Hydrate the cache mirror (if any) before serving, so a restart\n      // surfaces previously-persisted traces immediately. A bare in-memory\n      // store resolves the readyGate instantly.\n      const readyGate =\n        cacheStore !== undefined ? cacheStore.ready() : Promise.resolve();\n\n      void readyGate\n        .catch(() => {\n          // Hydration is best-effort — never block the dashboard on it.\n        })\n        .then(() => startDashboard(resolvedStore, config.dashboard ?? {}))\n        .then((handle) => {\n          if (applied !== undefined) {\n            applied.dashboardHandle = handle;\n          }\n        });\n    }\n  }\n}\n\n/**\n * Reset the applied state — internal, test-only. Closes any running\n * dashboard and forgets the registered collector so a fresh\n * `applyPanopticConfig` starts clean. NOT part of the public surface and\n * does NOT unregister from the core observer registry (use core's\n * `clearObservers` for that in tests).\n */\nexport async function resetAppliedPanopticConfig(): Promise<void> {\n  const handle = applied?.dashboardHandle;\n  applied = undefined;\n\n  if (handle !== undefined) {\n    await handle.close();\n  }\n}\n\n/**\n * The currently-running dashboard handle, or `undefined` when no\n * dashboard is active. Internal, test-only — lets a spec await the\n * asynchronously-started dashboard. NOT part of the public surface.\n */\nexport function getActiveDashboardHandle(): DashboardHandle | undefined {\n  return applied?.dashboardHandle;\n}\n\n/**\n * Wrap a {@link Panoptic} subscriber as a core {@link Observer}. The\n * subscriber already exposes `collect(report)` with a matching signature,\n * but the thin wrapper makes the structural adaptation explicit and keeps\n * the registered object a minimal `Observer` rather than the whole\n * subscriber surface.\n */\nfunction toObserver(instance: Panoptic): Observer {\n  return {\n    collect(report: ExecutionReport): Promise<void> {\n      return instance.collect(report);\n    },\n  };\n}\n\n/**\n * Find the first exporter that satisfies the {@link TraceStoreContract}\n * read surface (`query` / `get` / `aggregate`) — the in-memory store\n * doubles as an exporter, so a store passed via `exporters` is reused for\n * the dashboard rather than creating a second one.\n */\nfunction findStore(exporters: ExporterContract[]): TraceStoreContract | undefined {\n  for (const exporter of exporters) {\n    const candidate = exporter as unknown as Partial<TraceStoreContract>;\n\n    if (\n      typeof candidate.query === \"function\" &&\n      typeof candidate.get === \"function\" &&\n      typeof candidate.aggregate === \"function\"\n    ) {\n      return candidate as TraceStoreContract;\n    }\n  }\n\n  return undefined;\n}\n\n/** Start the dashboard, normalizing the `true | DashboardOptions` switch. */\nfunction startDashboard(\n  store: TraceStoreContract,\n  dashboardConfig: boolean | DashboardOptions,\n): Promise<DashboardHandle> {\n  const options: DashboardOptions =\n    typeof dashboardConfig === \"object\" ? dashboardConfig : {};\n\n  return dashboard(store, options);\n}\n"],"mappings":";;;;;;;AA0BA,IAAI;;;;;;;;;;;;;;;;;;;;;AAsBJ,SAAgB,oBAAoB,QAA+B;CACjE,IAAI,WAAW,QACb;CAIF,cAAc,QAAQ,OAAO,UAAU,CAAC;CAExC,IAAI,YAAY,QAAW;EACzB,MAAM,YAAY,CAAC,GAAI,OAAO,aAAa,CAAC,CAAE;EAC9C,IAAI,QAAQ,UAAU,SAAS;EAI/B,IAAI;EAOJ,IAAI,UAAU,UAAa,OAAO,WAAW;GAC3C,IAAI,OAAO,UAAU,QAAW;IAC9B,aAAa,sBAAsB,OAAO,KAAK;IAC/C,QAAQ;GACV,OACE,QAAQ,yBAAyB;GAGnC,UAAU,KAAK,KAAoC;EACrD;EAEA,MAAM,mBAAmB,SAAS;GAChC;GACA,gBAAgB,OAAO;GACvB,aAAa,OAAO;EACtB,CAAC;EACD,iBAAiB,WAAW,gBAAgB,CAAC;EAE7C,UAAU,EAAE,iBAAiB;EAE7B,IAAI,OAAO,aAAa,UAAU,QAAW;GAC3C,MAAM,gBAAgB;GAQtB,CAFE,eAAe,SAAY,WAAW,MAAM,IAAI,QAAQ,QAAQ,EAEpD,CACX,YAAY,CAEb,CAAC,CAAC,CACD,WAAW,eAAe,eAAe,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CACjE,MAAM,WAAW;IAChB,IAAI,YAAY,QACd,QAAQ,kBAAkB;GAE9B,CAAC;EACL;CACF;AACF;;;;;;;;AAkCA,SAAS,WAAW,UAA8B;CAChD,OAAO,EACL,QAAQ,QAAwC;EAC9C,OAAO,SAAS,QAAQ,MAAM;CAChC,EACF;AACF;;;;;;;AAQA,SAAS,UAAU,WAA+D;CAChF,KAAK,MAAM,YAAY,WAAW;EAChC,MAAM,YAAY;EAElB,IACE,OAAO,UAAU,UAAU,cAC3B,OAAO,UAAU,QAAQ,cACzB,OAAO,UAAU,cAAc,YAE/B,OAAO;CAEX;AAGF;;AAGA,SAAS,eACP,OACA,iBAC0B;CAI1B,OAAO,UAAU,OAFf,OAAO,oBAAoB,WAAW,kBAAkB,CAAC,CAE5B;AACjC"}

package/esm/config/index.d.mts

@@ -0,0 +1,2 @@
+import { PanopticConfig } from "./panoptic-config.type.mjs";
+import { applyPanopticConfig } from "./apply-panoptic-config.mjs";

package/esm/config/index.mjs

@@ -0,0 +1,3 @@
+import { applyPanopticConfig } from "./apply-panoptic-config.mjs";
+
+export {  };

package/esm/config/panoptic-config.type.d.mts

@@ -0,0 +1,84 @@
+import { ExporterContract } from "../contracts/exporter.contract.mjs";
+import { CacheDriverInput } from "../store/cache-trace-store.mjs";
+import { DashboardOptions } from "../dashboard/dashboard.type.mjs";
+
+//#region ../@warlock.js/ai-panoptic/src/config/panoptic-config.type.d.ts
+/**
+ * Declarative panoptic configuration, set once through the global
+ * `ai.config({ panoptic: { … } })`. Sugar layered over the existing
+ * {@link import("../panoptic/panoptic").panoptic} factory: reading this
+ * slot (on the side-effect import of `@warlock.js/ai-panoptic`) builds
+ * the same collector, registers it as a core `Observer`, and optionally
+ * starts the local dashboard — so app code never hand-wires a store and
+ * a server. The explicit `panoptic({ exporters })` / `.attach()` /
+ * `.collect()` API stays fully intact as the underlying primitive.
+ *
+ * @example
+ * import { ai } from "@warlock.js/ai";
+ * import "@warlock.js/ai-panoptic"; // side-effect wiring
+ *
+ * ai.config({
+ *   panoptic: {
+ *     exporters: [createInMemoryTraceStore({ capacity: 5000 })],
+ *     dashboard: { port: 4319, open: true },
+ *     observeAll: true,
+ *   },
+ * });
+ */
+type PanopticConfig = {
+  /**
+   * Exporters the collector feeds (a store, OTel, Langfuse, …). A
+   * {@link import("../store/in-memory-trace-store").createInMemoryTraceStore}
+   * store doubles as an `ExporterContract`, so passing one here both
+   * captures traces and gives the dashboard something to read.
+   */
+  exporters?: ExporterContract[];
+  /**
+   * Persist traces through a {@link import("@warlock.js/cache").CacheDriver}
+   * (Redis, Postgres, file, …) so they survive a process restart. Accepts a
+   * driver instance or a (possibly async) factory resolved lazily on first
+   * use — the factory form lets production defer the connect.
+   *
+   * When set (and no store-shaped exporter was supplied), the dashboard
+   * reads a {@link import("../store/cache-trace-store").createCacheTraceStore}
+   * store instead of a fresh in-memory one. When omitted, panoptic falls
+   * back to {@link import("../store/in-memory-trace-store").createInMemoryTraceStore}
+   * — so the dashboard works with no cache configured.
+   */
+  cache?: CacheDriverInput;
+  /**
+   * Serve the local dashboard. `true` uses the defaults
+   * ({@link DashboardOptions}); an object overrides them. When set, the
+   * dashboard reads the store supplied via `exporters` (the first
+   * store-shaped exporter), or a fresh in-memory store panoptic creates
+   * and registers when none was supplied.
+   */
+  dashboard?: boolean | DashboardOptions;
+  /**
+   * Observe every flow (`ai.agent` / `ai.workflow` / `ai.supervisor` /
+   * `ai.team`) by default. Individual flows opt out with `observe: false`.
+   * Default `false` — opt-in observability.
+   */
+  observeAll?: boolean;
+  /**
+   * Capture raw prompt / response / tool I/O onto each span so the dashboard
+   * + console exporter can surface them. Off by default (payloads are large
+   * and can be sensitive); set `true` for a content-rich local dashboard.
+   */
+  captureContent?: boolean;
+  /**
+   * Emit each agent's full message history (every trip, every role) onto
+   * `span.input` instead of just `[system, user]`. Requires the agent run to
+   * set `captureMessages`. Default `false`.
+   */
+  fullHistory?: boolean;
+};
+declare module "@warlock.js/ai" {
+  interface AIConfig {
+    /** Declarative panoptic observability config. See {@link PanopticConfig}. */
+    panoptic?: PanopticConfig;
+  }
+} //# sourceMappingURL=panoptic-config.type.d.ts.map
+//#endregion
+export { PanopticConfig };
+//# sourceMappingURL=panoptic-config.type.d.mts.map

package/esm/config/panoptic-config.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panoptic-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/config/panoptic-config.type.ts"],"mappings":";;;;;;;AA0BA;;;;;;;;;;;;;;;;;;AA8Ca;AACX;KA/CU,cAAA;;;;;;;EAOV,SAAA,GAAY,gBAAA;EAiDe;;;;;;;;;;;;EApC3B,KAAA,GAAQ,gBAAA;;;;;;;;EAQR,SAAA,aAAsB,gBAAA;;;;;;EAMtB,UAAA;;;;;;EAMA,cAAA;;;;;;EAMA,WAAA;AAAA;AAAA;EAAA,UAQU,QAAA;;IAER,QAAA,GAAW,cAAc;EAAA;AAAA"}

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

@@ -13,7 +13,9 @@ import { ReportStatus, ReportType, Usage } from "@warlock.js/ai";
  * 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.
+ * into spans without consulting any other source. Raw content — prompts,
+ * responses, and tool payloads — is captured onto `input` / `output`
+ * only when the collector opts in via `captureContent` (off by default).
  *
  * @example
  * const root: TraceSpan = {
@@ -75,10 +77,27 @@ type TraceSpan = {
   /**
    * 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.
+   * primitive-specific metadata (trip / step / iteration counts, model
+   * identity, the tool's originating trip index) that has no first-class
+   * field here. Raw prompts / completions / tool payloads do NOT live
+   * here — they go on {@link TraceSpan.input} / {@link TraceSpan.output}
+   * under content capture. Absent when empty.
    */
   attributes?: Record<string, unknown>;
+  /**
+   * Captured input for this node — an agent's first-trip prompt or a
+   * tool's call arguments — present ONLY when the collector ran with
+   * content capture enabled (`captureContent`), off by default because
+   * payloads are large and often sensitive. Typed `unknown`: agent
+   * prompts are strings, tool args are the validated argument value.
+   */
+  input?: unknown;
+  /**
+   * Captured output for this node — an agent's final response text or a
+   * tool's return value — present only under content capture (see
+   * {@link TraceSpan.input}).
+   */
+  output?: unknown;
   /**
    * Child spans, mirroring `BaseReport.children` in invocation order.
    * Empty for leaf spans (pure tools). Exporters that emit a flat
@@ -92,9 +111,16 @@ type TraceSpan = {
  * 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. */
+  /** Stable error identifier (typed framework error name when available). */type: string; /** Human-readable message — secret-scrubbed before storage (S4). */
+  message: string; /** Optional captured stack trace, secret-scrubbed when present (S4). */
   stack?: string;
+  /**
+   * Optional redacted view of the error's `cause` (S4) — a raw provider
+   * SDK error can carry `Authorization` / `x-api-key` / `cookie` on its
+   * headers, so the cause is deep-redacted (sensitive keys stripped)
+   * before it is attached.
+   */
+  cause?: unknown;
 };
 /**
  * The root of a Panoptic trace — a top-level {@link TraceSpan} plus the

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

@@ -1 +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"}
+{"version":3,"file":"trace.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/contracts/trace.type.ts"],"mappings":";;;;;AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,SAAA;EA2DG;;;;EAtDb,MAAA;EA0EmB;AAAA;AAQrB;;EA7EE,YAAA;EA6EwB;;;;;;EAtExB,OAAA;EA4FU;;;;;EAtFV,SAAA,WA4FA;EA1FA,IAAA;EA4FA;;;;;EAtFA,OAAA,WAkGmB;EAhGnB,IAAA,EAAM,UAAA;EAEN,MAAA,EAAQ,YAAA;EAER,SAAA;EAEA,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAA;;;;;;EAMP,KAAA,GAAQ,cAAA;;;;;;;;;;EAUR,UAAA,GAAa,MAAA;;;;;;;;EAQb,KAAA;;;;;;EAMA,MAAA;;;;;;EAMA,QAAA,EAAU,SAAA;AAAA;;;;;;KAQA,cAAA;6EAEV,IAAA;EAEA,OAAA;EAEA,KAAA;;;;;;;EAOA,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/dashboard/dashboard.d.mts

@@ -0,0 +1,32 @@
+import { TraceStoreContract } from "../store/trace-store.contract.mjs";
+import { DashboardHandle, DashboardOptions } from "./dashboard.type.mjs";
+
+//#region ../@warlock.js/ai-panoptic/src/dashboard/dashboard.d.ts
+/**
+ * Start the local Panoptic dashboard over a {@link TraceStoreContract} —
+ * a zero-dependency `node:http` server that serves a read-only JSON API
+ * and one self-contained HTML page polling it. The store is the live
+ * object the collector fills, so each poll reflects the latest completed
+ * traces with no extra wiring.
+ *
+ * This is a low-level building block. The documented path is
+ * `ai.config({ panoptic: { dashboard } })`, which constructs (or reuses)
+ * the store and calls this for you. Use it directly only when you manage
+ * the store yourself.
+ *
+ * Binds loopback-only by default (`127.0.0.1`) so prompt content is never
+ * exposed to the LAN. Pass `port: 0` for an ephemeral port — the resolved
+ * port comes back on the handle. A port already in use rejects with a
+ * clear, actionable `Error` rather than the raw `EADDRINUSE`.
+ *
+ * @example
+ * const store = createInMemoryTraceStore();
+ * const handle = await dashboard(store, { port: 4319, open: true });
+ * console.log(handle.url); // http://127.0.0.1:4319/
+ * // ...later:
+ * await handle.close();
+ */
+declare function dashboard(store: TraceStoreContract, options?: DashboardOptions): Promise<DashboardHandle>;
+//#endregion
+export { dashboard };
+//# sourceMappingURL=dashboard.d.mts.map

package/esm/dashboard/dashboard.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/dashboard/dashboard.ts"],"mappings":";;;;;;AAiCA;;;;;;;;;;;;;;;;AAG0B;;;;;;iBAHV,SAAA,CACd,KAAA,EAAO,kBAAA,EACP,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA"}

package/esm/dashboard/dashboard.mjs

@@ -0,0 +1,132 @@
+import { createRequestHandler } from "./serve.mjs";
+import { createServer } from "node:http";
+
+//#region ../@warlock.js/ai-panoptic/src/dashboard/dashboard.ts
+const DEFAULT_PORT = 4319;
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_TITLE = "Panoptic";
+/**
+* Start the local Panoptic dashboard over a {@link TraceStoreContract} —
+* a zero-dependency `node:http` server that serves a read-only JSON API
+* and one self-contained HTML page polling it. The store is the live
+* object the collector fills, so each poll reflects the latest completed
+* traces with no extra wiring.
+*
+* This is a low-level building block. The documented path is
+* `ai.config({ panoptic: { dashboard } })`, which constructs (or reuses)
+* the store and calls this for you. Use it directly only when you manage
+* the store yourself.
+*
+* Binds loopback-only by default (`127.0.0.1`) so prompt content is never
+* exposed to the LAN. Pass `port: 0` for an ephemeral port — the resolved
+* port comes back on the handle. A port already in use rejects with a
+* clear, actionable `Error` rather than the raw `EADDRINUSE`.
+*
+* @example
+* const store = createInMemoryTraceStore();
+* const handle = await dashboard(store, { port: 4319, open: true });
+* console.log(handle.url); // http://127.0.0.1:4319/
+* // ...later:
+* await handle.close();
+*/
+function dashboard(store, options = {}) {
+	const port = options.port ?? DEFAULT_PORT;
+	const host = options.host ?? DEFAULT_HOST;
+	const title = options.title ?? DEFAULT_TITLE;
+	const basePath = normalizeBasePath(options.basePath);
+	if (!isLoopbackHost(host) && !options.authToken) return Promise.reject(/* @__PURE__ */ new Error(`Panoptic dashboard: binding to a non-loopback host ("${host}") requires an \`authToken\` (the dashboard exposes raw prompt content). Pass \`authToken\`, or bind to 127.0.0.1.`));
+	const allowedHosts = (options.allowedHosts ?? defaultAllowedHosts(host)).map((h) => h.toLowerCase());
+	const server = createServer(createRequestHandler(store, {
+		basePath,
+		title,
+		authToken: options.authToken,
+		allowedHosts
+	}));
+	return new Promise((resolve, reject) => {
+		const onError = (error) => {
+			server.off("error", onError);
+			if (error.code === "EADDRINUSE") {
+				reject(/* @__PURE__ */ new Error(`Panoptic dashboard: port ${port} in use; pass { port: 0 } for an ephemeral port`));
+				return;
+			}
+			reject(error);
+		};
+		server.on("error", onError);
+		server.listen(port, host, () => {
+			server.off("error", onError);
+			const address = server.address();
+			const resolvedPort = typeof address === "object" && address !== null ? address.port : port;
+			const url = `http://${host}:${resolvedPort}${basePath}`;
+			if (options.open) openBrowser(url);
+			resolve({
+				url,
+				port: resolvedPort,
+				close() {
+					return new Promise((closeResolve, closeReject) => {
+						server.close((closeError) => {
+							if (closeError) {
+								closeReject(closeError);
+								return;
+							}
+							closeResolve();
+						});
+					});
+				}
+			});
+		});
+	});
+}
+/** Loopback hosts the dashboard may bind without an auth token. */
+function isLoopbackHost(host) {
+	const h = host.toLowerCase();
+	return h === "127.0.0.1" || h === "::1" || h === "[::1]" || h === "localhost";
+}
+/**
+* Default `Host` allowlist for a given bind host. A loopback bind accepts
+* the loopback names a browser would send; a non-loopback bind defaults to
+* just the bound host (callers can widen via `allowedHosts`).
+*/
+function defaultAllowedHosts(host) {
+	if (isLoopbackHost(host)) return [
+		"localhost",
+		"127.0.0.1",
+		"[::1]",
+		"::1"
+	];
+	return [host];
+}
+/**
+* Normalize a caller `basePath` to a leading-and-trailing-slash form the
+* router can prefix routes with. `undefined` / `""` → `"/"`.
+*/
+function normalizeBasePath(basePath) {
+	if (basePath === void 0 || basePath.length === 0 || basePath === "/") return "/";
+	const withLeading = basePath.startsWith("/") ? basePath : `/${basePath}`;
+	return withLeading.endsWith("/") ? withLeading : `${withLeading}/`;
+}
+/**
+* Best-effort open of the default browser at `url`. Fire-and-forget and
+* fully swallowed — failing to open a browser must never reject the
+* dashboard start. Uses the platform's native opener via a lazy
+* `node:child_process` import so the dependency is paid only when
+* `open: true`.
+*/
+function openBrowser(url) {
+	import("node:child_process").then(({ spawn }) => {
+		const child = spawn(process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open", process.platform === "win32" ? [
+			"/c",
+			"start",
+			"",
+			url
+		] : [url], {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	}).catch(() => {});
+}
+
+//#endregion
+export { dashboard };
+//# sourceMappingURL=dashboard.mjs.map

package/esm/dashboard/dashboard.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/dashboard/dashboard.ts"],"sourcesContent":["import { createServer } from \"node:http\";\nimport type { TraceStoreContract } from \"../store/trace-store.contract\";\nimport type { DashboardHandle, DashboardOptions } from \"./dashboard.type\";\nimport { createRequestHandler } from \"./serve\";\n\nconst DEFAULT_PORT = 4319;\nconst DEFAULT_HOST = \"127.0.0.1\";\nconst DEFAULT_TITLE = \"Panoptic\";\n\n/**\n * Start the local Panoptic dashboard over a {@link TraceStoreContract} —\n * a zero-dependency `node:http` server that serves a read-only JSON API\n * and one self-contained HTML page polling it. The store is the live\n * object the collector fills, so each poll reflects the latest completed\n * traces with no extra wiring.\n *\n * This is a low-level building block. The documented path is\n * `ai.config({ panoptic: { dashboard } })`, which constructs (or reuses)\n * the store and calls this for you. Use it directly only when you manage\n * the store yourself.\n *\n * Binds loopback-only by default (`127.0.0.1`) so prompt content is never\n * exposed to the LAN. Pass `port: 0` for an ephemeral port — the resolved\n * port comes back on the handle. A port already in use rejects with a\n * clear, actionable `Error` rather than the raw `EADDRINUSE`.\n *\n * @example\n * const store = createInMemoryTraceStore();\n * const handle = await dashboard(store, { port: 4319, open: true });\n * console.log(handle.url); // http://127.0.0.1:4319/\n * // ...later:\n * await handle.close();\n */\nexport function dashboard(\n  store: TraceStoreContract,\n  options: DashboardOptions = {},\n): Promise<DashboardHandle> {\n  const port = options.port ?? DEFAULT_PORT;\n  const host = options.host ?? DEFAULT_HOST;\n  const title = options.title ?? DEFAULT_TITLE;\n  const basePath = normalizeBasePath(options.basePath);\n\n  // Secure-by-default off loopback (S4): a non-loopback bind without an\n  // auth token would expose raw prompt content to the network, so refuse\n  // to start rather than silently exposing it.\n  if (!isLoopbackHost(host) && !options.authToken) {\n    return Promise.reject(\n      new Error(\n        `Panoptic dashboard: binding to a non-loopback host (\"${host}\") requires an \\`authToken\\` ` +\n          \"(the dashboard exposes raw prompt content). Pass `authToken`, or bind to 127.0.0.1.\",\n      ),\n    );\n  }\n\n  const allowedHosts = (options.allowedHosts ?? defaultAllowedHosts(host)).map(h =>\n    h.toLowerCase(),\n  );\n\n  const handler = createRequestHandler(store, {\n    basePath,\n    title,\n    authToken: options.authToken,\n    allowedHosts,\n  });\n  const server = createServer(handler);\n\n  return new Promise<DashboardHandle>((resolve, reject) => {\n    const onError = (error: NodeJS.ErrnoException): void => {\n      server.off(\"error\", onError);\n\n      if (error.code === \"EADDRINUSE\") {\n        reject(\n          new Error(\n            `Panoptic dashboard: port ${port} in use; pass { port: 0 } for an ephemeral port`,\n          ),\n        );\n\n        return;\n      }\n\n      reject(error);\n    };\n\n    server.on(\"error\", onError);\n\n    server.listen(port, host, () => {\n      server.off(\"error\", onError);\n\n      const address = server.address();\n      const resolvedPort = typeof address === \"object\" && address !== null ? address.port : port;\n      const url = `http://${host}:${resolvedPort}${basePath}`;\n\n      if (options.open) {\n        openBrowser(url);\n      }\n\n      resolve({\n        url,\n        port: resolvedPort,\n        close(): Promise<void> {\n          return new Promise<void>((closeResolve, closeReject) => {\n            server.close((closeError) => {\n              if (closeError) {\n                closeReject(closeError);\n\n                return;\n              }\n\n              closeResolve();\n            });\n          });\n        },\n      });\n    });\n  });\n}\n\n/** Loopback hosts the dashboard may bind without an auth token. */\nfunction isLoopbackHost(host: string): boolean {\n  const h = host.toLowerCase();\n  return h === \"127.0.0.1\" || h === \"::1\" || h === \"[::1]\" || h === \"localhost\";\n}\n\n/**\n * Default `Host` allowlist for a given bind host. A loopback bind accepts\n * the loopback names a browser would send; a non-loopback bind defaults to\n * just the bound host (callers can widen via `allowedHosts`).\n */\nfunction defaultAllowedHosts(host: string): string[] {\n  if (isLoopbackHost(host)) {\n    return [\"localhost\", \"127.0.0.1\", \"[::1]\", \"::1\"];\n  }\n  return [host];\n}\n\n/**\n * Normalize a caller `basePath` to a leading-and-trailing-slash form the\n * router can prefix routes with. `undefined` / `\"\"` → `\"/\"`.\n */\nfunction normalizeBasePath(basePath?: string): string {\n  if (basePath === undefined || basePath.length === 0 || basePath === \"/\") {\n    return \"/\";\n  }\n\n  const withLeading = basePath.startsWith(\"/\") ? basePath : `/${basePath}`;\n\n  return withLeading.endsWith(\"/\") ? withLeading : `${withLeading}/`;\n}\n\n/**\n * Best-effort open of the default browser at `url`. Fire-and-forget and\n * fully swallowed — failing to open a browser must never reject the\n * dashboard start. Uses the platform's native opener via a lazy\n * `node:child_process` import so the dependency is paid only when\n * `open: true`.\n */\nfunction openBrowser(url: string): void {\n  void import(\"node:child_process\")\n    .then(({ spawn }) => {\n      const command =\n        process.platform === \"win32\" ? \"cmd\" : process.platform === \"darwin\" ? \"open\" : \"xdg-open\";\n      const args = process.platform === \"win32\" ? [\"/c\", \"start\", \"\", url] : [url];\n\n      const child = spawn(command, args, { stdio: \"ignore\", detached: true });\n      child.on(\"error\", () => {\n        // Swallow — opening a browser is best-effort.\n      });\n      child.unref();\n    })\n    .catch(() => {\n      // Swallow — opening a browser is best-effort.\n    });\n}\n"],"mappings":";;;;AAKA,MAAM,eAAe;AACrB,MAAM,eAAe;AACrB,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;AA0BtB,SAAgB,UACd,OACA,UAA4B,CAAC,GACH;CAC1B,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,QAAQ,QAAQ,SAAS;CAC/B,MAAM,WAAW,kBAAkB,QAAQ,QAAQ;CAKnD,IAAI,CAAC,eAAe,IAAI,KAAK,CAAC,QAAQ,WACpC,OAAO,QAAQ,uBACb,IAAI,MACF,wDAAwD,KAAK,mHAE/D,CACF;CAGF,MAAM,gBAAgB,QAAQ,gBAAgB,oBAAoB,IAAI,EAAC,CAAE,KAAI,MAC3E,EAAE,YAAY,CAChB;CAQA,MAAM,SAAS,aANC,qBAAqB,OAAO;EAC1C;EACA;EACA,WAAW,QAAQ;EACnB;CACF,CACkC,CAAC;CAEnC,OAAO,IAAI,SAA0B,SAAS,WAAW;EACvD,MAAM,WAAW,UAAuC;GACtD,OAAO,IAAI,SAAS,OAAO;GAE3B,IAAI,MAAM,SAAS,cAAc;IAC/B,uBACE,IAAI,MACF,4BAA4B,KAAK,gDACnC,CACF;IAEA;GACF;GAEA,OAAO,KAAK;EACd;EAEA,OAAO,GAAG,SAAS,OAAO;EAE1B,OAAO,OAAO,MAAM,YAAY;GAC9B,OAAO,IAAI,SAAS,OAAO;GAE3B,MAAM,UAAU,OAAO,QAAQ;GAC/B,MAAM,eAAe,OAAO,YAAY,YAAY,YAAY,OAAO,QAAQ,OAAO;GACtF,MAAM,MAAM,UAAU,KAAK,GAAG,eAAe;GAE7C,IAAI,QAAQ,MACV,YAAY,GAAG;GAGjB,QAAQ;IACN;IACA,MAAM;IACN,QAAuB;KACrB,OAAO,IAAI,SAAe,cAAc,gBAAgB;MACtD,OAAO,OAAO,eAAe;OAC3B,IAAI,YAAY;QACd,YAAY,UAAU;QAEtB;OACF;OAEA,aAAa;MACf,CAAC;KACH,CAAC;IACH;GACF,CAAC;EACH,CAAC;CACH,CAAC;AACH;;AAGA,SAAS,eAAe,MAAuB;CAC7C,MAAM,IAAI,KAAK,YAAY;CAC3B,OAAO,MAAM,eAAe,MAAM,SAAS,MAAM,WAAW,MAAM;AACpE;;;;;;AAOA,SAAS,oBAAoB,MAAwB;CACnD,IAAI,eAAe,IAAI,GACrB,OAAO;EAAC;EAAa;EAAa;EAAS;CAAK;CAElD,OAAO,CAAC,IAAI;AACd;;;;;AAMA,SAAS,kBAAkB,UAA2B;CACpD,IAAI,aAAa,UAAa,SAAS,WAAW,KAAK,aAAa,KAClE,OAAO;CAGT,MAAM,cAAc,SAAS,WAAW,GAAG,IAAI,WAAW,IAAI;CAE9D,OAAO,YAAY,SAAS,GAAG,IAAI,cAAc,GAAG,YAAY;AAClE;;;;;;;;AASA,SAAS,YAAY,KAAmB;CACtC,AAAK,OAAO,qBAAqB,CAC9B,MAAM,EAAE,YAAY;EAKnB,MAAM,QAAQ,MAHZ,QAAQ,aAAa,UAAU,QAAQ,QAAQ,aAAa,WAAW,SAAS,YACrE,QAAQ,aAAa,UAAU;GAAC;GAAM;GAAS;GAAI;EAAG,IAAI,CAAC,GAAG,GAExC;GAAE,OAAO;GAAU,UAAU;EAAK,CAAC;EACtE,MAAM,GAAG,eAAe,CAExB,CAAC;EACD,MAAM,MAAM;CACd,CAAC,CAAC,CACD,YAAY,CAEb,CAAC;AACL"}

package/esm/dashboard/dashboard.type.d.mts

@@ -0,0 +1,63 @@
+//#region ../@warlock.js/ai-panoptic/src/dashboard/dashboard.type.d.ts
+/**
+ * Options for the local Panoptic {@link dashboard} server.
+ *
+ * Every field is optional and has a safe default. The dashboard is a dev
+ * tool over an in-memory trace store: it binds loopback-only by default
+ * (so prompt content is never accidentally exposed to the LAN), serves a
+ * single self-contained HTML page, and exposes a tiny read-only JSON API
+ * the page polls. There is no auth, persistence, or write surface.
+ */
+type DashboardOptions = {
+  /**
+   * TCP port to listen on. Default `4319`. Pass `0` for an ephemeral
+   * port — the OS-assigned port is then returned on
+   * {@link DashboardHandle.port}.
+   */
+  port?: number;
+  /**
+   * Host / interface to bind. Default `"127.0.0.1"` — loopback only, so
+   * the dashboard (and the prompt content it can surface) is never
+   * exposed beyond the local machine unless you opt in explicitly.
+   */
+  host?: string;
+  /**
+   * Mount-path prefix for the JSON API + UI. Default `"/"`. A non-root
+   * value (e.g. `"/panoptic"`) prefixes both the page and every
+   * `/api/...` route.
+   */
+  basePath?: string;
+  /**
+   * Open the default browser at the resolved URL once the server is
+   * listening. Default `false`.
+   */
+  open?: boolean; /** Title shown in the dashboard header. Default `"Panoptic"`. */
+  title?: string;
+  /**
+   * Bearer token required on every request (S4). When set, a request must
+   * present `Authorization: Bearer <token>` (or `?token=<token>`), else
+   * `401`. **Required** when binding to a non-loopback `host` — starting
+   * the dashboard on a public interface without a token throws.
+   */
+  authToken?: string;
+  /**
+   * `Host` header allowlist (S4) — defends against DNS-rebinding. A
+   * request whose `Host` is not listed gets `403`. Defaults to the
+   * loopback names (`localhost`, `127.0.0.1`, `[::1]`) for a loopback
+   * bind; for a non-loopback bind you must list the expected host(s).
+   */
+  allowedHosts?: string[];
+};
+/**
+ * Handle returned by {@link dashboard} once the server is listening.
+ * Carries the resolved URL + port (useful when `port: 0` requested an
+ * ephemeral one) and a `close()` to release the port.
+ */
+type DashboardHandle = {
+  /** Resolved URL the UI is served at (`http://host:port{basePath}`). */readonly url: string; /** Resolved port — the real OS-assigned port when `port: 0` was passed. */
+  readonly port: number; /** Stop the server and release the port. Resolves once fully closed. */
+  close(): Promise<void>;
+};
+//#endregion
+export { DashboardHandle, DashboardOptions };
+//# sourceMappingURL=dashboard.type.d.mts.map

package/esm/dashboard/dashboard.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/dashboard/dashboard.type.ts"],"mappings":";;AASA;;;;;;;;KAAY,gBAAA;EAgCV;;;AAOY;AAQd;EAzCE,IAAA;;;;;;EAMA,IAAA;EAyCgB;AAAA;;;;EAnChB,QAAA;;;;;EAKA,IAAA;EAEA,KAAA;;;;;;;EAOA,SAAA;;;;;;;EAOA,YAAA;AAAA;;;;;;KAQU,eAAA;kFAED,GAAA;WAEA,IAAA;EAET,KAAA,IAAS,OAAO;AAAA"}

package/esm/dashboard/index.d.mts

@@ -0,0 +1,3 @@
+import { DashboardHandle, DashboardOptions } from "./dashboard.type.mjs";
+import { dashboard } from "./dashboard.mjs";
+import { NO_PROMPT_KEY, NO_SESSION_KEY, NO_TYPE_KEY, PromptGroup, SessionGroup, TraceFilter, TypeGroup, TypeStat, aggregateByType, filterTraces, groupByPrompt, groupBySession, groupByType, heatIntensity, matchesFilter, maxNodeCost, percentile, rollupCost, traceCost, tracePromptKey } from "./trace-filter.mjs";

package/esm/dashboard/parse-query.d.mts

@@ -0,0 +1 @@
+export { };

package/esm/dashboard/parse-query.mjs

@@ -0,0 +1,54 @@
+//#region ../@warlock.js/ai-panoptic/src/dashboard/parse-query.ts
+/**
+* The set of terminal statuses a stored trace can carry. Used to keep
+* `parseQuery` from forwarding arbitrary `?status=` junk into the store.
+*/
+const KNOWN_STATUSES = [
+	"completed",
+	"failed",
+	"cancelled",
+	"max-iterations",
+	"awaiting-input",
+	"awaiting-approval"
+];
+/**
+* Map a request's query string onto a {@link TraceQuery} the trace store
+* understands. Every field is optional — an absent param is "don't care",
+* so an empty query string yields an empty filter that matches every
+* stored trace.
+*
+* - `traceId` / `sessionId` — passed through verbatim (first value wins).
+* - `status` — **repeatable**: `?status=failed&status=cancelled` becomes
+*   `["failed", "cancelled"]`; a single value stays a scalar. Unknown
+*   status tokens are dropped so a typo never silently matches nothing in
+*   a confusing way (it simply isn't filtered on).
+* - `startedAfter` / `startedBefore` — forwarded as ISO strings; the
+*   store accepts either a string or `Date`, and `matchTrace` does the
+*   inclusive bound comparison.
+*
+* Unknown params are ignored. Pure — takes a `URLSearchParams`, returns a
+* plain object — so it's trivially testable without a live server.
+*
+* @example
+* parseQuery(new URLSearchParams("status=failed&status=cancelled&sessionId=s1"));
+* // → { status: ["failed", "cancelled"], sessionId: "s1" }
+*/
+function parseQuery(params) {
+	const query = {};
+	const traceId = params.get("traceId");
+	if (traceId !== null && traceId.length > 0) query.traceId = traceId;
+	const sessionId = params.get("sessionId");
+	if (sessionId !== null && sessionId.length > 0) query.sessionId = sessionId;
+	const statuses = params.getAll("status").filter((value) => KNOWN_STATUSES.includes(value));
+	if (statuses.length === 1) query.status = statuses[0];
+	else if (statuses.length > 1) query.status = statuses;
+	const startedAfter = params.get("startedAfter");
+	if (startedAfter !== null && startedAfter.length > 0) query.startedAfter = startedAfter;
+	const startedBefore = params.get("startedBefore");
+	if (startedBefore !== null && startedBefore.length > 0) query.startedBefore = startedBefore;
+	return query;
+}
+
+//#endregion
+export { parseQuery };
+//# sourceMappingURL=parse-query.mjs.map

package/esm/dashboard/parse-query.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-query.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/dashboard/parse-query.ts"],"sourcesContent":["import type { ReportStatus } from \"@warlock.js/ai\";\nimport type { TraceQuery } from \"../store/trace-query.type\";\n\n/**\n * The set of terminal statuses a stored trace can carry. Used to keep\n * `parseQuery` from forwarding arbitrary `?status=` junk into the store.\n */\nconst KNOWN_STATUSES: readonly ReportStatus[] = [\n  \"completed\",\n  \"failed\",\n  \"cancelled\",\n  \"max-iterations\",\n  \"awaiting-input\",\n  \"awaiting-approval\",\n] as const;\n\n/**\n * Map a request's query string onto a {@link TraceQuery} the trace store\n * understands. Every field is optional — an absent param is \"don't care\",\n * so an empty query string yields an empty filter that matches every\n * stored trace.\n *\n * - `traceId` / `sessionId` — passed through verbatim (first value wins).\n * - `status` — **repeatable**: `?status=failed&status=cancelled` becomes\n *   `[\"failed\", \"cancelled\"]`; a single value stays a scalar. Unknown\n *   status tokens are dropped so a typo never silently matches nothing in\n *   a confusing way (it simply isn't filtered on).\n * - `startedAfter` / `startedBefore` — forwarded as ISO strings; the\n *   store accepts either a string or `Date`, and `matchTrace` does the\n *   inclusive bound comparison.\n *\n * Unknown params are ignored. Pure — takes a `URLSearchParams`, returns a\n * plain object — so it's trivially testable without a live server.\n *\n * @example\n * parseQuery(new URLSearchParams(\"status=failed&status=cancelled&sessionId=s1\"));\n * // → { status: [\"failed\", \"cancelled\"], sessionId: \"s1\" }\n */\nexport function parseQuery(params: URLSearchParams): TraceQuery {\n  const query: TraceQuery = {};\n\n  const traceId = params.get(\"traceId\");\n  if (traceId !== null && traceId.length > 0) {\n    query.traceId = traceId;\n  }\n\n  const sessionId = params.get(\"sessionId\");\n  if (sessionId !== null && sessionId.length > 0) {\n    query.sessionId = sessionId;\n  }\n\n  const statuses = params\n    .getAll(\"status\")\n    .filter((value): value is ReportStatus => (KNOWN_STATUSES as readonly string[]).includes(value));\n  if (statuses.length === 1) {\n    query.status = statuses[0];\n  } else if (statuses.length > 1) {\n    query.status = statuses;\n  }\n\n  const startedAfter = params.get(\"startedAfter\");\n  if (startedAfter !== null && startedAfter.length > 0) {\n    query.startedAfter = startedAfter;\n  }\n\n  const startedBefore = params.get(\"startedBefore\");\n  if (startedBefore !== null && startedBefore.length > 0) {\n    query.startedBefore = startedBefore;\n  }\n\n  return query;\n}\n"],"mappings":";;;;;AAOA,MAAM,iBAA0C;CAC9C;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,WAAW,QAAqC;CAC9D,MAAM,QAAoB,CAAC;CAE3B,MAAM,UAAU,OAAO,IAAI,SAAS;CACpC,IAAI,YAAY,QAAQ,QAAQ,SAAS,GACvC,MAAM,UAAU;CAGlB,MAAM,YAAY,OAAO,IAAI,WAAW;CACxC,IAAI,cAAc,QAAQ,UAAU,SAAS,GAC3C,MAAM,YAAY;CAGpB,MAAM,WAAW,OACd,OAAO,QAAQ,CAAC,CAChB,QAAQ,UAAkC,eAAqC,SAAS,KAAK,CAAC;CACjG,IAAI,SAAS,WAAW,GACtB,MAAM,SAAS,SAAS;MACnB,IAAI,SAAS,SAAS,GAC3B,MAAM,SAAS;CAGjB,MAAM,eAAe,OAAO,IAAI,cAAc;CAC9C,IAAI,iBAAiB,QAAQ,aAAa,SAAS,GACjD,MAAM,eAAe;CAGvB,MAAM,gBAAgB,OAAO,IAAI,eAAe;CAChD,IAAI,kBAAkB,QAAQ,cAAc,SAAS,GACnD,MAAM,gBAAgB;CAGxB,OAAO;AACT"}

package/esm/dashboard/serve.d.mts

@@ -0,0 +1 @@
+export { };