@inkeep/agents-core 0.74.2 → 0.74.3

package/dist/utils/cache-debug-query.js

@@ -0,0 +1,70 @@
+import { AI_OPERATIONS, SPAN_KEYS } from "../constants/otel-attributes.js";
+import { FIELD_CONTEXTS, FIELD_DATA_TYPES, OPERATORS, ORDER_DIRECTIONS, QUERY_DEFAULTS, QUERY_EXPRESSIONS, QUERY_TYPES, REQUEST_TYPES, SIGNALS, buildFilterExpression } from "../constants/signoz-queries.js";
+
+//#region src/utils/cache-debug-query.ts
+const CACHE_DEBUG_QUERY_NAME = QUERY_EXPRESSIONS.AI_LLM_CALLS;
+const selectField = (name, fieldDataType, fieldContext) => ({
+	name,
+	fieldDataType,
+	fieldContext
+});
+function buildCacheDebugQuery(conversationId, options) {
+	const { start, end, projectId, limit = QUERY_DEFAULTS.LIMIT_UNLIMITED } = options;
+	const filterItems = [
+		{
+			key: SPAN_KEYS.CONVERSATION_ID,
+			op: OPERATORS.EQUALS,
+			value: conversationId
+		},
+		{
+			key: SPAN_KEYS.AI_OPERATION_ID,
+			op: OPERATORS.IN,
+			value: [AI_OPERATIONS.GENERATE_TEXT, AI_OPERATIONS.STREAM_TEXT]
+		},
+		...projectId ? [{
+			key: SPAN_KEYS.PROJECT_ID,
+			op: OPERATORS.EQUALS,
+			value: projectId
+		}] : []
+	];
+	return {
+		start,
+		end,
+		requestType: REQUEST_TYPES.RAW,
+		...projectId ? { projectId } : {},
+		compositeQuery: { queries: [{
+			type: QUERY_TYPES.BUILDER_QUERY,
+			spec: {
+				name: CACHE_DEBUG_QUERY_NAME,
+				signal: SIGNALS.TRACES,
+				filter: { expression: buildFilterExpression(filterItems) },
+				selectFields: [
+					selectField(SPAN_KEYS.SPAN_ID, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.SPAN),
+					selectField(SPAN_KEYS.TIMESTAMP, FIELD_DATA_TYPES.INT64, FIELD_CONTEXTS.SPAN),
+					selectField(SPAN_KEYS.AI_OPERATION_ID, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.AI_MODEL_ID, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.AI_TELEMETRY_GENERATION_TYPE, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.AI_TELEMETRY_SUB_AGENT_ID, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.AGENT_ID, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.AI_MODEL_PROVIDER, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.GEN_AI_RESPONSE_PROVIDER, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.GEN_AI_USAGE_INPUT_TOKENS, FIELD_DATA_TYPES.INT64, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, FIELD_DATA_TYPES.INT64, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS, FIELD_DATA_TYPES.INT64, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.CACHE_INTENT_MARKER_COUNT, FIELD_DATA_TYPES.INT64, FIELD_CONTEXTS.ATTRIBUTE),
+					selectField(SPAN_KEYS.CACHE_INTENT_PREFIX_SIGNATURE, FIELD_DATA_TYPES.STRING, FIELD_CONTEXTS.ATTRIBUTE)
+				],
+				order: [{
+					key: { name: SPAN_KEYS.TIMESTAMP },
+					direction: ORDER_DIRECTIONS.DESC
+				}],
+				limit,
+				stepInterval: QUERY_DEFAULTS.STEP_INTERVAL,
+				disabled: QUERY_DEFAULTS.DISABLED
+			}
+		}] }
+	};
+}
+
+//#endregion
+export { CACHE_DEBUG_QUERY_NAME, buildCacheDebugQuery };

package/dist/utils/cache-debug-walk.d.ts

@@ -0,0 +1,36 @@
+import { CacheState } from "./cache-state.js";
+
+//#region src/utils/cache-debug-walk.d.ts
+type CacheDebugSpanRow = {
+  data?: Record<string, unknown>;
+} & Record<string, unknown>;
+interface CacheDebugCall {
+  spanId: string;
+  timestamp: string;
+  operationId: string;
+  model: string;
+  modelProvider: string;
+  generationType: string;
+  subAgentId: string;
+  inputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  markerCount: number;
+  prefixSignature: string;
+  cacheState: CacheState;
+}
+/**
+ * Walk the LLM-span rows chronologically, deriving each call's cache state with
+ * a per-agent prior-signature cursor.
+ *
+ * The walk:
+ *   1. Sorts rows by `SPAN_KEYS.TIMESTAMP` (ascending).
+ *   2. For each row, resolves the sub-agent key via fallback chain
+ *      `AI_TELEMETRY_SUB_AGENT_ID -> AGENT_ID -> '_default'`.
+ *   3. Looks up that agent's prior signature in `priorSignatureByAgent`.
+ *   4. Calls `deriveCacheState` and, if the row's `prefix_signature` is non-empty,
+ *      updates the agent's cursor.
+ */
+declare function deriveCacheDebugCalls(rows: CacheDebugSpanRow[]): CacheDebugCall[];
+//#endregion
+export { CacheDebugCall, CacheDebugSpanRow, deriveCacheDebugCalls };

package/dist/utils/cache-debug-walk.js

@@ -0,0 +1,91 @@
+import { SPAN_KEYS } from "../constants/otel-attributes.js";
+import { deriveCacheState, isProviderSupportedForCaching, resolveCachingProvider } from "./cache-state.js";
+
+//#region src/utils/cache-debug-walk.ts
+/**
+* Pure cache-debug walk: turns the SigNoz LLM-span rows returned by
+* `buildCacheDebugQuery` into a chronologically ordered list of `CacheDebugCall`
+* records — each carrying the derived `CacheState`.
+*
+* Per-agent priorSignature tracking (mirrors the per-agent walk in
+* agents-manage-ui/.../[conversationId]/route.ts). A single global cursor
+* cross-contaminates `priorSignature` between sub-agents in multi-agent
+* conversations and reports false MISS-expected / MISS-regression states; the
+* Map<subAgentId, signature> keeps each agent's cursor independent.
+*
+* This is the pure, testable core of the `pnpm cache-debug` CLI. The CLI itself
+* remains a thin shell that fetches from SigNoz and prints these records.
+*/
+function getField(row, key) {
+	const data = row.data;
+	if (data && typeof data === "object" && key in data) return data[key];
+	return row[key];
+}
+function getString(row, key) {
+	const value = getField(row, key);
+	if (typeof value === "string") return value;
+	return value == null ? "" : String(value);
+}
+function getNumber(row, key) {
+	const value = getField(row, key);
+	const n = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(n) ? n : 0;
+}
+function subAgentKey(row) {
+	return getString(row, SPAN_KEYS.AI_TELEMETRY_SUB_AGENT_ID) || getString(row, SPAN_KEYS.AGENT_ID) || "_default";
+}
+/**
+* Walk the LLM-span rows chronologically, deriving each call's cache state with
+* a per-agent prior-signature cursor.
+*
+* The walk:
+*   1. Sorts rows by `SPAN_KEYS.TIMESTAMP` (ascending).
+*   2. For each row, resolves the sub-agent key via fallback chain
+*      `AI_TELEMETRY_SUB_AGENT_ID -> AGENT_ID -> '_default'`.
+*   3. Looks up that agent's prior signature in `priorSignatureByAgent`.
+*   4. Calls `deriveCacheState` and, if the row's `prefix_signature` is non-empty,
+*      updates the agent's cursor.
+*/
+function deriveCacheDebugCalls(rows) {
+	const sorted = [...rows].sort((a, b) => getString(a, SPAN_KEYS.TIMESTAMP).localeCompare(getString(b, SPAN_KEYS.TIMESTAMP)));
+	const calls = [];
+	const priorSignatureByAgent = /* @__PURE__ */ new Map();
+	for (const row of sorted) {
+		const prefixSignature = getString(row, SPAN_KEYS.CACHE_INTENT_PREFIX_SIGNATURE) || null;
+		const cacheReadTokens = getNumber(row, SPAN_KEYS.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS);
+		const markerCount = getNumber(row, SPAN_KEYS.CACHE_INTENT_MARKER_COUNT);
+		const requestProvider = getString(row, SPAN_KEYS.AI_MODEL_PROVIDER);
+		const cachingProvider = resolveCachingProvider({
+			requestProvider,
+			responseProvider: getString(row, SPAN_KEYS.GEN_AI_RESPONSE_PROVIDER)
+		});
+		const subAgentId = subAgentKey(row);
+		const cacheState = deriveCacheState({
+			markerCount,
+			prefixSignature,
+			cacheRead: cacheReadTokens,
+			priorSignature: priorSignatureByAgent.get(subAgentId) ?? null,
+			providerSupportsCaching: cachingProvider ? isProviderSupportedForCaching(cachingProvider) : true
+		});
+		if (prefixSignature) priorSignatureByAgent.set(subAgentId, prefixSignature);
+		calls.push({
+			spanId: getString(row, SPAN_KEYS.SPAN_ID),
+			timestamp: getString(row, SPAN_KEYS.TIMESTAMP),
+			operationId: getString(row, SPAN_KEYS.AI_OPERATION_ID),
+			model: getString(row, SPAN_KEYS.AI_MODEL_ID),
+			modelProvider: requestProvider,
+			generationType: getString(row, SPAN_KEYS.AI_TELEMETRY_GENERATION_TYPE),
+			subAgentId: getString(row, SPAN_KEYS.AI_TELEMETRY_SUB_AGENT_ID),
+			inputTokens: getNumber(row, SPAN_KEYS.GEN_AI_USAGE_INPUT_TOKENS),
+			cacheReadTokens,
+			cacheCreationTokens: getNumber(row, SPAN_KEYS.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS),
+			markerCount,
+			prefixSignature: prefixSignature ?? "",
+			cacheState
+		});
+	}
+	return calls;
+}
+
+//#endregion
+export { deriveCacheDebugCalls };

package/dist/utils/cache-state.d.ts

@@ -0,0 +1,36 @@
+//#region src/utils/cache-state.d.ts
+type CacheState = 'HIT' | 'MISS-regression' | 'MISS-expected' | 'NOT-ATTEMPTED' | 'NOT-SUPPORTED-BY-PROVIDER';
+declare function isProviderSupportedForCaching(provider: string): boolean;
+/**
+ * Resolve the provider to use for the caching-support gate.
+ *
+ * Vercel-AI-Gateway-routed deployments report `ai.model.provider = 'gateway'`,
+ * which is a router, not a caching-capable provider. The actual model provider
+ * that produced the response (and owns the cache keys) lives in
+ * `gen_ai.response.provider`. Prefer that resolved provider when present so the
+ * support gate reflects the real backend (e.g. 'anthropic'); fall back to the
+ * request-side `ai.model.provider` only when the resolved provider is absent.
+ */
+declare function resolveCachingProvider({
+  requestProvider,
+  responseProvider
+}: {
+  requestProvider?: string | null;
+  responseProvider?: string | null;
+}): string;
+interface DeriveCacheStateInput {
+  markerCount: number;
+  prefixSignature: string | null;
+  cacheRead: number;
+  priorSignature?: string | null;
+  providerSupportsCaching?: boolean;
+}
+declare function deriveCacheState({
+  markerCount,
+  prefixSignature,
+  cacheRead,
+  priorSignature,
+  providerSupportsCaching
+}: DeriveCacheStateInput): CacheState;
+//#endregion
+export { CacheState, DeriveCacheStateInput, deriveCacheState, isProviderSupportedForCaching, resolveCachingProvider };

package/dist/utils/cache-state.js

@@ -0,0 +1,33 @@
+//#region src/utils/cache-state.ts
+const CACHING_SUPPORTED_PROVIDERS = new Set([
+	"anthropic",
+	"openai",
+	"google",
+	"gemini"
+]);
+function isProviderSupportedForCaching(provider) {
+	return CACHING_SUPPORTED_PROVIDERS.has(provider.toLowerCase());
+}
+/**
+* Resolve the provider to use for the caching-support gate.
+*
+* Vercel-AI-Gateway-routed deployments report `ai.model.provider = 'gateway'`,
+* which is a router, not a caching-capable provider. The actual model provider
+* that produced the response (and owns the cache keys) lives in
+* `gen_ai.response.provider`. Prefer that resolved provider when present so the
+* support gate reflects the real backend (e.g. 'anthropic'); fall back to the
+* request-side `ai.model.provider` only when the resolved provider is absent.
+*/
+function resolveCachingProvider({ requestProvider, responseProvider }) {
+	return (responseProvider || requestProvider || "").trim();
+}
+function deriveCacheState({ markerCount, prefixSignature, cacheRead, priorSignature = null, providerSupportsCaching = true }) {
+	if (!providerSupportsCaching) return "NOT-SUPPORTED-BY-PROVIDER";
+	if (markerCount <= 0) return "NOT-ATTEMPTED";
+	if (cacheRead > 0) return "HIT";
+	if (priorSignature && prefixSignature && prefixSignature === priorSignature) return "MISS-regression";
+	return "MISS-expected";
+}
+
+//#endregion
+export { deriveCacheState, isProviderSupportedForCaching, resolveCachingProvider };