@warlock.js/devtools 5.31.0 → 5.33.0

package/esm/sources/ai-source.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-source.mjs","names":[],"sources":["../../../../../../../../packages/devtools/src/sources/ai-source.ts"],"sourcesContent":["import type { Trace, TraceSpan, TraceStoreContract } from \"@warlock.js/ai-panoptic\";\nimport { toSafeValue } from \"../safe-value\";\nimport type { DevtoolsDisposer } from \"../types\";\n\nexport const AI_INSTALL_GUIDANCE =\n  \"Install @warlock.js/ai and @warlock.js/ai-panoptic, then restart warlock dev. Import @warlock.js/ai-panoptic and enable ai.config({ panoptic: { observeAll: true } }). If already installed, check that both packages are compatible and can be loaded.\";\n\nexport type DevtoolsAiEvent = { traceId: string; requestId?: string };\n\n/** Only the connector's development branch constructs this source. */\nexport type DevtoolsAiSource =\n  | { available: false; message: string; dispose: DevtoolsDisposer }\n  | {\n      available: true;\n      store: TraceStoreContract;\n      summarize: (trace: Trace) => DevtoolsAiRun;\n      subscribe: (listener: (event: DevtoolsAiEvent) => void) => DevtoolsDisposer;\n      dispose: DevtoolsDisposer;\n    };\n\nexport type DevtoolsAiRun = {\n  traceId: string;\n  requestId?: string;\n  sessionId?: string;\n  name: string;\n  status: TraceSpan[\"status\"];\n  startedAt: string;\n  duration: number;\n  usage: Trace[\"usage\"];\n  cost?: number;\n  models: string[];\n  toolCalls: number;\n  retries: number;\n  cacheHits?: number;\n  incomplete: boolean;\n  truncatedTrips: number;\n  compactions: number;\n  skippedCompactions: number;\n  providerCompactions: number;\n};\n\n/** Summaries use root usage once: nested spans already roll up into it. */\nexport function summarizeAiTrace(trace: Trace, cost?: number): DevtoolsAiRun {\n  const models = new Set<string>();\n  let toolCalls = 0;\n  let retries = 0;\n  let cacheHits: number | undefined;\n  let incomplete = false;\n  let truncatedTrips = 0;\n  let compactions = 0;\n  let skippedCompactions = 0;\n  let providerCompactions = 0;\n  const visit = (span: TraceSpan): void => {\n    const attributes = span.attributes ?? {};\n    const model = attributes[\"agent.model.name\"];\n    const provider = attributes[\"agent.model.provider\"];\n    if (typeof model === \"string\")\n      models.add(typeof provider === \"string\" ? `${provider}/${model}` : model);\n    if (span.type === \"tool\") toolCalls += 1;\n    if (typeof attributes.retries === \"number\") retries += attributes.retries;\n    if (typeof attributes[\"agent.cacheHits\"] === \"number\")\n      cacheHits = (cacheHits ?? 0) + attributes[\"agent.cacheHits\"];\n    if (typeof attributes[\"agent.truncatedTrips\"] === \"number\")\n      truncatedTrips += attributes[\"agent.truncatedTrips\"];\n    if (typeof attributes[\"agent.providerCompactions\"] === \"number\")\n      providerCompactions += attributes[\"agent.providerCompactions\"];\n    if (Array.isArray(attributes[\"agent.compactions\"])) {\n      const records: unknown[] = attributes[\"agent.compactions\"];\n      for (const record of records) {\n        if (typeof record !== \"object\" || record === null || !(\"type\" in record)) continue;\n        if (record.type === \"applied\") compactions += 1;\n        if (record.type === \"skipped\") skippedCompactions += 1;\n      }\n    }\n    incomplete ||=\n      span.status === \"incomplete\" ||\n      span.error?.type === \"AgentIncompleteError\" ||\n      span.error?.type === \"AGENT_INCOMPLETE\";\n    span.children.forEach(visit);\n  };\n  visit(trace.root);\n  return {\n    traceId: trace.traceId,\n    requestId: trace.requestId,\n    sessionId: trace.sessionId,\n    name: trace.root.name,\n    status: trace.root.status,\n    startedAt: trace.startedAt,\n    duration: trace.duration,\n    usage: trace.usage,\n    cost,\n    models: [...models],\n    toolCalls,\n    retries,\n    cacheHits,\n    incomplete,\n    truncatedTrips,\n    compactions,\n    skippedCompactions,\n    providerCompactions,\n  };\n}\n\n/** Content-free snapshot; never retain prompts, completions or tool arguments/results. */\nfunction snapshotSpan(span: TraceSpan): TraceSpan {\n  return {\n    spanId: span.spanId,\n    parentSpanId: span.parentSpanId,\n    traceId: span.traceId,\n    sessionId: span.sessionId,\n    name: span.name,\n    version: span.version,\n    type: span.type,\n    status: span.status,\n    startedAt: span.startedAt,\n    endedAt: span.endedAt,\n    duration: span.duration,\n    usage: structuredClone(span.usage),\n    error: span.error ? { type: span.error.type, message: span.error.message } : undefined,\n    attributes: toSafeValue(span.attributes) as Record<string, unknown> | undefined,\n    children: span.children.map(snapshotSpan),\n  };\n}\n\n/**\n * Optional, lazy integration. Retains only traces collected after devtools boots,\n * using Panoptic's bounded query store; existing exporter/cache stores stay independent.\n */\nexport async function attachAiSource(capacity: number): Promise<DevtoolsAiSource> {\n  let panoptic: typeof import(\"@warlock.js/ai-panoptic\");\n  try {\n    panoptic = await import(\"@warlock.js/ai-panoptic\");\n    if (typeof panoptic.subscribeTraces !== \"function\")\n      throw new Error(\"Trace subscription unavailable\");\n  } catch {\n    return { available: false, message: AI_INSTALL_GUIDANCE, dispose() {} };\n  }\n\n  const { currentRequestId } = await import(\"../current-request-id\");\n  const store = panoptic.createInMemoryTraceStore({ capacity });\n  const listeners = new Set<(event: DevtoolsAiEvent) => void>();\n  const detach = panoptic.subscribeTraces((trace) => {\n    // Read ALS before any asynchronous exporter work, including for runs that\n    // finish after the HTTP response. Never use sessionId as a request id.\n    const requestId = currentRequestId() ?? trace.requestId;\n    store.add({\n      ...trace,\n      requestId,\n      usage: structuredClone(trace.usage),\n      root: snapshotSpan(trace.root),\n    });\n    for (const listener of listeners) {\n      try {\n        listener({ traceId: trace.traceId, requestId });\n      } catch {\n        /* isolate clients */\n      }\n    }\n  });\n\n  return {\n    available: true,\n    store,\n    summarize: (trace) => summarizeAiTrace(trace, panoptic.totalCostUsd(trace.usage)),\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    dispose() {\n      detach();\n      listeners.clear();\n      store.clear();\n    },\n  };\n}\n"],"mappings":"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"}

package/esm/sources/log-source.mjs

@@ -1,5 +1,5 @@
-import { currentRequestId } from "../current-request-id.mjs";
 import { toSafeValue } from "../safe-value.mjs";
+import { currentRequestId } from "../current-request-id.mjs";
 import { LogChannel, log } from "@warlock.js/logger";
 
 //#region ../../packages/devtools/src/sources/log-source.ts

package/esm/sources/query-source.mjs

@@ -1,5 +1,5 @@
-import { currentRequestId } from "../current-request-id.mjs";
 import { toSafeValue } from "../safe-value.mjs";
+import { currentRequestId } from "../current-request-id.mjs";
 import { captureCallerLocation } from "../caller-location.mjs";
 import { applyRedact, log } from "@warlock.js/logger";
 

package/esm/types.d.mts

@@ -1,3 +1,4 @@
+import { DevtoolsAiEvent } from "./sources/ai-source.mjs";
 //#region ../../packages/devtools/src/types.d.ts
 /**
  * The records the devtools collector keeps and the dashboard API returns.
@@ -7,7 +8,7 @@
  * ring buffer that is lost on restart.
  */
 /** Options accepted by `devtoolsConnector()`. */
-type DevtoolsOptions = {
+export type DevtoolsOptions = {
   /**
    * URL prefix the dashboard and its API are served under.
    *
@@ -29,44 +30,49 @@ type DevtoolsOptions = {
   nPlusOneThreshold?: number;
 };
 /** `DevtoolsOptions` with every default applied. */
-type ResolvedDevtoolsOptions = Required<DevtoolsOptions>;
+export type ResolvedDevtoolsOptions = Required<DevtoolsOptions>;
 /** A source file position, as shown next to an N+1 warning. */
-type DevtoolsCallerLocation = {
-  /** Absolute path, forward slashes. */file: string;
+export type DevtoolsCallerLocation = {
+  /** Absolute path, forward slashes. */
+  file: string;
   line: number;
   column: number;
 };
 /** One timed phase of a request (router middleware, loader, render, …). */
-type DevtoolsPhase = {
+export type DevtoolsPhase = {
   name: string;
   startedAt: number;
   durationMs: number;
   attrs?: Record<string, unknown>;
 };
 /** One database query, Postgres or Mongo. */
-type DevtoolsQuery = {
-  /** Unique within the collector. */id: string;
+export type DevtoolsQuery = {
+  /** Unique within the collector. */
+  id: string;
   connection: string;
   driver: "postgres" | "mongodb";
-  sql?: string; /** Redacted through the logger's redaction rules before storage. */
+  sql?: string;
+  /** Redacted through the logger's redaction rules before storage. */
   bindings?: unknown[];
   collection?: string;
   command?: string;
   pipeline?: unknown;
   startedAt: number;
   durationMs: number;
-  rowCount?: number; /** The error message when the query failed. */
+  rowCount?: number;
+  /** The error message when the query failed. */
   error?: string;
   /**
    * The query with its values stripped — SQL text without bindings, or the
    * Mongo command with every leaf value replaced by `?`. Two queries with the
    * same shape are "the same query" for N+1 detection.
    */
-  shape: string; /** The first application frame that issued the query, when resolvable. */
+  shape: string;
+  /** The first application frame that issued the query, when resolvable. */
   caller?: DevtoolsCallerLocation;
 };
 /** One cache operation. */
-type DevtoolsCacheOperation = {
+export type DevtoolsCacheOperation = {
   type: "hit" | "miss" | "set" | "removed" | "invalidated" | "flushed";
   driver: string;
   key?: string;
@@ -76,16 +82,17 @@ type DevtoolsCacheOperation = {
   durationMs?: number;
 };
 /** One log entry. */
-type DevtoolsLogEntry = {
+export type DevtoolsLogEntry = {
   level: "debug" | "info" | "warn" | "error" | "success";
   module: string;
   action: string;
   message: string;
-  at: number; /** Redacted through the logger's redaction rules before storage. */
+  at: number;
+  /** Redacted through the logger's redaction rules before storage. */
   context?: unknown;
 };
 /** A mail captured in development (see core's `mailEvents.onCaptured`). */
-type DevtoolsMail = {
+export type DevtoolsMail = {
   id: string;
   requestId?: string;
   capturedAt: number;
@@ -100,13 +107,13 @@ type DevtoolsMail = {
   attachments: DevtoolsMailAttachment[];
 };
 /** Attachment metadata only — the bytes are never stored. */
-type DevtoolsMailAttachment = {
+export type DevtoolsMailAttachment = {
   filename: string;
   contentType?: string;
   size?: number;
 };
 /** A problem devtools noticed about a request. */
-type DevtoolsWarning = {
+export type DevtoolsWarning = {
   type: "n+1";
   message: string;
   shape: string;
@@ -114,24 +121,28 @@ type DevtoolsWarning = {
   caller?: DevtoolsCallerLocation;
 };
 /** Everything recorded for one HTTP request. */
-type DevtoolsRequest = {
-  /** The framework's `request.id`. */id: string;
+export type DevtoolsRequest = {
+  /** The framework's `request.id`. */
+  id: string;
   method: string;
-  path: string; /** Matched route pattern, e.g. `/posts/:slug`. */
+  path: string;
+  /** Matched route pattern, e.g. `/posts/:slug`. */
   route?: string;
   status?: number;
-  startedAt: number; /** Undefined while the request is still in flight. */
+  startedAt: number;
+  /** Undefined while the request is still in flight. */
   durationMs?: number;
   error?: string;
   phases: DevtoolsPhase[];
   queries: DevtoolsQuery[];
   cache: DevtoolsCacheOperation[];
-  logs: DevtoolsLogEntry[]; /** Ids of mails captured during this request (see `DevtoolsMail`). */
+  logs: DevtoolsLogEntry[];
+  /** Ids of mails captured during this request (see `DevtoolsMail`). */
   mails: string[];
   warnings: DevtoolsWarning[];
 };
 /** The row the request list shows; `GET <path>/api/requests` returns these. */
-type DevtoolsRequestSummary = {
+export type DevtoolsRequestSummary = {
   id: string;
   method: string;
   path: string;
@@ -143,7 +154,7 @@ type DevtoolsRequestSummary = {
   warningCount: number;
 };
 /** The row the mailbox list shows; `GET <path>/api/mails` returns these. */
-type DevtoolsMailSummary = {
+export type DevtoolsMailSummary = {
   id: string;
   requestId?: string;
   capturedAt: number;
@@ -154,13 +165,13 @@ type DevtoolsMailSummary = {
  * Work that happened outside any request (boot, a scheduler tick, a queue
  * job): kept separately so it never pollutes a request's timeline.
  */
-type DevtoolsBackground = {
+export type DevtoolsBackground = {
   queries: DevtoolsQuery[];
   cache: DevtoolsCacheOperation[];
   logs: DevtoolsLogEntry[];
 };
 /** Server-sent events on `GET <path>/api/stream`. */
-type DevtoolsStreamEvent = {
+export type DevtoolsStreamEvent = {
   type: "request";
   data: DevtoolsRequestSummary;
 } | {
@@ -169,29 +180,34 @@ type DevtoolsStreamEvent = {
 } | {
   type: "log";
   data: DevtoolsLogEntry;
+} | {
+  type: "ai";
+  data: DevtoolsAiEvent;
 };
 /** Unsubscribes a listener or detaches a source. */
-type DevtoolsDisposer = () => void;
+export type DevtoolsDisposer = () => void;
 /**
  * The in-memory store every source writes to and the dashboard API reads
  * from. `requestId` is the framework's `request.id`; `undefined` means the
  * work happened outside a request and goes to the background bucket.
  */
-type DevtoolsCollector = {
+export type DevtoolsCollector = {
   startRequest(request: {
     id: string;
     method: string;
     path: string;
     route?: string;
     startedAt: number;
-  }): void; /** Settles the request, runs N+1 detection and emits a `request` stream event. */
+  }): void;
+  /** Settles the request, runs N+1 detection and emits a `request` stream event. */
   endRequest(id: string, result: {
     status?: number;
     durationMs: number;
     error?: string;
     route?: string;
   }): void;
-  addPhase(requestId: string, phase: DevtoolsPhase): void; /** Computes `id` and `shape` itself. */
+  addPhase(requestId: string, phase: DevtoolsPhase): void;
+  /** Computes `id` and `shape` itself. */
   addQuery(requestId: string | undefined, query: Omit<DevtoolsQuery, "id" | "shape">): DevtoolsQuery;
   addCacheOperation(requestId: string | undefined, operation: DevtoolsCacheOperation): void;
   addLog(requestId: string | undefined, entry: DevtoolsLogEntry): void;
@@ -209,5 +225,4 @@ type DevtoolsCollector = {
   clear(): void;
 };
 //#endregion
-export { DevtoolsBackground, DevtoolsCacheOperation, DevtoolsCallerLocation, DevtoolsCollector, DevtoolsDisposer, DevtoolsLogEntry, DevtoolsMail, DevtoolsMailAttachment, DevtoolsMailSummary, DevtoolsOptions, DevtoolsPhase, DevtoolsQuery, DevtoolsRequest, DevtoolsRequestSummary, DevtoolsStreamEvent, DevtoolsWarning, ResolvedDevtoolsOptions };
 //# sourceMappingURL=types.d.mts.map

package/esm/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../packages/devtools/src/types.ts"],"mappings":";;AASA;;;;;;;KAAY,eAAA;EAmBO;AAInB;;;;EAjBE,IAAA;EAoBU;;;;;EAdV,WAAA;EAkBA;;AAAM;AAIR;;;EAfE,iBAAA;AAAA;;KAIU,uBAAA,GAA0B,QAAQ,CAAC,eAAA;;KAGnC,sBAAA;EAYI,sCAVd,IAAA;EACA,IAAA;EACA,MAAA;AAAA;;KAIU,aAAA;EACV,IAAA;EACA,SAAA;EACA,UAAA;EACA,KAAA,GAAQ,MAAM;AAAA;;KAIJ,aAAA;EAWV,mCATA,EAAA;EACA,UAAA;EACA,MAAA;EACA,GAAA,WAkBA;EAhBA,QAAA;EACA,UAAA;EACA,OAAA;EACA,QAAA;EACA,SAAA;EACA,UAAA;EACA,QAAA,WAeA;EAbA,KAAA;EAeA;;;;;EATA,KAAA,UAaU;EAXV,MAAA,GAAS,sBAAsB;AAAA;;KAIrB,sBAAA;EACV,IAAA;EACA,MAAA;EACA,GAAA;EACA,IAAA;EACA,IAAA;EACA,EAAA;EACA,UAAA;AAAA;AAeF;AAAA,KAXY,gBAAA;EACV,KAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;EACA,EAAA,UAUA;EARA,OAAA;AAAA;;KAIU,YAAA;EACV,EAAA;EACA,SAAA;EACA,UAAA;EACA,IAAA;EACA,EAAA;EACA,EAAA;EACA,GAAA;EACA,OAAA;EACA,IAAA;EACA,IAAA;EACA,OAAA,EAAS,MAAA;EACT,WAAA,EAAa,sBAAsB;AAAA;;KAIzB,sBAAA;EACV,QAAA;EACA,WAAA;EACA,IAAA;AAAA;;KAIU,eAAA;EACV,IAAA;EACA,OAAA;EACA,KAAA;EACA,KAAA;EACA,MAAA,GAAS,sBAAsB;AAAA;;KAIrB,eAAA;EAAA,oCAEV,EAAA;EACA,MAAA;EACA,IAAA,UASS;EAPT,KAAA;EACA,MAAA;EACA,SAAA,UAUyB;EARzB,UAAA;EACA,KAAA;EACA,MAAA,EAAQ,aAAA;EACR,OAAA,EAAS,aAAA;EACT,KAAA,EAAO,sBAAA;EACP,IAAA,EAAM,gBAAA,IAPN;EASA,KAAA;EACA,QAAA,EAAU,eAAA;AAAA;;KAIA,sBAAA;EACV,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,SAAA;EACA,UAAA;EACA,UAAA;EACA,YAAA;AAAA;AATF;AAAA,KAaY,mBAAA;EACV,EAAA;EACA,SAAA;EACA,UAAA;EACA,EAAA;EACA,OAAA;AAAA;;;;;KAOU,kBAAA;EACV,OAAA,EAAS,aAAA;EACT,KAAA,EAAO,sBAAA;EACP,IAAA,EAAM,gBAAA;AAAA;;KAII,mBAAA;EACN,IAAA;EAAiB,IAAA,EAAM,sBAAA;AAAA;EACvB,IAAA;EAAc,IAAA,EAAM,mBAAA;AAAA;EACpB,IAAA;EAAa,IAAA,EAAM,gBAAA;AAAA;;KAGb,gBAAA;;;;;;KAOA,iBAAA;EACV,YAAA,CAAa,OAAA;IACX,EAAA;IACA,MAAA;IACA,IAAA;IACA,KAAA;IACA,SAAA;EAAA,UAnB2B;EAsB7B,UAAA,CACE,EAAA,UACA,MAAA;IAAU,MAAA;IAAiB,UAAA;IAAoB,KAAA;IAAgB,KAAA;EAAA;EAEjE,QAAA,CAAS,SAAA,UAAmB,KAAA,EAAO,aAAA,SAzBd;EA2BrB,QAAA,CACE,SAAA,sBACA,KAAA,EAAO,IAAA,CAAK,aAAA,oBACX,aAAA;EACH,iBAAA,CAAkB,SAAA,sBAA+B,SAAA,EAAW,sBAAA;EAC5D,MAAA,CAAO,SAAA,sBAA+B,KAAA,EAAO,gBAAA;EAC7C,OAAA,CAAQ,IAAA,EAAM,YAAA;EACd,YAAA,IAAgB,sBAAA;EAChB,UAAA,CAAW,EAAA,WAAa,eAAA;EACxB,SAAA,IAAa,mBAAA;EACb,OAAA,CAAQ,EAAA,WAAa,YAAA;EACrB,QAAA,CAAS,MAAA;IAAW,KAAA,GAAQ,gBAAA;IAA2B,MAAA;EAAA,IAAoB,gBAAA;EAC3E,aAAA,IAAiB,kBAAA;EACjB,SAAA,CAAU,QAAA,GAAW,KAAA,EAAO,mBAAA,YAA+B,gBAAA;EAC3D,KAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../packages/devtools/src/types.ts"],"mappings":";;;;;;;;;;YAWY;;;;;;EAMV;;;;;;EAMA;;;;;;;EAOA;;;YAIU,0BAA0B,SAAS;;YAGnC;;EAEV;EACA;EACA;;;YAIU;EACV;EACA;EACA;EACA,QAAQ;;;YAIE;;EAEV;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;;;;;EAMA;;EAEA,SAAS;;;YAIC;EACV;EACA;EACA;EACA;EACA;EACA;EACA;;;YAIU;EACV;EACA;EACA;EACA;EACA;;EAEA;;;YAIU;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,SAAS;EACT,aAAa;;;YAIH;EACV;EACA;EACA;;;YAIU;EACV;EACA;EACA;EACA;EACA,SAAS;;;YAIC;;EAEV;EACA;EACA;;EAEA;EACA;EACA;;EAEA;EACA;EACA,QAAQ;EACR,SAAS;EACT,OAAO;EACP,MAAM;;EAEN;EACA,UAAU;;;YAIA;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;YAIU;EACV;EACA;EACA;EACA;EACA;;;;;;YAOU;EACV,SAAS;EACT,OAAO;EACP,MAAM;;;YAII;EACN;EAAiB,MAAM;;EACvB;EAAc,MAAM;;EACpB;EAAa,MAAM;;EACnB;EAAY,MAAM;;;YAGZ;;;;;;YAOA;EACV,aAAa;IACX;IACA;IACA;IACA;IACA;;;EAGF,WACE,YACA;IAAU;IAAiB;IAAoB;IAAgB;;EAEjE,SAAS,mBAAmB,OAAO;;EAEnC,SACE,+BACA,OAAO,KAAK,iCACX;EACH,kBAAkB,+BAA+B,WAAW;EAC5D,OAAO,+BAA+B,OAAO;EAC7C,QAAQ,MAAM;EACd,gBAAgB;EAChB,WAAW,aAAa;EACxB,aAAa;EACb,QAAQ,aAAa;EACrB,SAAS;IAAW,QAAQ;IAA2B;MAAoB;EAC3E,iBAAiB;EACjB,UAAU,WAAW,OAAO,+BAA+B;EAC3D"}

package/esm/ui-root.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ui-root.mjs","names":[],"sources":["../../../../../../../packages/devtools/src/ui-root.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nlet cachedUiRoot: string | undefined;\n\n/** Whether `dir` is this package's root: it has `ui/index.html` beside a `package.json` named `@warlock.js/devtools`. */\nfunction isPackageRoot(dir: string): boolean {\n  const indexHtml = path.join(dir, \"ui\", \"index.html\");\n  const packageJson = path.join(dir, \"package.json\");\n\n  if (!existsSync(indexHtml) || !existsSync(packageJson)) {\n    return false;\n  }\n\n  try {\n    const parsed = JSON.parse(readFileSync(packageJson, \"utf8\")) as { name?: string };\n    return parsed.name === \"@warlock.js/devtools\";\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Locate this package's `ui/` directory by walking up from the current\n * module's directory. Works from `src/` in development and from the built\n * `esm/`/`cjs/` output, since both sit beside `ui/` and `package.json` at\n * the package root.\n */\nexport function resolveUiRoot(): string {\n  if (cachedUiRoot) {\n    return cachedUiRoot;\n  }\n\n  let dir = path.dirname(fileURLToPath(import.meta.url));\n\n  while (true) {\n    if (isPackageRoot(dir)) {\n      cachedUiRoot = path.join(dir, \"ui\");\n      return cachedUiRoot;\n    }\n\n    const parent = path.dirname(dir);\n    if (parent === dir) {\n      throw new Error(\n        \"Could not locate the devtools UI directory: no ancestor of \" +\n          \"this module has a ui/index.html beside a package.json named \" +\n          \"@warlock.js/devtools.\",\n      );\n    }\n\n    dir = parent;\n  }\n}\n"],"mappings":";;;;;AAIA,IAAI;;AAGJ,SAAS,cAAc,KAAsB;CAC3C,MAAM,YAAY,KAAK,KAAK,KAAK,MAAM,YAAY;CACnD,MAAM,cAAc,KAAK,KAAK,KAAK,cAAc;CAEjD,IAAI,CAAC,WAAW,SAAS,KAAK,CAAC,WAAW,WAAW,GACnD,OAAO;CAGT,IAAI;EAEF,OADe,KAAK,MAAM,aAAa,aAAa,MAAM,CAC9C,CAAC,CAAC,SAAS;CACzB,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,gBAAwB;CACtC,IAAI,cACF,OAAO;CAGT,IAAI,MAAM,KAAK,QAAQ,cAAc,OAAO,KAAK,GAAG,CAAC;CAErD,OAAO,MAAM;EACX,IAAI,cAAc,GAAG,GAAG;GACtB,eAAe,KAAK,KAAK,KAAK,IAAI;GAClC,OAAO;EACT;EAEA,MAAM,SAAS,KAAK,QAAQ,GAAG;EAC/B,IAAI,WAAW,KACb,MAAM,IAAI,MACR,8IAGF;EAGF,MAAM;CACR;AACF"}
+{"version":3,"file":"ui-root.mjs","names":[],"sources":["../../../../../../../packages/devtools/src/ui-root.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nlet cachedUiRoot: string | undefined;\n\n/** Whether `dir` is this package's root: it has `ui/index.html` beside a `package.json` named `@warlock.js/devtools`. */\nfunction isPackageRoot(dir: string): boolean {\n  const indexHtml = path.join(dir, \"ui\", \"index.html\");\n  const packageJson = path.join(dir, \"package.json\");\n\n  if (!existsSync(indexHtml) || !existsSync(packageJson)) {\n    return false;\n  }\n\n  try {\n    const parsed = JSON.parse(readFileSync(packageJson, \"utf8\")) as { name?: string };\n    return parsed.name === \"@warlock.js/devtools\";\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Locate this package's `ui/` directory by walking up from the current\n * module's directory. Works from `src/` in development and from the built\n * `esm/`/`cjs/` output, since both sit beside `ui/` and `package.json` at\n * the package root.\n */\nexport function resolveUiRoot(): string {\n  if (cachedUiRoot) {\n    return cachedUiRoot;\n  }\n\n  let dir = path.dirname(fileURLToPath(import.meta.url));\n\n  while (true) {\n    if (isPackageRoot(dir)) {\n      cachedUiRoot = path.join(dir, \"ui\");\n      return cachedUiRoot;\n    }\n\n    const parent = path.dirname(dir);\n    if (parent === dir) {\n      throw new Error(\n        \"Could not locate the devtools UI directory: no ancestor of \" +\n          \"this module has a ui/index.html beside a package.json named \" +\n          \"@warlock.js/devtools.\",\n      );\n    }\n\n    dir = parent;\n  }\n}\n"],"mappings":";;;;;AAIA,IAAI;;AAGJ,SAAS,cAAc,KAAsB;CAC3C,MAAM,YAAY,KAAK,KAAK,KAAK,MAAM,YAAY;CACnD,MAAM,cAAc,KAAK,KAAK,KAAK,cAAc;CAEjD,IAAI,CAAC,WAAW,SAAS,KAAK,CAAC,WAAW,WAAW,GACnD,OAAO;CAGT,IAAI;EAEF,OADe,KAAK,MAAM,aAAa,aAAa,MAAM,CAC9C,CAAC,CAAC,SAAS;CACzB,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,gBAAwB;CACtC,IAAI,cACF,OAAO;CAGT,IAAI,MAAM,KAAK,QAAQ,cAAc,YAAY,GAAG,CAAC;CAErD,OAAO,MAAM;EACX,IAAI,cAAc,GAAG,GAAG;GACtB,eAAe,KAAK,KAAK,KAAK,IAAI;GAClC,OAAO;EACT;EAEA,MAAM,SAAS,KAAK,QAAQ,GAAG;EAC/B,IAAI,WAAW,KACb,MAAM,IAAI,MACR,8IAGF;EAGF,MAAM;CACR;AACF"}

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 ---
 name: devtools-overview
-description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
+description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, AI traces per HTTP request (model, tokens, cost, cache hits, tools, retries, truncation, compaction), the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
 ---
 
 # `@warlock.js/devtools` — overview
@@ -58,6 +58,78 @@ of it would fail to resolve there.
 Work outside a request (boot, scheduler ticks, queue jobs) goes to a separate
 background list, so it never clutters a request's timeline.
 
+## AI runs alongside HTTP requests
+
+The **AI** tab and each request's **AI runs** section display completed traces
+from optional `@warlock.js/ai-panoptic`. If it cannot be imported, the tab shows
+install/restart guidance and the other panels keep working.
+
+```bash
+warlock add devtools
+npm install @warlock.js/ai @warlock.js/ai-panoptic
+```
+
+At app boot, enable observation, then restart `warlock dev`:
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-panoptic";
+ai.config({ panoptic: { observeAll: true } });
+```
+
+No `dashboard: true` or extra listener port is needed. Existing `attach`,
+middleware and explicit collection through Panoptic's built-in collector also
+feed the panel. An installed but unobserved flow produces no trace.
+
+- `DevtoolsAiRun` and `DevtoolsAiEvent` are public types from
+  `@warlock.js/devtools`; `DevtoolsStreamEvent` includes the `ai` event.
+- Read all runs with `GET /__warlock/api/ai`, or filter by an exact HTTP id with
+  `GET /__warlock/api/ai?requestId=<encoded-id>`. Responses include `available`,
+  `runs` and a root-usage `aggregate`; unavailable responses contain `message`.
+- Inspect tools/timings, retry attempts and compaction records with
+  `GET /__warlock/api/ai/runs/<encoded-trace-id>` (404 when evicted). The existing
+  stream emits `ai` events with `{ traceId, requestId? }`.
+- Model, input/output/cache-read/cache-write tokens and historical USD cost come
+  from the trace, never a guessed price table. Unknown cost is unpriced. Root
+  usage includes children already; do not sum all spans for a run total.
+- Cache hits count trips reporting positive provider `cachedTokens`.
+  Semantic-cache hits have no explicit report flag and remain unreported; zero
+  tokens alone do not prove a hit. `—` means unreported rather than zero.
+- `incomplete` status or normalized `AGENT_INCOMPLETE` / `AgentIncompleteError`
+  marks truncation. Recovered truncated trips still contribute to their count.
+- Compaction metadata includes applied/skipped agent decisions and provider
+  compaction-block counts; summary content is omitted. Orchestrator result-only
+  compaction cannot be reconstructed from a report-only trace.
+
+A same-origin browser tool can consume the public types directly:
+
+```ts
+import type { DevtoolsAiEvent, DevtoolsAiRun, DevtoolsStreamEvent } from "@warlock.js/devtools";
+
+const response = await fetch("/__warlock/api/ai?requestId=request-42");
+const { runs }: { runs: DevtoolsAiRun[] } = await response.json();
+console.log(runs.map((run) => [run.traceId, run.usage, run.cost]));
+
+function handleStream(event: DevtoolsStreamEvent): void {
+  if (event.type === "ai") {
+    const update: DevtoolsAiEvent = event.data;
+    console.log(update.traceId, update.requestId);
+  }
+}
+handleStream({ type: "ai", data: { traceId: "run-42", requestId: "request-42" } });
+```
+
+Request correlation reads core's current request id at collection time, before
+exporters. Concurrent/late runs can retain their async context. No id means
+background; `sessionId` is never substituted. Replayed reports outside the
+request cannot recover its context automatically.
+
+Devtools retains its own content-free in-memory store, at most `maxRequests`
+traces (200 by default), independently of HTTP request retention. Clear/shutdown
+empties this view, leaving application exporter/cache stores alone. Boot-time
+and persisted traces are not replayed. The source only attaches in development;
+AI routes keep the same socket-loopback guard as every other panel.
+
 ## API docs
 
 `/__warlock/docs` renders the app's OpenAPI 3.1 document with [Scalar](https://github.com/scalar/scalar); the dashboard's **API** tab shows the same page and has a **Scalar | Swagger UI** switch (remembered in the browser). `/__warlock/docs/swagger` renders the same document with [Swagger UI](https://github.com/swagger-api/swagger-ui). The document comes from `GET /__warlock/api/openapi.json`, built in-process by core's `getDevelopmentOpenApiDocument()` from the routes already registered, so it is the same generator as `warlock generate.openapi` and follows your edits with no CLI run. It covers API routes (not pages): paths, parameters, request bodies from Seal validation, responses from each handler's `responseSchema`, `401`/`422` and bearer/cookie security from `authMiddleware()`. See core's `generate-openapi` topic for what is documented and how to declare it.
@@ -99,4 +171,16 @@ why the dashboard is development-only and loopback-only.
   cascade `dataSourceRegistry.on("query")`, core `mailEvents.onCaptured()` and
   the cache `invalidated` event are public APIs that also work without devtools.
 
+## Process supervision panel
+
+Run `npx warlock add process` to create an app-owned supervisor and
+`src/app/processes/devtools.ts`, exporting `processPanel = { list: () =>
+processes.list() }`. Devtools discovers this registration only in development.
+The **Processes** tab refreshes `GET /__warlock/api/processes`: PIDs, workload
+categories, labels, display commands, limits, enforcement, and peak memory.
+It excludes ownership tokens. Without registration the list is empty. The
+endpoint retains development/loopback guards and provides no stop action.
+Use the `supervise-processes` skill of `@warlock.js/process` for launch,
+recovery and stop APIs; configure one owner/registry per application instance.
+
 

package/llms.txt

@@ -6,4 +6,4 @@
 
 ## Skills
 
-- [devtools-overview](@warlock.js/devtools/devtools-overview/SKILL.md): Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.
+- [devtools-overview](@warlock.js/devtools/devtools-overview/SKILL.md): Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, AI traces per HTTP request (model, tokens, cost, cache hits, tools, retries, truncation, compaction), the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.

package/package.json

@@ -5,12 +5,16 @@
     "environment": "server"
   },
   "peerDependencies": {
-    "@warlock.js/cache": "5.31.0",
-    "@warlock.js/cascade": "5.31.0",
-    "@warlock.js/core": "5.31.0",
-    "@warlock.js/logger": "5.31.0"
+    "@warlock.js/ai-panoptic": "5.33.0",
+    "@warlock.js/cache": "5.33.0",
+    "@warlock.js/cascade": "5.33.0",
+    "@warlock.js/core": "5.33.0",
+    "@warlock.js/logger": "5.33.0"
   },
   "peerDependenciesMeta": {
+    "@warlock.js/ai-panoptic": {
+      "optional": true
+    },
     "@warlock.js/cache": {
       "optional": true
     },
@@ -34,7 +38,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.31.0",
+  "version": "5.33.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/devtools-overview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devtools-overview
-description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
+description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, AI traces per HTTP request (model, tokens, cost, cache hits, tools, retries, truncation, compaction), the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
 ---
 
 # `@warlock.js/devtools` — overview
@@ -50,6 +50,78 @@ of it would fail to resolve there.
 Work outside a request (boot, scheduler ticks, queue jobs) goes to a separate
 background list, so it never clutters a request's timeline.
 
+## AI runs alongside HTTP requests
+
+The **AI** tab and each request's **AI runs** section display completed traces
+from optional `@warlock.js/ai-panoptic`. If it cannot be imported, the tab shows
+install/restart guidance and the other panels keep working.
+
+```bash
+warlock add devtools
+npm install @warlock.js/ai @warlock.js/ai-panoptic
+```
+
+At app boot, enable observation, then restart `warlock dev`:
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-panoptic";
+ai.config({ panoptic: { observeAll: true } });
+```
+
+No `dashboard: true` or extra listener port is needed. Existing `attach`,
+middleware and explicit collection through Panoptic's built-in collector also
+feed the panel. An installed but unobserved flow produces no trace.
+
+- `DevtoolsAiRun` and `DevtoolsAiEvent` are public types from
+  `@warlock.js/devtools`; `DevtoolsStreamEvent` includes the `ai` event.
+- Read all runs with `GET /__warlock/api/ai`, or filter by an exact HTTP id with
+  `GET /__warlock/api/ai?requestId=<encoded-id>`. Responses include `available`,
+  `runs` and a root-usage `aggregate`; unavailable responses contain `message`.
+- Inspect tools/timings, retry attempts and compaction records with
+  `GET /__warlock/api/ai/runs/<encoded-trace-id>` (404 when evicted). The existing
+  stream emits `ai` events with `{ traceId, requestId? }`.
+- Model, input/output/cache-read/cache-write tokens and historical USD cost come
+  from the trace, never a guessed price table. Unknown cost is unpriced. Root
+  usage includes children already; do not sum all spans for a run total.
+- Cache hits count trips reporting positive provider `cachedTokens`.
+  Semantic-cache hits have no explicit report flag and remain unreported; zero
+  tokens alone do not prove a hit. `—` means unreported rather than zero.
+- `incomplete` status or normalized `AGENT_INCOMPLETE` / `AgentIncompleteError`
+  marks truncation. Recovered truncated trips still contribute to their count.
+- Compaction metadata includes applied/skipped agent decisions and provider
+  compaction-block counts; summary content is omitted. Orchestrator result-only
+  compaction cannot be reconstructed from a report-only trace.
+
+A same-origin browser tool can consume the public types directly:
+
+```ts
+import type { DevtoolsAiEvent, DevtoolsAiRun, DevtoolsStreamEvent } from "@warlock.js/devtools";
+
+const response = await fetch("/__warlock/api/ai?requestId=request-42");
+const { runs }: { runs: DevtoolsAiRun[] } = await response.json();
+console.log(runs.map((run) => [run.traceId, run.usage, run.cost]));
+
+function handleStream(event: DevtoolsStreamEvent): void {
+  if (event.type === "ai") {
+    const update: DevtoolsAiEvent = event.data;
+    console.log(update.traceId, update.requestId);
+  }
+}
+handleStream({ type: "ai", data: { traceId: "run-42", requestId: "request-42" } });
+```
+
+Request correlation reads core's current request id at collection time, before
+exporters. Concurrent/late runs can retain their async context. No id means
+background; `sessionId` is never substituted. Replayed reports outside the
+request cannot recover its context automatically.
+
+Devtools retains its own content-free in-memory store, at most `maxRequests`
+traces (200 by default), independently of HTTP request retention. Clear/shutdown
+empties this view, leaving application exporter/cache stores alone. Boot-time
+and persisted traces are not replayed. The source only attaches in development;
+AI routes keep the same socket-loopback guard as every other panel.
+
 ## API docs
 
 `/__warlock/docs` renders the app's OpenAPI 3.1 document with [Scalar](https://github.com/scalar/scalar); the dashboard's **API** tab shows the same page and has a **Scalar | Swagger UI** switch (remembered in the browser). `/__warlock/docs/swagger` renders the same document with [Swagger UI](https://github.com/swagger-api/swagger-ui). The document comes from `GET /__warlock/api/openapi.json`, built in-process by core's `getDevelopmentOpenApiDocument()` from the routes already registered, so it is the same generator as `warlock generate.openapi` and follows your edits with no CLI run. It covers API routes (not pages): paths, parameters, request bodies from Seal validation, responses from each handler's `responseSchema`, `401`/`422` and bearer/cookie security from `authMiddleware()`. See core's `generate-openapi` topic for what is documented and how to declare it.
@@ -90,3 +162,15 @@ why the dashboard is development-only and loopback-only.
 - Building your own tooling on the same hooks: core `registerTracingHooks()`,
   cascade `dataSourceRegistry.on("query")`, core `mailEvents.onCaptured()` and
   the cache `invalidated` event are public APIs that also work without devtools.
+
+## Process supervision panel
+
+Run `npx warlock add process` to create an app-owned supervisor and
+`src/app/processes/devtools.ts`, exporting `processPanel = { list: () =>
+processes.list() }`. Devtools discovers this registration only in development.
+The **Processes** tab refreshes `GET /__warlock/api/processes`: PIDs, workload
+categories, labels, display commands, limits, enforcement, and peak memory.
+It excludes ownership tokens. Without registration the list is empty. The
+endpoint retains development/loopback guards and provides no stop action.
+Use the `supervise-processes` skill of `@warlock.js/process` for launch,
+recovery and stop APIs; configure one owner/registry per application instance.

package/ui/app.css

@@ -361,3 +361,16 @@ details summary {
     grid-template-columns: 120px 1fr;
   }
 }
+
+.ai-span {
+  margin: 0.75rem 0 0.75rem 0.75rem;
+  padding-left: 0.75rem;
+  border-left: 2px solid currentColor;
+}
+.ai-span summary {
+  cursor: pointer;
+}
+.toolbar input {
+  flex: 1;
+  min-width: 12rem;
+}