@warlock.js/ai-panoptic 5.31.0 → 5.33.0

package/esm/store/match-trace.d.mts

@@ -1,6 +1,5 @@
 import { Trace } from "../contracts/trace.type.mjs";
 import { TraceQuery } from "./trace-query.type.mjs";
-
 //#region ../../packages/ai-panoptic/src/store/match-trace.d.ts
 /**
  * Test whether one trace satisfies a {@link TraceQuery}. Every declared
@@ -15,7 +14,6 @@ import { TraceQuery } from "./trace-query.type.mjs";
  * Pure — used by the store's `query` and `aggregate` so both share one
  * matching definition.
  */
-declare function matchTrace(trace: Trace, filter?: TraceQuery): boolean;
+export declare function matchTrace(trace: Trace, filter?: TraceQuery): boolean;
 //#endregion
-export { matchTrace };
 //# sourceMappingURL=match-trace.d.mts.map

package/esm/store/match-trace.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"match-trace.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/match-trace.ts"],"mappings":";;;;;;AAiBA;;;;;;;;;AAA4D;;iBAA5C,UAAA,CAAW,KAAA,EAAO,KAAA,EAAO,MAAA,GAAS,UAAU"}
+{"version":3,"file":"match-trace.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/match-trace.ts"],"mappings":";;;;;;;;;;;;;;;;wBAiBgB,WAAW,OAAO,OAAO,SAAS"}

package/esm/store/match-trace.mjs

@@ -14,6 +14,7 @@
 */
 function matchTrace(trace, filter) {
 	if (!filter) return true;
+	if (filter.requestId !== void 0 && trace.requestId !== filter.requestId) return false;
 	if (filter.traceId !== void 0 && trace.traceId !== filter.traceId) return false;
 	if (filter.sessionId !== void 0 && trace.sessionId !== filter.sessionId) return false;
 	if (filter.status !== void 0 && !statusMatches(trace.root.status, filter.status)) return false;

package/esm/store/match-trace.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"match-trace.mjs","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/match-trace.ts"],"sourcesContent":["import type { ReportStatus } from \"@warlock.js/ai\";\nimport type { Trace } from \"../contracts/trace.type\";\nimport type { TraceQuery } from \"./trace-query.type\";\n\n/**\n * Test whether one trace satisfies a {@link TraceQuery}. Every declared\n * filter field must match (logical AND); absent fields are ignored, so\n * an empty / undefined filter matches every trace.\n *\n * Time bounds compare against the trace's root `startedAt`, parsed to\n * an epoch once per call, inclusive on both ends. Status accepts a\n * single value or an array (membership test). Identity fields are exact\n * string equality.\n *\n * Pure — used by the store's `query` and `aggregate` so both share one\n * matching definition.\n */\nexport function matchTrace(trace: Trace, filter?: TraceQuery): boolean {\n  if (!filter) {\n    return true;\n  }\n\n  if (filter.traceId !== undefined && trace.traceId !== filter.traceId) {\n    return false;\n  }\n\n  if (filter.sessionId !== undefined && trace.sessionId !== filter.sessionId) {\n    return false;\n  }\n\n  if (filter.status !== undefined && !statusMatches(trace.root.status, filter.status)) {\n    return false;\n  }\n\n  const startedAt = Date.parse(trace.startedAt);\n\n  if (filter.startedAfter !== undefined && startedAt < toEpoch(filter.startedAfter)) {\n    return false;\n  }\n\n  if (filter.startedBefore !== undefined && startedAt > toEpoch(filter.startedBefore)) {\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * Membership test for the status filter — true when `status` equals the\n * single wanted value, or is one of the wanted array.\n */\nfunction statusMatches(status: ReportStatus, wanted: ReportStatus | ReportStatus[]): boolean {\n  if (Array.isArray(wanted)) {\n    return wanted.includes(status);\n  }\n\n  return status === wanted;\n}\n\n/**\n * Normalize a time bound (ISO string or `Date`) to epoch milliseconds\n * for comparison against a parsed `startedAt`.\n */\nfunction toEpoch(bound: string | Date): number {\n  if (bound instanceof Date) {\n    return bound.getTime();\n  }\n\n  return Date.parse(bound);\n}\n"],"mappings":";;;;;;;;;;;;;;AAiBA,SAAgB,WAAW,OAAc,QAA8B;CACrE,IAAI,CAAC,QACH,OAAO;CAGT,IAAI,OAAO,YAAY,UAAa,MAAM,YAAY,OAAO,SAC3D,OAAO;CAGT,IAAI,OAAO,cAAc,UAAa,MAAM,cAAc,OAAO,WAC/D,OAAO;CAGT,IAAI,OAAO,WAAW,UAAa,CAAC,cAAc,MAAM,KAAK,QAAQ,OAAO,MAAM,GAChF,OAAO;CAGT,MAAM,YAAY,KAAK,MAAM,MAAM,SAAS;CAE5C,IAAI,OAAO,iBAAiB,UAAa,YAAY,QAAQ,OAAO,YAAY,GAC9E,OAAO;CAGT,IAAI,OAAO,kBAAkB,UAAa,YAAY,QAAQ,OAAO,aAAa,GAChF,OAAO;CAGT,OAAO;AACT;;;;;AAMA,SAAS,cAAc,QAAsB,QAAgD;CAC3F,IAAI,MAAM,QAAQ,MAAM,GACtB,OAAO,OAAO,SAAS,MAAM;CAG/B,OAAO,WAAW;AACpB;;;;;AAMA,SAAS,QAAQ,OAA8B;CAC7C,IAAI,iBAAiB,MACnB,OAAO,MAAM,QAAQ;CAGvB,OAAO,KAAK,MAAM,KAAK;AACzB"}
+{"version":3,"file":"match-trace.mjs","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/match-trace.ts"],"sourcesContent":["import type { ReportStatus } from \"@warlock.js/ai\";\nimport type { Trace } from \"../contracts/trace.type\";\nimport type { TraceQuery } from \"./trace-query.type\";\n\n/**\n * Test whether one trace satisfies a {@link TraceQuery}. Every declared\n * filter field must match (logical AND); absent fields are ignored, so\n * an empty / undefined filter matches every trace.\n *\n * Time bounds compare against the trace's root `startedAt`, parsed to\n * an epoch once per call, inclusive on both ends. Status accepts a\n * single value or an array (membership test). Identity fields are exact\n * string equality.\n *\n * Pure — used by the store's `query` and `aggregate` so both share one\n * matching definition.\n */\nexport function matchTrace(trace: Trace, filter?: TraceQuery): boolean {\n  if (!filter) {\n    return true;\n  }\n\n  if (filter.requestId !== undefined && trace.requestId !== filter.requestId) {\n    return false;\n  }\n\n  if (filter.traceId !== undefined && trace.traceId !== filter.traceId) {\n    return false;\n  }\n\n  if (filter.sessionId !== undefined && trace.sessionId !== filter.sessionId) {\n    return false;\n  }\n\n  if (filter.status !== undefined && !statusMatches(trace.root.status, filter.status)) {\n    return false;\n  }\n\n  const startedAt = Date.parse(trace.startedAt);\n\n  if (filter.startedAfter !== undefined && startedAt < toEpoch(filter.startedAfter)) {\n    return false;\n  }\n\n  if (filter.startedBefore !== undefined && startedAt > toEpoch(filter.startedBefore)) {\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * Membership test for the status filter — true when `status` equals the\n * single wanted value, or is one of the wanted array.\n */\nfunction statusMatches(status: ReportStatus, wanted: ReportStatus | ReportStatus[]): boolean {\n  if (Array.isArray(wanted)) {\n    return wanted.includes(status);\n  }\n\n  return status === wanted;\n}\n\n/**\n * Normalize a time bound (ISO string or `Date`) to epoch milliseconds\n * for comparison against a parsed `startedAt`.\n */\nfunction toEpoch(bound: string | Date): number {\n  if (bound instanceof Date) {\n    return bound.getTime();\n  }\n\n  return Date.parse(bound);\n}\n"],"mappings":";;;;;;;;;;;;;;AAiBA,SAAgB,WAAW,OAAc,QAA8B;CACrE,IAAI,CAAC,QACH,OAAO;CAGT,IAAI,OAAO,cAAc,UAAa,MAAM,cAAc,OAAO,WAC/D,OAAO;CAGT,IAAI,OAAO,YAAY,UAAa,MAAM,YAAY,OAAO,SAC3D,OAAO;CAGT,IAAI,OAAO,cAAc,UAAa,MAAM,cAAc,OAAO,WAC/D,OAAO;CAGT,IAAI,OAAO,WAAW,UAAa,CAAC,cAAc,MAAM,KAAK,QAAQ,OAAO,MAAM,GAChF,OAAO;CAGT,MAAM,YAAY,KAAK,MAAM,MAAM,SAAS;CAE5C,IAAI,OAAO,iBAAiB,UAAa,YAAY,QAAQ,OAAO,YAAY,GAC9E,OAAO;CAGT,IAAI,OAAO,kBAAkB,UAAa,YAAY,QAAQ,OAAO,aAAa,GAChF,OAAO;CAGT,OAAO;AACT;;;;;AAMA,SAAS,cAAc,QAAsB,QAAgD;CAC3F,IAAI,MAAM,QAAQ,MAAM,GACtB,OAAO,OAAO,SAAS,MAAM;CAG/B,OAAO,WAAW;AACpB;;;;;AAMA,SAAS,QAAQ,OAA8B;CAC7C,IAAI,iBAAiB,MACnB,OAAO,MAAM,QAAQ;CAGvB,OAAO,KAAK,MAAM,KAAK;AACzB"}

package/esm/store/sum-usage.d.mts

@@ -1,34 +1,8 @@
 import { Usage } from "@warlock.js/ai";
-
 //#region ../../packages/ai-panoptic/src/store/sum-usage.d.ts
-/**
- * Fold a child {@link Usage} into a running accumulator. Token channels
- * (`input` / `output` / `total`) always sum; the optional cache /
- * reasoning channels (`cachedTokens` / `cacheWriteTokens` /
- * `reasoningTokens`) sum only when at least one side reported them, so
- * a provider that never meters a channel doesn't fabricate a `0` for
- * it. The `cost` breakdown is merged with the core framework's
- * {@link accumulateCost}, keeping cost-rollup semantics identical to a
- * native report tree — an unpriced contributor never erases a priced
- * one.
- *
- * Pure: returns a fresh `Usage`, never mutates either argument. Seed an
- * aggregation with {@link emptyUsage}.
- *
- * @example
- * let total = emptyUsage();
- * for (const trace of traces) {
- *   total = sumUsage(total, trace.usage);
- * }
- */
-declare function sumUsage(accumulator: Usage, next: Usage): Usage;
-/**
- * A zero-valued {@link Usage} to seed an aggregation. Only the required
- * token channels are set; optional channels stay absent until a
- * contributor reports them, preserving the "never reported" vs
- * "reported as 0" distinction.
- */
-declare function emptyUsage(): Usage;
+/** Return an independent all-channel usage rollup, preserving hosted-tool counters. */
+export declare function sumUsage(accumulator: Usage, next: Usage): Usage;
+/** Seed an aggregation without claiming any optional counter was reported. */
+export declare function emptyUsage(): Usage;
 //#endregion
-export { emptyUsage, sumUsage };
 //# sourceMappingURL=sum-usage.d.mts.map

package/esm/store/sum-usage.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"sum-usage.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/sum-usage.ts"],"mappings":";;;;;AAsBA;;;;;;;;;;;;;;AAAgE;AAoChE;;;iBApCgB,QAAA,CAAS,WAAA,EAAa,KAAA,EAAO,IAAA,EAAM,KAAA,GAAQ,KAAA;AAoCxB;;;;;;AAAA,iBAAnB,UAAA,IAAc,KAAK"}
+{"version":3,"file":"sum-usage.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/sum-usage.ts"],"mappings":";;;wBAGgB,SAAS,aAAa,OAAO,MAAM,QAAQ;;wBAQ3C,cAAc"}

package/esm/store/sum-usage.mjs

@@ -1,48 +1,14 @@
-import { accumulateCost } from "@warlock.js/ai";
+import { mergeUsage } from "@warlock.js/ai";
 
 //#region ../../packages/ai-panoptic/src/store/sum-usage.ts
-/**
-* Fold a child {@link Usage} into a running accumulator. Token channels
-* (`input` / `output` / `total`) always sum; the optional cache /
-* reasoning channels (`cachedTokens` / `cacheWriteTokens` /
-* `reasoningTokens`) sum only when at least one side reported them, so
-* a provider that never meters a channel doesn't fabricate a `0` for
-* it. The `cost` breakdown is merged with the core framework's
-* {@link accumulateCost}, keeping cost-rollup semantics identical to a
-* native report tree — an unpriced contributor never erases a priced
-* one.
-*
-* Pure: returns a fresh `Usage`, never mutates either argument. Seed an
-* aggregation with {@link emptyUsage}.
-*
-* @example
-* let total = emptyUsage();
-* for (const trace of traces) {
-*   total = sumUsage(total, trace.usage);
-* }
-*/
+/** Return an independent all-channel usage rollup, preserving hosted-tool counters. */
 function sumUsage(accumulator, next) {
-	const merged = {
-		input: accumulator.input + next.input,
-		output: accumulator.output + next.output,
-		total: accumulator.total + next.total
-	};
-	const cachedTokens = sumOptional(accumulator.cachedTokens, next.cachedTokens);
-	if (cachedTokens !== void 0) merged.cachedTokens = cachedTokens;
-	const cacheWriteTokens = sumOptional(accumulator.cacheWriteTokens, next.cacheWriteTokens);
-	if (cacheWriteTokens !== void 0) merged.cacheWriteTokens = cacheWriteTokens;
-	const reasoningTokens = sumOptional(accumulator.reasoningTokens, next.reasoningTokens);
-	if (reasoningTokens !== void 0) merged.reasoningTokens = reasoningTokens;
-	const cost = accumulateCost(accumulator.cost, next.cost);
-	if (cost !== void 0) merged.cost = cost;
+	const merged = emptyUsage();
+	mergeUsage(merged, accumulator);
+	mergeUsage(merged, next);
 	return merged;
 }
-/**
-* A zero-valued {@link Usage} to seed an aggregation. Only the required
-* token channels are set; optional channels stay absent until a
-* contributor reports them, preserving the "never reported" vs
-* "reported as 0" distinction.
-*/
+/** Seed an aggregation without claiming any optional counter was reported. */
 function emptyUsage() {
 	return {
 		input: 0,
@@ -50,15 +16,6 @@ function emptyUsage() {
 		total: 0
 	};
 }
-/**
-* Add two optional token counts, treating either side's `undefined` as
-* zero — but return `undefined` when both are absent, so an unreported
-* channel stays unreported rather than collapsing to `0`.
-*/
-function sumOptional(accumulator, next) {
-	if (accumulator === void 0 && next === void 0) return;
-	return (accumulator ?? 0) + (next ?? 0);
-}
 
 //#endregion
 export { emptyUsage, sumUsage };

package/esm/store/sum-usage.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sum-usage.mjs","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/sum-usage.ts"],"sourcesContent":["import { accumulateCost, type Usage } from \"@warlock.js/ai\";\n\n/**\n * Fold a child {@link Usage} into a running accumulator. Token channels\n * (`input` / `output` / `total`) always sum; the optional cache /\n * reasoning channels (`cachedTokens` / `cacheWriteTokens` /\n * `reasoningTokens`) sum only when at least one side reported them, so\n * a provider that never meters a channel doesn't fabricate a `0` for\n * it. The `cost` breakdown is merged with the core framework's\n * {@link accumulateCost}, keeping cost-rollup semantics identical to a\n * native report tree — an unpriced contributor never erases a priced\n * one.\n *\n * Pure: returns a fresh `Usage`, never mutates either argument. Seed an\n * aggregation with {@link emptyUsage}.\n *\n * @example\n * let total = emptyUsage();\n * for (const trace of traces) {\n *   total = sumUsage(total, trace.usage);\n * }\n */\nexport function sumUsage(accumulator: Usage, next: Usage): Usage {\n  const merged: Usage = {\n    input: accumulator.input + next.input,\n    output: accumulator.output + next.output,\n    total: accumulator.total + next.total,\n  };\n\n  const cachedTokens = sumOptional(accumulator.cachedTokens, next.cachedTokens);\n  if (cachedTokens !== undefined) {\n    merged.cachedTokens = cachedTokens;\n  }\n\n  const cacheWriteTokens = sumOptional(accumulator.cacheWriteTokens, next.cacheWriteTokens);\n  if (cacheWriteTokens !== undefined) {\n    merged.cacheWriteTokens = cacheWriteTokens;\n  }\n\n  const reasoningTokens = sumOptional(accumulator.reasoningTokens, next.reasoningTokens);\n  if (reasoningTokens !== undefined) {\n    merged.reasoningTokens = reasoningTokens;\n  }\n\n  const cost = accumulateCost(accumulator.cost, next.cost);\n  if (cost !== undefined) {\n    merged.cost = cost;\n  }\n\n  return merged;\n}\n\n/**\n * A zero-valued {@link Usage} to seed an aggregation. Only the required\n * token channels are set; optional channels stay absent until a\n * contributor reports them, preserving the \"never reported\" vs\n * \"reported as 0\" distinction.\n */\nexport function emptyUsage(): Usage {\n  return {\n    input: 0,\n    output: 0,\n    total: 0,\n  };\n}\n\n/**\n * Add two optional token counts, treating either side's `undefined` as\n * zero — but return `undefined` when both are absent, so an unreported\n * channel stays unreported rather than collapsing to `0`.\n */\nfunction sumOptional(\n  accumulator: number | undefined,\n  next: number | undefined,\n): number | undefined {\n  if (accumulator === undefined && next === undefined) {\n    return undefined;\n  }\n\n  return (accumulator ?? 0) + (next ?? 0);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,SAAS,aAAoB,MAAoB;CAC/D,MAAM,SAAgB;EACpB,OAAO,YAAY,QAAQ,KAAK;EAChC,QAAQ,YAAY,SAAS,KAAK;EAClC,OAAO,YAAY,QAAQ,KAAK;CAClC;CAEA,MAAM,eAAe,YAAY,YAAY,cAAc,KAAK,YAAY;CAC5E,IAAI,iBAAiB,QACnB,OAAO,eAAe;CAGxB,MAAM,mBAAmB,YAAY,YAAY,kBAAkB,KAAK,gBAAgB;CACxF,IAAI,qBAAqB,QACvB,OAAO,mBAAmB;CAG5B,MAAM,kBAAkB,YAAY,YAAY,iBAAiB,KAAK,eAAe;CACrF,IAAI,oBAAoB,QACtB,OAAO,kBAAkB;CAG3B,MAAM,OAAO,eAAe,YAAY,MAAM,KAAK,IAAI;CACvD,IAAI,SAAS,QACX,OAAO,OAAO;CAGhB,OAAO;AACT;;;;;;;AAQA,SAAgB,aAAoB;CAClC,OAAO;EACL,OAAO;EACP,QAAQ;EACR,OAAO;CACT;AACF;;;;;;AAOA,SAAS,YACP,aACA,MACoB;CACpB,IAAI,gBAAgB,UAAa,SAAS,QACxC;CAGF,QAAQ,eAAe,MAAM,QAAQ;AACvC"}
+{"version":3,"file":"sum-usage.mjs","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/sum-usage.ts"],"sourcesContent":["import { mergeUsage, type Usage } from \"@warlock.js/ai\";\n\n/** Return an independent all-channel usage rollup, preserving hosted-tool counters. */\nexport function sumUsage(accumulator: Usage, next: Usage): Usage {\n  const merged = emptyUsage();\n  mergeUsage(merged, accumulator);\n  mergeUsage(merged, next);\n  return merged;\n}\n\n/** Seed an aggregation without claiming any optional counter was reported. */\nexport function emptyUsage(): Usage {\n  return { input: 0, output: 0, total: 0 };\n}\n"],"mappings":";;;;AAGA,SAAgB,SAAS,aAAoB,MAAoB;CAC/D,MAAM,SAAS,WAAW;CAC1B,WAAW,QAAQ,WAAW;CAC9B,WAAW,QAAQ,IAAI;CACvB,OAAO;AACT;;AAGA,SAAgB,aAAoB;CAClC,OAAO;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;AACzC"}

package/esm/store/trace-aggregate.type.d.mts

@@ -1,5 +1,4 @@
-import { ModelPricing, Usage } from "@warlock.js/ai";
-
+import { ModelCost, Usage } from "@warlock.js/ai";
 //#region ../../packages/ai-panoptic/src/store/trace-aggregate.type.d.ts
 /**
  * Rolled-up usage + cost across a set of stored traces, returned by the
@@ -21,10 +20,14 @@ import { ModelPricing, Usage } from "@warlock.js/ai";
  * console.log(`${stats.traces} runs, ${stats.usage.total} tokens`);
  * const totalUsd = totalCost(stats.cost) ?? 0; // `totalCost` from @warlock.js/ai
  */
-type TraceAggregate = {
-  /** Number of traces matched by the query. */traces: number; /** Count of matched traces whose root status was `"completed"`. */
-  completed: number; /** Count of matched traces whose root status was `"failed"` or `"incomplete"`. */
-  failed: number; /** Count of matched traces whose root status was `"cancelled"`. */
+export type TraceAggregate = {
+  /** Number of traces matched by the query. */
+  traces: number;
+  /** Count of matched traces whose root status was `"completed"`. */
+  completed: number;
+  /** Count of matched traces whose root status was `"failed"` or `"incomplete"`. */
+  failed: number;
+  /** Count of matched traces whose root status was `"cancelled"`. */
   cancelled: number;
   /**
    * Summed token usage across every matched trace. `input` / `output` /
@@ -36,12 +39,12 @@ type TraceAggregate = {
   /**
    * Merged per-channel USD cost across every matched trace, or
    * `undefined` when no matched trace carried pricing. Same shape as
-   * `ModelPricing` so callers can read the input/output/cache split,
+   * `ModelCost` so callers can read the input/output/cache split,
    * not just one opaque number.
    */
-  cost?: ModelPricing; /** Summed wall-clock duration in milliseconds across matched traces. */
+  cost?: ModelCost;
+  /** Summed wall-clock duration in milliseconds across matched traces. */
   totalDuration: number;
 };
 //#endregion
-export { TraceAggregate };
 //# sourceMappingURL=trace-aggregate.type.d.mts.map

package/esm/store/trace-aggregate.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-aggregate.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/trace-aggregate.type.ts"],"mappings":";;;;;AAsBA;;;;;;;;;;;;;;AAwBe;;;;KAxBH,cAAA;+CAEV,MAAA;EAEA,SAAA;EAEA,MAAA;EAEA,SAAA;;;;;;;EAOA,KAAA,EAAO,KAAA;;;;;;;EAOP,IAAA,GAAO,YAAY;EAEnB,aAAA;AAAA"}
+{"version":3,"file":"trace-aggregate.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/trace-aggregate.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;YAsBY;;EAEV;;EAEA;;EAEA;;EAEA;;;;;;;EAOA,OAAO;;;;;;;EAOP,OAAO;;EAEP"}

package/esm/store/trace-query.type.d.mts

@@ -1,5 +1,4 @@
 import { ReportStatus } from "@warlock.js/ai";
-
 //#region ../../packages/ai-panoptic/src/store/trace-query.type.d.ts
 /**
  * Filter passed to the trace store's `query` / `aggregate`. Every field
@@ -21,7 +20,9 @@ import { ReportStatus } from "@warlock.js/ai";
  * @example
  * const sessionSpend = store.aggregate({ sessionId: "session-42" });
  */
-type TraceQuery = {
+export type TraceQuery = {
+  /** Exact HTTP request correlation id; absent on background traces. */
+  requestId?: string;
   /**
    * Match a single trace by its `traceId` (equals the root run's
    * `runId`). The most specific filter — narrows to at most one trace.
@@ -36,10 +37,11 @@ type TraceQuery = {
    * Match traces whose root terminal `status` equals this value, or any
    * of these values when an array is given.
    */
-  status?: ReportStatus | ReportStatus[]; /** Inclusive lower bound on the trace's root `startedAt`. */
-  startedAfter?: string | Date; /** Inclusive upper bound on the trace's root `startedAt`. */
+  status?: ReportStatus | ReportStatus[];
+  /** Inclusive lower bound on the trace's root `startedAt`. */
+  startedAfter?: string | Date;
+  /** Inclusive upper bound on the trace's root `startedAt`. */
   startedBefore?: string | Date;
 };
 //#endregion
-export { TraceQuery };
 //# sourceMappingURL=trace-query.type.d.mts.map

package/esm/store/trace-query.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-query.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/trace-query.type.ts"],"mappings":";;;;;AAsBA;;;;;;;;;;;;;;;;;;KAAY,UAAA;EAmBmB;;;;EAd7B,OAAA;;;;;EAKA,SAAA;;;;;EAKA,MAAA,GAAS,YAAA,GAAe,YAAA;EAExB,YAAA,YAAwB,IAAA;EAExB,aAAA,YAAyB,IAAA;AAAA"}
+{"version":3,"file":"trace-query.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/trace-query.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;YAsBY;;EAEV;;;;;EAKA;;;;;EAKA;;;;;EAKA,SAAS,eAAe;;EAExB,wBAAwB;;EAExB,yBAAyB"}

package/esm/store/trace-store.contract.d.mts

@@ -1,7 +1,6 @@
 import { Trace } from "../contracts/trace.type.mjs";
 import { TraceAggregate } from "./trace-aggregate.type.mjs";
 import { TraceQuery } from "./trace-query.type.mjs";
-
 //#region ../../packages/ai-panoptic/src/store/trace-store.contract.d.ts
 /**
  * Contract for a Panoptic trace store — a queryable sink that retains
@@ -26,7 +25,7 @@ import { TraceQuery } from "./trace-query.type.mjs";
  * const failed = store.query({ status: "failed" });
  * const spend = store.aggregate({ sessionId });
  */
-interface TraceStoreContract {
+export interface TraceStoreContract {
   /**
    * Ingest one finalized trace. Replaces any existing trace with the
    * same `traceId` (re-collecting a run overwrites rather than
@@ -51,5 +50,4 @@ interface TraceStoreContract {
   clear(): void;
 }
 //#endregion
-export { TraceStoreContract };
 //# sourceMappingURL=trace-store.contract.d.mts.map

package/esm/store/trace-store.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-store.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/trace-store.contract.ts"],"mappings":";;;;;;;AA2BA;;;;;;;;;;;;;;;;;;;;;UAAiB,kBAAA;EAqBI;;;;;EAfnB,GAAA,CAAI,KAAA,EAAO,KAAA;EAqBN;EAlBL,GAAA,CAAI,OAAA,WAAkB,KAAA;;;;;EAMtB,KAAA,CAAM,MAAA,GAAS,UAAA,GAAa,KAAA;;;;;EAM5B,SAAA,CAAU,MAAA,GAAS,UAAA,GAAa,cAAA;;WAGvB,IAAA;;EAGT,KAAA;AAAA"}
+{"version":3,"file":"trace-store.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-panoptic/src/store/trace-store.contract.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BiB;;;;;;EAMf,IAAI,OAAO;;EAGX,IAAI,kBAAkB;;;;;EAMtB,MAAM,SAAS,aAAa;;;;;EAM5B,UAAU,SAAS,aAAa;;WAGvB;;EAGT"}

package/llms-full.txt

@@ -472,6 +472,41 @@ Add exporters after construction with `observe.use(exporter)` (chainable, dedupe
 - The `query-traces` topic — retaining traces in the queryable in-memory store and slicing them (`query` / `aggregate` / `capacity`).
 - The `run-ai-agent` topic of the `warlock-js-ai` skill — running the agent and the `BaseReport` shape Panoptic consumes.
 
+## Subscribe across collectors and inspect requests in devtools
+
+`subscribeTraces(listener)` is a process-local adapter hook: it receives every
+finalized trace from built-in collectors (including ones created earlier), in
+the collecting async context, before exporter dispatch. It has no replay and
+adds no retention. It does not enable observation or subscribe to pure
+`toTrace()` calls. Treat incoming traces as read-only. Listener throws/rejections
+are isolated; promises are not awaited.
+
+```ts
+import { subscribeTraces } from "@warlock.js/ai-panoptic";
+import type { TraceListener } from "@warlock.js/ai-panoptic";
+
+const onTrace: TraceListener = (trace) => {
+  console.log(trace.traceId, trace.root.status, trace.usage);
+};
+const unsubscribe = subscribeTraces(onTrace);
+// ...later, on adapter teardown:
+unsubscribe();
+```
+
+With `@warlock.js/devtools` installed, its **AI** tab at `/__warlock` subscribes
+for you. Enable `ai.config({ panoptic: { observeAll: true } })` as above, or use
+an explicit subscriber. No `dashboard: true` is needed. Request-local context
+links runs to their HTTP request when available, independently of `sessionId`.
+The panel never mounts in production.
+
+New diagnostic attributes are `retry.attempts` (timings/outcomes),
+`agent.cacheHits` (trips reporting positive provider cache reads),
+`agent.truncatedTrips`, `agent.providerCompactions` and `agent.compactions`
+(applied/skipped decisions, trip indices, token counts and replaced ranges).
+They exclude compaction summaries and callback error text. Unknown cache hits
+remain absent; do not infer semantic-cache hits from zero tokens. An incomplete
+run is identified by its status or normalized `AGENT_INCOMPLETE` error code.
+
 
 ## query-traces  `@warlock.js/ai-panoptic/query-traces/SKILL.md`
 
@@ -532,6 +567,7 @@ Every field is optional and **ANDed** together — an absent field is "don't car
 ```ts
 type TraceQuery = {
   traceId?: string; // exact one run
+  requestId?: string; // exact HTTP request id, when an integration supplied it
   sessionId?: string; // every run for a session
   status?: ReportStatus | ReportStatus[]; // single status or membership set
   startedAfter?: string | Date; // inclusive lower bound on root startedAt
@@ -677,6 +713,54 @@ for (const trace of store.query({ sessionId })) {
 - The `export-traces` topic — sending traces to an external backend instead of (or alongside) retaining them in memory; writing a custom sink.
 - The `run-ai-agent` topic of the `warlock-js-ai` skill — the `BaseReport` the collector projects into the `Trace` this store retains.
 
+## Hosted-tool rollups
+
+`sumUsage` uses the framework's all-channel `mergeUsage`, so traces retain
+`usage.serverToolUse` and `usage.cost.serverTools` alongside cache lifetime
+counts and mixed-provider cache semantics. Request counts remain absent when
+unreported; unpriced requests do not erase priced siblings.
+
+```ts
+const stats = store.aggregate({ sessionId });
+console.log(stats.usage.serverToolUse?.webSearchRequests);
+console.log(stats.cost?.serverTools?.webSearch); // historical USD
+console.log(totalCost(stats.cost)); // includes hosted fees
+```
+
+## Correlate traces with HTTP requests
+
+`Trace.requestId` is an optional integration-supplied identity. It is independent
+of `sessionId`; legacy and background traces omit it. In-memory and cache stores
+use the same exact-match `requestId` filter in `query()` and `aggregate()`, and
+cache hydration preserves it.
+
+```ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createInMemoryTraceStore, subscribeTraces } from "@warlock.js/ai-panoptic";
+
+// Your HTTP adapter runs the flow inside this context.
+const httpContext = new AsyncLocalStorage<{ requestId: string }>();
+const requests = createInMemoryTraceStore({ capacity: 200 });
+const unsubscribe = subscribeTraces((trace) => {
+  requests.add({ ...trace, requestId: httpContext.getStore()?.requestId });
+});
+
+const runs = requests.query({ requestId: "request-42" });
+const usage = requests.aggregate({ requestId: "request-42" });
+unsubscribe();
+```
+
+The callback reads request context synchronously, before exporters run. It sees
+future collection from all built-in collectors, with no replay. Treat incoming
+traces as read-only and add an enriched copy. Errors are isolated, async
+callbacks are not awaited, and `toTrace()` does not notify subscribers.
+
+For app development, `@warlock.js/devtools` already does this: open the **AI** tab
+at `/__warlock`, or an HTTP request's **AI runs** section. Its bounded,
+content-free store is separate from your exporter/cache stores. Clearing the
+panel does not clear application trace history. Enable flow observation first;
+installing the viewer alone does not collect runs.
+
 
 ## use-local-dashboard  `@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md`
 
@@ -909,4 +993,25 @@ These three findings (link sanitization + the two token-handling items above) ca
 - The `export-traces` topic — shipping traces to OTel / Langfuse / a file instead of (or alongside) the local dashboard.
 - The `evaluate-system-prompt` topic — the drawer's "Evaluate system prompt" action, the dashboard's one write route.
 
+## Use the app's devtools AI panel
+
+When developing a Warlock HTTP app with `@warlock.js/devtools` installed, open
+`/__warlock` → **AI** to inspect runs alongside their HTTP requests. This uses
+the existing app server and needs no `dashboard: true`:
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-panoptic";
+ai.config({ panoptic: { observeAll: true } });
+```
+
+Restart `warlock dev` after installing the optional Panoptic package. Runs
+appear after collection, with model, tokens, historical cost, provider cache
+hits, tool timings, retries, incomplete/truncated status and compaction metadata.
+The panel uses a bounded content-free in-memory view (200 traces by default),
+not the standalone dashboard's persisted cache store. Clear/restart discards
+only that view. HTTP request identity is captured from the collecting async
+context; missing identities remain background runs. Devtools never mounts in
+production and retains its socket-loopback guard.
+
 

package/package.json

@@ -19,9 +19,9 @@
   "peerDependencies": {
     "@opentelemetry/api": "*",
     "@opentelemetry/sdk-trace-base": "*",
-    "@warlock.js/ai": "5.31.0",
-    "@warlock.js/cache": "5.31.0",
-    "@warlock.js/logger": "5.31.0",
+    "@warlock.js/ai": "5.33.0",
+    "@warlock.js/cache": "5.33.0",
+    "@warlock.js/logger": "5.33.0",
     "langfuse": "*"
   },
   "peerDependenciesMeta": {
@@ -41,7 +41,7 @@
   "dependencies": {
     "langfuse": "^3.38.20"
   },
-  "version": "5.31.0",
+  "version": "5.33.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/observe-with-panoptic/SKILL.md

@@ -173,3 +173,38 @@ Add exporters after construction with `observe.use(exporter)` (chainable, dedupe
 - The `export-traces` topic — the sink end: choosing/writing an exporter, the `gen_ai.*` / `warlock.*` attribute mapping.
 - The `query-traces` topic — retaining traces in the queryable in-memory store and slicing them (`query` / `aggregate` / `capacity`).
 - The `run-ai-agent` topic of the `warlock-js-ai` skill — running the agent and the `BaseReport` shape Panoptic consumes.
+
+## Subscribe across collectors and inspect requests in devtools
+
+`subscribeTraces(listener)` is a process-local adapter hook: it receives every
+finalized trace from built-in collectors (including ones created earlier), in
+the collecting async context, before exporter dispatch. It has no replay and
+adds no retention. It does not enable observation or subscribe to pure
+`toTrace()` calls. Treat incoming traces as read-only. Listener throws/rejections
+are isolated; promises are not awaited.
+
+```ts
+import { subscribeTraces } from "@warlock.js/ai-panoptic";
+import type { TraceListener } from "@warlock.js/ai-panoptic";
+
+const onTrace: TraceListener = (trace) => {
+  console.log(trace.traceId, trace.root.status, trace.usage);
+};
+const unsubscribe = subscribeTraces(onTrace);
+// ...later, on adapter teardown:
+unsubscribe();
+```
+
+With `@warlock.js/devtools` installed, its **AI** tab at `/__warlock` subscribes
+for you. Enable `ai.config({ panoptic: { observeAll: true } })` as above, or use
+an explicit subscriber. No `dashboard: true` is needed. Request-local context
+links runs to their HTTP request when available, independently of `sessionId`.
+The panel never mounts in production.
+
+New diagnostic attributes are `retry.attempts` (timings/outcomes),
+`agent.cacheHits` (trips reporting positive provider cache reads),
+`agent.truncatedTrips`, `agent.providerCompactions` and `agent.compactions`
+(applied/skipped decisions, trip indices, token counts and replaced ranges).
+They exclude compaction summaries and callback error text. Unknown cache hits
+remain absent; do not infer semantic-cache hits from zero tokens. An incomplete
+run is identified by its status or normalized `AGENT_INCOMPLETE` error code.

package/skills/query-traces/SKILL.md

@@ -55,6 +55,7 @@ Every field is optional and **ANDed** together — an absent field is "don't car
 ```ts
 type TraceQuery = {
   traceId?: string; // exact one run
+  requestId?: string; // exact HTTP request id, when an integration supplied it
   sessionId?: string; // every run for a session
   status?: ReportStatus | ReportStatus[]; // single status or membership set
   startedAfter?: string | Date; // inclusive lower bound on root startedAt
@@ -199,3 +200,51 @@ for (const trace of store.query({ sessionId })) {
 - The `observe-with-panoptic` topic — wiring the `panoptic(...)` subscriber and bring-your-own-collector so the store fills as runs complete.
 - The `export-traces` topic — sending traces to an external backend instead of (or alongside) retaining them in memory; writing a custom sink.
 - The `run-ai-agent` topic of the `warlock-js-ai` skill — the `BaseReport` the collector projects into the `Trace` this store retains.
+
+## Hosted-tool rollups
+
+`sumUsage` uses the framework's all-channel `mergeUsage`, so traces retain
+`usage.serverToolUse` and `usage.cost.serverTools` alongside cache lifetime
+counts and mixed-provider cache semantics. Request counts remain absent when
+unreported; unpriced requests do not erase priced siblings.
+
+```ts
+const stats = store.aggregate({ sessionId });
+console.log(stats.usage.serverToolUse?.webSearchRequests);
+console.log(stats.cost?.serverTools?.webSearch); // historical USD
+console.log(totalCost(stats.cost)); // includes hosted fees
+```
+
+## Correlate traces with HTTP requests
+
+`Trace.requestId` is an optional integration-supplied identity. It is independent
+of `sessionId`; legacy and background traces omit it. In-memory and cache stores
+use the same exact-match `requestId` filter in `query()` and `aggregate()`, and
+cache hydration preserves it.
+
+```ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createInMemoryTraceStore, subscribeTraces } from "@warlock.js/ai-panoptic";
+
+// Your HTTP adapter runs the flow inside this context.
+const httpContext = new AsyncLocalStorage<{ requestId: string }>();
+const requests = createInMemoryTraceStore({ capacity: 200 });
+const unsubscribe = subscribeTraces((trace) => {
+  requests.add({ ...trace, requestId: httpContext.getStore()?.requestId });
+});
+
+const runs = requests.query({ requestId: "request-42" });
+const usage = requests.aggregate({ requestId: "request-42" });
+unsubscribe();
+```
+
+The callback reads request context synchronously, before exporters run. It sees
+future collection from all built-in collectors, with no replay. Treat incoming
+traces as read-only and add an enriched copy. Errors are isolated, async
+callbacks are not awaited, and `toTrace()` does not notify subscribers.
+
+For app development, `@warlock.js/devtools` already does this: open the **AI** tab
+at `/__warlock`, or an HTTP request's **AI runs** section. Its bounded,
+content-free store is separate from your exporter/cache stores. Clearing the
+panel does not clear application trace history. Enable flow observation first;
+installing the viewer alone does not collect runs.

package/skills/use-local-dashboard/SKILL.md

@@ -226,3 +226,24 @@ These three findings (link sanitization + the two token-handling items above) ca
 - The `query-traces` topic — the `TraceStoreContract` (`query` / `get` / `aggregate`) the dashboard reads, the `TraceQuery` filter, and capacity eviction.
 - The `export-traces` topic — shipping traces to OTel / Langfuse / a file instead of (or alongside) the local dashboard.
 - The `evaluate-system-prompt` topic — the drawer's "Evaluate system prompt" action, the dashboard's one write route.
+
+## Use the app's devtools AI panel
+
+When developing a Warlock HTTP app with `@warlock.js/devtools` installed, open
+`/__warlock` → **AI** to inspect runs alongside their HTTP requests. This uses
+the existing app server and needs no `dashboard: true`:
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-panoptic";
+ai.config({ panoptic: { observeAll: true } });
+```
+
+Restart `warlock dev` after installing the optional Panoptic package. Runs
+appear after collection, with model, tokens, historical cost, provider cache
+hits, tool timings, retries, incomplete/truncated status and compaction metadata.
+The panel uses a bounded content-free in-memory view (200 traces by default),
+not the standalone dashboard's persisted cache store. Clear/restart discards
+only that view. HTTP request identity is captured from the collecting async
+context; missing identities remain background runs. Devtools never mounts in
+production and retains its socket-loopback guard.