@warlock.js/ai-panoptic 4.4.0 → 4.6.0

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

@@ -111,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":";;;;;AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,SAAA;EA2DG;;;;EAtDb,MAAA;EA0EmB;AAAA;AAQrB;;EA7EE,YAAA;EA6EwB;;;;;AAMnB;EA5EL,OAAA;EAqFe;;;;;EA/Ef,SAAA,WAqFM;EAnFN,IAAA;EAuFA;;;;;EAjFA,OAAA,WA2FmB;EAzFnB,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;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 { };

package/esm/dashboard/serve.mjs

@@ -0,0 +1,111 @@
+import { parseQuery } from "./parse-query.mjs";
+import { dashboardHtml } from "./ui.html.mjs";
+
+//#region ../@warlock.js/ai-panoptic/src/dashboard/serve.ts
+/**
+* Security response headers added to every dashboard response (S4):
+* block MIME-sniffing, framing, referrer leakage, and lock the page's
+* content sources down to itself (the UI is fully self-contained — no CDN).
+*/
+const SECURITY_HEADERS = {
+	"x-content-type-options": "nosniff",
+	"x-frame-options": "DENY",
+	"referrer-policy": "no-referrer",
+	"content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+};
+/** Extract the host (no port) from a `Host` header value. */
+function hostHeaderName(hostHeader) {
+	if (!hostHeader) return void 0;
+	if (hostHeader.startsWith("[")) return hostHeader.slice(0, hostHeader.indexOf("]") + 1);
+	const colon = hostHeader.indexOf(":");
+	return colon === -1 ? hostHeader : hostHeader.slice(0, colon);
+}
+/** Constant-ish bearer-token check from `Authorization` header or `?token=`. */
+function isAuthorized(req, url, token) {
+	const header = req.headers.authorization;
+	if (header && header === `Bearer ${token}`) return true;
+	return url.searchParams.get("token") === token;
+}
+/**
+* Build the `node:http` request handler for the dashboard over a given
+* trace store. Kept separate from the server lifecycle so it can be unit
+* tested by feeding it a fake `req`/`res` without binding a port.
+*
+* Routes (all under `config.basePath`, all read-only):
+*
+* - `GET api/traces`        → `store.query(parseQuery(searchParams))`
+* - `GET api/traces/:id`    → `store.get(id)` or `404`
+* - `GET api/aggregate`     → `store.aggregate(parseQuery(searchParams))`
+* - `GET {basePath}`        → the self-contained HTML page
+*
+* Anything else → `404`. Non-`GET` methods → `405`. The store shapes
+* ({@link Trace}/{@link TraceSpan}) are already JSON-safe, so responses
+* are a plain `JSON.stringify` with no serializer.
+*
+* @example
+* const handler = createRequestHandler(store, { basePath: "/", title: "Panoptic" });
+* http.createServer(handler).listen(4319, "127.0.0.1");
+*/
+function createRequestHandler(store, config) {
+	const base = config.basePath;
+	const apiPrefix = `${base}api`;
+	return function handle(req, res) {
+		if (req.method !== "GET") {
+			sendJson(res, 405, { error: "method_not_allowed" });
+			return;
+		}
+		const url = new URL(req.url ?? "/", "http://localhost");
+		const pathname = url.pathname;
+		const host = hostHeaderName(req.headers.host);
+		if (!host || !config.allowedHosts.includes(host.toLowerCase())) {
+			sendJson(res, 403, { error: "host_not_allowed" });
+			return;
+		}
+		if (config.authToken && !isAuthorized(req, url, config.authToken)) {
+			sendJson(res, 401, { error: "unauthorized" });
+			return;
+		}
+		if (pathname === `${apiPrefix}/traces`) {
+			sendJson(res, 200, store.query(parseQuery(url.searchParams)));
+			return;
+		}
+		if (pathname.startsWith(`${apiPrefix}/traces/`)) {
+			const traceId = decodeURIComponent(pathname.slice(`${apiPrefix}/traces/`.length));
+			const trace = traceId.length > 0 ? store.get(traceId) : void 0;
+			if (trace === void 0) {
+				sendJson(res, 404, {
+					error: "trace_not_found",
+					traceId
+				});
+				return;
+			}
+			sendJson(res, 200, trace);
+			return;
+		}
+		if (pathname === `${apiPrefix}/aggregate`) {
+			sendJson(res, 200, store.aggregate(parseQuery(url.searchParams)));
+			return;
+		}
+		if (pathname === base || pathname === base.replace(/\/$/, "")) {
+			res.writeHead(200, {
+				"content-type": "text/html; charset=utf-8",
+				...SECURITY_HEADERS
+			});
+			res.end(dashboardHtml(base, config.title));
+			return;
+		}
+		sendJson(res, 404, { error: "not_found" });
+	};
+}
+/** Write a JSON response with the given status code and security headers. */
+function sendJson(res, status, body) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		...SECURITY_HEADERS
+	});
+	res.end(JSON.stringify(body));
+}
+
+//#endregion
+export { createRequestHandler };
+//# sourceMappingURL=serve.mjs.map

package/esm/dashboard/serve.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-panoptic/src/dashboard/serve.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport type { TraceStoreContract } from \"../store/trace-store.contract\";\nimport { parseQuery } from \"./parse-query\";\nimport { dashboardHtml } from \"./ui.html\";\n\n/** Fully-resolved routing config the request handler closes over. */\nexport type ServeConfig = {\n  /** Normalized mount path, always ending in `/` (e.g. `\"/\"`). */\n  basePath: string;\n  /** Header title baked into the served page. */\n  title: string;\n  /** Bearer token required on every request when set (S4). */\n  authToken?: string;\n  /** `Host` header allowlist — defends against DNS-rebinding (S4). */\n  allowedHosts: string[];\n};\n\n/**\n * Security response headers added to every dashboard response (S4):\n * block MIME-sniffing, framing, referrer leakage, and lock the page's\n * content sources down to itself (the UI is fully self-contained — no CDN).\n */\nconst SECURITY_HEADERS: Record<string, string> = {\n  \"x-content-type-options\": \"nosniff\",\n  \"x-frame-options\": \"DENY\",\n  \"referrer-policy\": \"no-referrer\",\n  \"content-security-policy\":\n    \"default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'\",\n};\n\n/** Extract the host (no port) from a `Host` header value. */\nfunction hostHeaderName(hostHeader: string | undefined): string | undefined {\n  if (!hostHeader) return undefined;\n  // IPv6 literal `[::1]:4319` → `[::1]`; otherwise strip `:port`.\n  if (hostHeader.startsWith(\"[\")) {\n    return hostHeader.slice(0, hostHeader.indexOf(\"]\") + 1);\n  }\n  const colon = hostHeader.indexOf(\":\");\n  return colon === -1 ? hostHeader : hostHeader.slice(0, colon);\n}\n\n/** Constant-ish bearer-token check from `Authorization` header or `?token=`. */\nfunction isAuthorized(req: IncomingMessage, url: URL, token: string): boolean {\n  const header = req.headers.authorization;\n  if (header && header === `Bearer ${token}`) return true;\n  return url.searchParams.get(\"token\") === token;\n}\n\n/**\n * Build the `node:http` request handler for the dashboard over a given\n * trace store. Kept separate from the server lifecycle so it can be unit\n * tested by feeding it a fake `req`/`res` without binding a port.\n *\n * Routes (all under `config.basePath`, all read-only):\n *\n * - `GET api/traces`        → `store.query(parseQuery(searchParams))`\n * - `GET api/traces/:id`    → `store.get(id)` or `404`\n * - `GET api/aggregate`     → `store.aggregate(parseQuery(searchParams))`\n * - `GET {basePath}`        → the self-contained HTML page\n *\n * Anything else → `404`. Non-`GET` methods → `405`. The store shapes\n * ({@link Trace}/{@link TraceSpan}) are already JSON-safe, so responses\n * are a plain `JSON.stringify` with no serializer.\n *\n * @example\n * const handler = createRequestHandler(store, { basePath: \"/\", title: \"Panoptic\" });\n * http.createServer(handler).listen(4319, \"127.0.0.1\");\n */\nexport function createRequestHandler(\n  store: TraceStoreContract,\n  config: ServeConfig,\n): (req: IncomingMessage, res: ServerResponse) => void {\n  const base = config.basePath;\n  const apiPrefix = `${base}api`;\n\n  return function handle(req: IncomingMessage, res: ServerResponse): void {\n    if (req.method !== \"GET\") {\n      sendJson(res, 405, { error: \"method_not_allowed\" });\n\n      return;\n    }\n\n    // `req.url` is path + query only; a dummy origin lets URL parse it.\n    const url = new URL(req.url ?? \"/\", \"http://localhost\");\n    const pathname = url.pathname;\n\n    // Host-header allowlist — blocks DNS-rebinding attacks that point a\n    // hostile domain at this loopback port (S4).\n    const host = hostHeaderName(req.headers.host);\n    if (!host || !config.allowedHosts.includes(host.toLowerCase())) {\n      sendJson(res, 403, { error: \"host_not_allowed\" });\n\n      return;\n    }\n\n    // Bearer-token auth when configured (always required off loopback, S4).\n    if (config.authToken && !isAuthorized(req, url, config.authToken)) {\n      sendJson(res, 401, { error: \"unauthorized\" });\n\n      return;\n    }\n\n    if (pathname === `${apiPrefix}/traces`) {\n      sendJson(res, 200, store.query(parseQuery(url.searchParams)));\n\n      return;\n    }\n\n    if (pathname.startsWith(`${apiPrefix}/traces/`)) {\n      const traceId = decodeURIComponent(pathname.slice(`${apiPrefix}/traces/`.length));\n      const trace = traceId.length > 0 ? store.get(traceId) : undefined;\n\n      if (trace === undefined) {\n        sendJson(res, 404, { error: \"trace_not_found\", traceId });\n\n        return;\n      }\n\n      sendJson(res, 200, trace);\n\n      return;\n    }\n\n    if (pathname === `${apiPrefix}/aggregate`) {\n      sendJson(res, 200, store.aggregate(parseQuery(url.searchParams)));\n\n      return;\n    }\n\n    if (pathname === base || pathname === base.replace(/\\/$/, \"\")) {\n      res.writeHead(200, {\n        \"content-type\": \"text/html; charset=utf-8\",\n        ...SECURITY_HEADERS,\n      });\n      res.end(dashboardHtml(base, config.title));\n\n      return;\n    }\n\n    sendJson(res, 404, { error: \"not_found\" });\n  };\n}\n\n/** Write a JSON response with the given status code and security headers. */\nfunction sendJson(res: ServerResponse, status: number, body: unknown): void {\n  res.writeHead(status, {\n    \"content-type\": \"application/json; charset=utf-8\",\n    ...SECURITY_HEADERS,\n  });\n  res.end(JSON.stringify(body));\n}\n"],"mappings":";;;;;;;;;AAsBA,MAAM,mBAA2C;CAC/C,0BAA0B;CAC1B,mBAAmB;CACnB,mBAAmB;CACnB,2BACE;AACJ;;AAGA,SAAS,eAAe,YAAoD;CAC1E,IAAI,CAAC,YAAY,OAAO;CAExB,IAAI,WAAW,WAAW,GAAG,GAC3B,OAAO,WAAW,MAAM,GAAG,WAAW,QAAQ,GAAG,IAAI,CAAC;CAExD,MAAM,QAAQ,WAAW,QAAQ,GAAG;CACpC,OAAO,UAAU,KAAK,aAAa,WAAW,MAAM,GAAG,KAAK;AAC9D;;AAGA,SAAS,aAAa,KAAsB,KAAU,OAAwB;CAC5E,MAAM,SAAS,IAAI,QAAQ;CAC3B,IAAI,UAAU,WAAW,UAAU,SAAS,OAAO;CACnD,OAAO,IAAI,aAAa,IAAI,OAAO,MAAM;AAC3C;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,qBACd,OACA,QACqD;CACrD,MAAM,OAAO,OAAO;CACpB,MAAM,YAAY,GAAG,KAAK;CAE1B,OAAO,SAAS,OAAO,KAAsB,KAA2B;EACtE,IAAI,IAAI,WAAW,OAAO;GACxB,SAAS,KAAK,KAAK,EAAE,OAAO,qBAAqB,CAAC;GAElD;EACF;EAGA,MAAM,MAAM,IAAI,IAAI,IAAI,OAAO,KAAK,kBAAkB;EACtD,MAAM,WAAW,IAAI;EAIrB,MAAM,OAAO,eAAe,IAAI,QAAQ,IAAI;EAC5C,IAAI,CAAC,QAAQ,CAAC,OAAO,aAAa,SAAS,KAAK,YAAY,CAAC,GAAG;GAC9D,SAAS,KAAK,KAAK,EAAE,OAAO,mBAAmB,CAAC;GAEhD;EACF;EAGA,IAAI,OAAO,aAAa,CAAC,aAAa,KAAK,KAAK,OAAO,SAAS,GAAG;GACjE,SAAS,KAAK,KAAK,EAAE,OAAO,eAAe,CAAC;GAE5C;EACF;EAEA,IAAI,aAAa,GAAG,UAAU,UAAU;GACtC,SAAS,KAAK,KAAK,MAAM,MAAM,WAAW,IAAI,YAAY,CAAC,CAAC;GAE5D;EACF;EAEA,IAAI,SAAS,WAAW,GAAG,UAAU,SAAS,GAAG;GAC/C,MAAM,UAAU,mBAAmB,SAAS,MAAM,GAAG,UAAU,UAAU,MAAM,CAAC;GAChF,MAAM,QAAQ,QAAQ,SAAS,IAAI,MAAM,IAAI,OAAO,IAAI;GAExD,IAAI,UAAU,QAAW;IACvB,SAAS,KAAK,KAAK;KAAE,OAAO;KAAmB;IAAQ,CAAC;IAExD;GACF;GAEA,SAAS,KAAK,KAAK,KAAK;GAExB;EACF;EAEA,IAAI,aAAa,GAAG,UAAU,aAAa;GACzC,SAAS,KAAK,KAAK,MAAM,UAAU,WAAW,IAAI,YAAY,CAAC,CAAC;GAEhE;EACF;EAEA,IAAI,aAAa,QAAQ,aAAa,KAAK,QAAQ,OAAO,EAAE,GAAG;GAC7D,IAAI,UAAU,KAAK;IACjB,gBAAgB;IAChB,GAAG;GACL,CAAC;GACD,IAAI,IAAI,cAAc,MAAM,OAAO,KAAK,CAAC;GAEzC;EACF;EAEA,SAAS,KAAK,KAAK,EAAE,OAAO,YAAY,CAAC;CAC3C;AACF;;AAGA,SAAS,SAAS,KAAqB,QAAgB,MAAqB;CAC1E,IAAI,UAAU,QAAQ;EACpB,gBAAgB;EAChB,GAAG;CACL,CAAC;CACD,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC;AAC9B"}