@inkeep/agents-core 0.74.1 → 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 };

package/dist/utils/index.d.ts

@@ -34,9 +34,9 @@ import "./third-party-mcp-servers/index.js";
 import { AssembleResult, estimateTokens } from "./token-estimator.js";
 import { flushTraces, getTracer, setSpanWithError, unwrapError } from "./tracer-factory.js";
 import { HashedHeaderValue, SignatureVerificationErrorCode, SignatureVerificationResult, TriggerAuthResult, hashAuthenticationHeaders, hashTriggerHeaderValue, validateTriggerHeaderValue, verifySignatureWithConfig, verifyTriggerAuth } from "./trigger-auth.js";
-import { extractUsageTokens, gatewayCostMiddleware, normalizeModelId } from "./usage-cost-middleware.js";
+import { computePrefixSignature, countCacheMarkers, extractUsageTokens, gatewayCostMiddleware, normalizeModelId } from "./usage-cost-middleware.js";
 import "./usage-tracker.js";
 import { ValidatePublicKeyResult, validatePublicKey } from "./validate-public-key.js";
 import { _resetWaitUntilCache, getWaitUntil } from "./wait-until.js";
 import { TRUSTED_WORK_APP_MCP_PATHS, isTrustedWorkAppMcpUrl } from "./work-app-mcp.js";
-export { ApiKeyGenerationResult, AppCredentialResult, AssembleResult, CommonCreateErrorResponses, CommonDeleteErrorResponses, CommonGetErrorResponses, CommonUpdateErrorResponses, ComposioAuthResult, CredentialScope, ERROR_DOCS_BASE_URL, ErrorCode, ErrorCodes, ErrorResponse, GenerateInternalServiceTokenParams, GenerateServiceTokenParams, GenerationType, HashedHeaderValue, InternalServiceId, InternalServiceTokenPayload, InternalServices, JsonTransformer, JwtVerifyResult, LLMMessage, LoggerFactoryConfig, McpClient, McpClientOptions, McpOAuthFlowResult, McpSSEConfig, McpServerConfig, McpStreamableHttpConfig, McpTokenExchangeResult, MockLanguageModel, ModelFactory, OAuthConfig, ParsedSSEResponse, PinoLogger, PinoLoggerConfig, PoWError, PoWResult, ProblemDetails, SKILL_ENTRY_FILE_PATH, ServiceTokenPayload, SignJwtOptions, SignSlackLinkTokenParams, SignSlackUserTokenParams, SignatureVerificationErrorCode, SignatureVerificationResult, SlackAccessTokenPayload, SlackAccessTokenPayloadSchema, SlackLinkIntent, SlackLinkIntentSchema, SlackLinkTokenPayload, SlackLinkTokenPayloadSchema, TRUSTED_WORK_APP_MCP_PATHS, TempTokenPayload, TriggerAuthResult, ValidatePublicKeyResult, VerifyInternalServiceTokenResult, VerifyJwtOptions, VerifyServiceTokenResult, VerifySlackLinkTokenResult, VerifySlackUserTokenResult, _resetWaitUntilCache, activeMcpClients, buildConversationMetadata, buildConversationUserProperties, commonCreateErrorResponses, commonDeleteErrorResponses, commonGetErrorResponses, commonUpdateErrorResponses, computeNextRunAt, configureComposioMCPServer, convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, createApiError, createMockModel, decodeJwtPayload, deleteComposioConnectedAccount, deriveKidFromPublicKey, deriveRelationId, detectAuthenticationRequired, errorResponseSchema, errorSchemaFactory, estimateTokens, exchangeMcpAuthorizationCode, extractBearerToken, extractComposioServerId, extractPreviewFields, extractPublicId, extractUsageTokens, fetchComposioServers, fetchSingleComposioServer, flushTraces, formatMessagesForLLM, formatMessagesForLLMContext, gatewayCostMiddleware, generateApiKey, generateAppCredential, generateId, generateInternalServiceToken, generateServiceToken, getComposioInstance, getComposioOAuthRedirectUrl, getComposioUserId, getConversationId, getConversationProperties, getConversationUserProperties, getCredentialStoreLookupKeyFromRetrievalParams, getDatabaseErrorLogContext, getInProcessFetch, getJwtSecret, getLogger, getMessageUserProperties, getMetadataFromApiKey, getPoWErrorMessage, getTracer, getWaitUntil, handleApiError, hasIssuer, hashApiKey, hashAuthenticationHeaders, hashTriggerHeaderValue, initiateMcpOAuthFlow, interpolateTemplate, isApiKeyExpired, isComposioMCPServerAuthenticated, isDevelopment, isInternalServiceToken, isPoWEnabled, isProduction, isSlackUserToken, isTest, isThirdPartyMCPServerAuthenticated, isTrustedWorkAppMcpUrl, isUniqueConstraintError, isZodSchema, loggerFactory, makeAllPropertiesRequired, maskApiKey, normalizeDataComponentSchema, normalizeDateString, normalizeModelId, parseEmbeddedJson, parseSSEResponse, parseSkillFromMarkdown, preview, problemDetailsSchema, registerAppFetch, retryWithBackoff, runWithLogContext, sanitizeAppConfig, serializeSkillToMarkdown, setSpanWithError, signJwt, signSlackLinkToken, signSlackUserToken, stripUnsupportedConstraints, throwIfUniqueConstraintError, toISODateString, unwrapError, validateApiKey, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, validateOrigin, validatePublicKey, validateTargetAgent, validateTenantId, validateTriggerHeaderValue, verifyAuthorizationHeader, verifyInternalServiceAuthHeader, verifyInternalServiceToken, verifyJwt, verifyPoW, verifyServiceToken, verifySignatureWithConfig, verifySlackLinkToken, verifySlackUserToken, verifyTempToken, verifyTriggerAuth };
+export { ApiKeyGenerationResult, AppCredentialResult, AssembleResult, CommonCreateErrorResponses, CommonDeleteErrorResponses, CommonGetErrorResponses, CommonUpdateErrorResponses, ComposioAuthResult, CredentialScope, ERROR_DOCS_BASE_URL, ErrorCode, ErrorCodes, ErrorResponse, GenerateInternalServiceTokenParams, GenerateServiceTokenParams, GenerationType, HashedHeaderValue, InternalServiceId, InternalServiceTokenPayload, InternalServices, JsonTransformer, JwtVerifyResult, LLMMessage, LoggerFactoryConfig, McpClient, McpClientOptions, McpOAuthFlowResult, McpSSEConfig, McpServerConfig, McpStreamableHttpConfig, McpTokenExchangeResult, MockLanguageModel, ModelFactory, OAuthConfig, ParsedSSEResponse, PinoLogger, PinoLoggerConfig, PoWError, PoWResult, ProblemDetails, SKILL_ENTRY_FILE_PATH, ServiceTokenPayload, SignJwtOptions, SignSlackLinkTokenParams, SignSlackUserTokenParams, SignatureVerificationErrorCode, SignatureVerificationResult, SlackAccessTokenPayload, SlackAccessTokenPayloadSchema, SlackLinkIntent, SlackLinkIntentSchema, SlackLinkTokenPayload, SlackLinkTokenPayloadSchema, TRUSTED_WORK_APP_MCP_PATHS, TempTokenPayload, TriggerAuthResult, ValidatePublicKeyResult, VerifyInternalServiceTokenResult, VerifyJwtOptions, VerifyServiceTokenResult, VerifySlackLinkTokenResult, VerifySlackUserTokenResult, _resetWaitUntilCache, activeMcpClients, buildConversationMetadata, buildConversationUserProperties, commonCreateErrorResponses, commonDeleteErrorResponses, commonGetErrorResponses, commonUpdateErrorResponses, computeNextRunAt, computePrefixSignature, configureComposioMCPServer, convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, countCacheMarkers, createApiError, createMockModel, decodeJwtPayload, deleteComposioConnectedAccount, deriveKidFromPublicKey, deriveRelationId, detectAuthenticationRequired, errorResponseSchema, errorSchemaFactory, estimateTokens, exchangeMcpAuthorizationCode, extractBearerToken, extractComposioServerId, extractPreviewFields, extractPublicId, extractUsageTokens, fetchComposioServers, fetchSingleComposioServer, flushTraces, formatMessagesForLLM, formatMessagesForLLMContext, gatewayCostMiddleware, generateApiKey, generateAppCredential, generateId, generateInternalServiceToken, generateServiceToken, getComposioInstance, getComposioOAuthRedirectUrl, getComposioUserId, getConversationId, getConversationProperties, getConversationUserProperties, getCredentialStoreLookupKeyFromRetrievalParams, getDatabaseErrorLogContext, getInProcessFetch, getJwtSecret, getLogger, getMessageUserProperties, getMetadataFromApiKey, getPoWErrorMessage, getTracer, getWaitUntil, handleApiError, hasIssuer, hashApiKey, hashAuthenticationHeaders, hashTriggerHeaderValue, initiateMcpOAuthFlow, interpolateTemplate, isApiKeyExpired, isComposioMCPServerAuthenticated, isDevelopment, isInternalServiceToken, isPoWEnabled, isProduction, isSlackUserToken, isTest, isThirdPartyMCPServerAuthenticated, isTrustedWorkAppMcpUrl, isUniqueConstraintError, isZodSchema, loggerFactory, makeAllPropertiesRequired, maskApiKey, normalizeDataComponentSchema, normalizeDateString, normalizeModelId, parseEmbeddedJson, parseSSEResponse, parseSkillFromMarkdown, preview, problemDetailsSchema, registerAppFetch, retryWithBackoff, runWithLogContext, sanitizeAppConfig, serializeSkillToMarkdown, setSpanWithError, signJwt, signSlackLinkToken, signSlackUserToken, stripUnsupportedConstraints, throwIfUniqueConstraintError, toISODateString, unwrapError, validateApiKey, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, validateOrigin, validatePublicKey, validateTargetAgent, validateTenantId, validateTriggerHeaderValue, verifyAuthorizationHeader, verifyInternalServiceAuthHeader, verifyInternalServiceToken, verifyJwt, verifyPoW, verifyServiceToken, verifySignatureWithConfig, verifySlackLinkToken, verifySlackUserToken, verifyTempToken, verifyTriggerAuth };

package/dist/utils/index.js

@@ -21,7 +21,7 @@ import { JsonTransformer } from "./JsonTransformer.js";
 import { parseEmbeddedJson } from "./json-parser.js";
 import { McpClient, activeMcpClients } from "./mcp-client.js";
 import { MockLanguageModel, createMockModel } from "./mock-provider.js";
-import { extractUsageTokens, gatewayCostMiddleware, normalizeModelId } from "./usage-cost-middleware.js";
+import { computePrefixSignature, countCacheMarkers, extractUsageTokens, gatewayCostMiddleware, normalizeModelId } from "./usage-cost-middleware.js";
 import { ModelFactory } from "./model-factory.js";
 import { getPoWErrorMessage, isPoWEnabled, verifyPoW } from "./pow.js";
 import { retryWithBackoff } from "./retry.js";
@@ -38,4 +38,4 @@ import { validatePublicKey } from "./validate-public-key.js";
 import { _resetWaitUntilCache, getWaitUntil } from "./wait-until.js";
 import { TRUSTED_WORK_APP_MCP_PATHS, isTrustedWorkAppMcpUrl } from "./work-app-mcp.js";
 
-export { ERROR_DOCS_BASE_URL, ErrorCode, InternalServices, JsonTransformer, McpClient, MockLanguageModel, ModelFactory, PinoLogger, SKILL_ENTRY_FILE_PATH, SlackAccessTokenPayloadSchema, SlackLinkIntentSchema, SlackLinkTokenPayloadSchema, TRUSTED_WORK_APP_MCP_PATHS, _resetWaitUntilCache, activeMcpClients, buildConversationMetadata, buildConversationUserProperties, commonCreateErrorResponses, commonDeleteErrorResponses, commonGetErrorResponses, commonUpdateErrorResponses, computeNextRunAt, configureComposioMCPServer, convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, createApiError, createMockModel, decodeJwtPayload, deleteComposioConnectedAccount, deriveKidFromPublicKey, deriveRelationId, detectAuthenticationRequired, errorResponseSchema, errorSchemaFactory, estimateTokens, exchangeMcpAuthorizationCode, extractBearerToken, extractComposioServerId, extractPreviewFields, extractPublicId, extractUsageTokens, fetchComposioServers, fetchSingleComposioServer, flushTraces, formatMessagesForLLM, formatMessagesForLLMContext, gatewayCostMiddleware, generateApiKey, generateAppCredential, generateId, generateInternalServiceToken, generateServiceToken, getComposioInstance, getComposioOAuthRedirectUrl, getComposioUserId, getConversationId, getConversationProperties, getConversationUserProperties, getCredentialStoreLookupKeyFromRetrievalParams, getDatabaseErrorLogContext, getInProcessFetch, getJwtSecret, getLogger, getMessageUserProperties, getMetadataFromApiKey, getPoWErrorMessage, getTracer, getWaitUntil, handleApiError, hasIssuer, hashApiKey, hashAuthenticationHeaders, hashTriggerHeaderValue, initiateMcpOAuthFlow, interpolateTemplate, isApiKeyExpired, isComposioMCPServerAuthenticated, isDevelopment, isInternalServiceToken, isPoWEnabled, isProduction, isSlackUserToken, isTest, isThirdPartyMCPServerAuthenticated, isTrustedWorkAppMcpUrl, isUniqueConstraintError, isZodSchema, loggerFactory, makeAllPropertiesRequired, maskApiKey, normalizeDataComponentSchema, normalizeDateString, normalizeModelId, parseEmbeddedJson, parseSSEResponse, parseSkillFromMarkdown, preview, problemDetailsSchema, registerAppFetch, retryWithBackoff, runWithLogContext, sanitizeAppConfig, serializeSkillToMarkdown, setSpanWithError, signJwt, signSlackLinkToken, signSlackUserToken, stripUnsupportedConstraints, throwIfUniqueConstraintError, toISODateString, unwrapError, validateApiKey, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, validateOrigin, validatePublicKey, validateTargetAgent, validateTenantId, validateTriggerHeaderValue, verifyAuthorizationHeader, verifyInternalServiceAuthHeader, verifyInternalServiceToken, verifyJwt, verifyPoW, verifyServiceToken, verifySignatureWithConfig, verifySlackLinkToken, verifySlackUserToken, verifyTempToken, verifyTriggerAuth };
+export { ERROR_DOCS_BASE_URL, ErrorCode, InternalServices, JsonTransformer, McpClient, MockLanguageModel, ModelFactory, PinoLogger, SKILL_ENTRY_FILE_PATH, SlackAccessTokenPayloadSchema, SlackLinkIntentSchema, SlackLinkTokenPayloadSchema, TRUSTED_WORK_APP_MCP_PATHS, _resetWaitUntilCache, activeMcpClients, buildConversationMetadata, buildConversationUserProperties, commonCreateErrorResponses, commonDeleteErrorResponses, commonGetErrorResponses, commonUpdateErrorResponses, computeNextRunAt, computePrefixSignature, configureComposioMCPServer, convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, countCacheMarkers, createApiError, createMockModel, decodeJwtPayload, deleteComposioConnectedAccount, deriveKidFromPublicKey, deriveRelationId, detectAuthenticationRequired, errorResponseSchema, errorSchemaFactory, estimateTokens, exchangeMcpAuthorizationCode, extractBearerToken, extractComposioServerId, extractPreviewFields, extractPublicId, extractUsageTokens, fetchComposioServers, fetchSingleComposioServer, flushTraces, formatMessagesForLLM, formatMessagesForLLMContext, gatewayCostMiddleware, generateApiKey, generateAppCredential, generateId, generateInternalServiceToken, generateServiceToken, getComposioInstance, getComposioOAuthRedirectUrl, getComposioUserId, getConversationId, getConversationProperties, getConversationUserProperties, getCredentialStoreLookupKeyFromRetrievalParams, getDatabaseErrorLogContext, getInProcessFetch, getJwtSecret, getLogger, getMessageUserProperties, getMetadataFromApiKey, getPoWErrorMessage, getTracer, getWaitUntil, handleApiError, hasIssuer, hashApiKey, hashAuthenticationHeaders, hashTriggerHeaderValue, initiateMcpOAuthFlow, interpolateTemplate, isApiKeyExpired, isComposioMCPServerAuthenticated, isDevelopment, isInternalServiceToken, isPoWEnabled, isProduction, isSlackUserToken, isTest, isThirdPartyMCPServerAuthenticated, isTrustedWorkAppMcpUrl, isUniqueConstraintError, isZodSchema, loggerFactory, makeAllPropertiesRequired, maskApiKey, normalizeDataComponentSchema, normalizeDateString, normalizeModelId, parseEmbeddedJson, parseSSEResponse, parseSkillFromMarkdown, preview, problemDetailsSchema, registerAppFetch, retryWithBackoff, runWithLogContext, sanitizeAppConfig, serializeSkillToMarkdown, setSpanWithError, signJwt, signSlackLinkToken, signSlackUserToken, stripUnsupportedConstraints, throwIfUniqueConstraintError, toISODateString, unwrapError, validateApiKey, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, validateOrigin, validatePublicKey, validateTargetAgent, validateTenantId, validateTriggerHeaderValue, verifyAuthorizationHeader, verifyInternalServiceAuthHeader, verifyInternalServiceToken, verifyJwt, verifyPoW, verifyServiceToken, verifySignatureWithConfig, verifySlackLinkToken, verifySlackUserToken, verifyTempToken, verifyTriggerAuth };

package/dist/utils/model-factory.d.ts

@@ -25,6 +25,13 @@ declare class ModelFactory {
    * a provider-specific per-call option, e.g. anthropic.thinking, gateway.models.
    */
   static extractStreamProviderOptions(providerOptions?: Record<string, unknown>): Record<string, JSONObject> | undefined;
+  /**
+   * Whether the given model settings will route through the Vercel AI Gateway
+   * vs. instantiating a direct provider client. Mirrors the gate used inside
+   * createModel so callers (e.g. the prompt-caching actuator) can detect mode
+   * without recreating the model instance.
+   */
+  static shouldRouteViaGateway(modelSettings: ModelSettings): boolean;
   /**
    * Create a language model instance from configuration
    * Throws error if no config provided - models must be configured at project level

package/dist/utils/model-factory.js

@@ -94,6 +94,19 @@ var ModelFactory = class ModelFactory {
 		return Object.keys(result).length > 0 ? result : void 0;
 	}
 	/**
+	* Whether the given model settings will route through the Vercel AI Gateway
+	* vs. instantiating a direct provider client. Mirrors the gate used inside
+	* createModel so callers (e.g. the prompt-caching actuator) can detect mode
+	* without recreating the model instance.
+	*/
+	static shouldRouteViaGateway(modelSettings) {
+		const modelString = modelSettings.model?.trim();
+		if (!modelString) return false;
+		const { provider } = ModelFactory.parseModelString(modelString);
+		const providerConfig = ModelFactory.extractProviderConfig(modelSettings.providerOptions);
+		return !!process.env.AI_GATEWAY_API_KEY && GATEWAY_ROUTABLE_PROVIDERS_SET.has(provider) && Object.keys(providerConfig).length === 0;
+	}
+	/**
 	* Create a language model instance from configuration
 	* Throws error if no config provided - models must be configured at project level
 	*/
@@ -110,9 +123,12 @@ var ModelFactory = class ModelFactory {
 			hasProviderOptions: !!modelSettings.providerOptions
 		}, "Creating language model from config");
 		const providerConfig = ModelFactory.extractProviderConfig(modelSettings.providerOptions);
-		const shouldRouteViaGateway = !!process.env.AI_GATEWAY_API_KEY && GATEWAY_ROUTABLE_PROVIDERS_SET.has(provider) && Object.keys(providerConfig).length === 0;
+		const routeViaGateway = ModelFactory.shouldRouteViaGateway({
+			model: modelSettings.model,
+			providerOptions: modelSettings.providerOptions
+		});
 		let model;
-		if (shouldRouteViaGateway) model = gateway(!!modelSettings.allowedProviders?.length ? modelName : `${provider}/${modelName}`);
+		if (routeViaGateway) model = gateway(!!modelSettings.allowedProviders?.length ? modelName : `${provider}/${modelName}`);
 		else if (provider !== "mock" && (provider === "azure" || Object.keys(providerConfig).length > 0)) {
 			logger.info({ config: providerConfig }, `Applying custom ${provider} provider configuration`);
 			model = ModelFactory.createProvider(provider, providerConfig).languageModel(modelName);

package/dist/utils/token-estimator.d.ts

@@ -14,6 +14,7 @@ declare function estimateTokens(text: string | undefined | null): number;
 interface AssembleResult {
   prompt: string;
   breakdown: ContextBreakdown;
+  artifactsMessage: string | null;
 }
 //#endregion
 export { AssembleResult, estimateTokens };

package/dist/utils/usage-cost-middleware.d.ts

@@ -9,6 +9,8 @@ declare function extractUsageTokens(usage: any): {
   cachedWriteTokens?: number;
 };
 declare function normalizeModelId(modelId: string): string;
+declare function countCacheMarkers(prompt: readonly any[], callProviderOptions?: Record<string, any>): number;
+declare function computePrefixSignature(prompt: readonly any[], tools?: readonly any[]): string;
 declare const gatewayCostMiddleware: LanguageModelMiddleware;
 //#endregion
-export { extractUsageTokens, gatewayCostMiddleware, normalizeModelId };
+export { computePrefixSignature, countCacheMarkers, extractUsageTokens, gatewayCostMiddleware, normalizeModelId };

package/dist/utils/usage-cost-middleware.js

@@ -1,17 +1,27 @@
 import { SPAN_KEYS } from "../constants/otel-attributes.js";
 import { GATEWAY_ROUTABLE_PROVIDERS_SET } from "../constants/models.js";
 import { getLogger } from "./logger.js";
+import { createHash } from "node:crypto";
 import { trace } from "@opentelemetry/api";
 
 //#region src/utils/usage-cost-middleware.ts
 const logger = getLogger("usage-cost-middleware");
 function extractUsageTokens(usage) {
+	const inputTokens = typeof usage?.inputTokens === "object" ? usage.inputTokens.total ?? 0 : usage?.inputTokens ?? 0;
+	const outputTokens = typeof usage?.outputTokens === "object" ? usage.outputTokens.total ?? 0 : usage?.outputTokens ?? 0;
+	const reasoningTokens = typeof usage?.outputTokens === "object" ? usage.outputTokens.reasoning : void 0;
+	let cachedReadTokens = typeof usage?.inputTokens === "object" ? usage.inputTokens.cacheRead : void 0;
+	const cachedWriteTokens = typeof usage?.inputTokens === "object" ? usage.inputTokens.cacheWrite : void 0;
+	if (cachedReadTokens === void 0) {
+		const geminiCacheRead = usage?.inputTokenDetails?.cacheReadTokens ?? usage?.cachedInputTokens;
+		if (typeof geminiCacheRead === "number") cachedReadTokens = geminiCacheRead;
+	}
 	return {
-		inputTokens: typeof usage?.inputTokens === "object" ? usage.inputTokens.total ?? 0 : usage?.inputTokens ?? 0,
-		outputTokens: typeof usage?.outputTokens === "object" ? usage.outputTokens.total ?? 0 : usage?.outputTokens ?? 0,
-		reasoningTokens: typeof usage?.outputTokens === "object" ? usage.outputTokens.reasoning : void 0,
-		cachedReadTokens: typeof usage?.inputTokens === "object" ? usage.inputTokens.cacheRead : void 0,
-		cachedWriteTokens: typeof usage?.inputTokens === "object" ? usage.inputTokens.cacheWrite : void 0
+		inputTokens,
+		outputTokens,
+		reasoningTokens,
+		cachedReadTokens,
+		cachedWriteTokens
 	};
 }
 function extractGatewayCost(providerMetadata) {
@@ -43,29 +53,77 @@ function setGatewayAttributesOnSpan(providerMetadata) {
 		if (routing?.resolvedProvider) activeSpan.setAttribute(SPAN_KEYS.GEN_AI_REQUEST_PROVIDER, routing.resolvedProvider);
 	}
 }
+function countCacheMarkers(prompt, callProviderOptions) {
+	let count = 0;
+	const caching = callProviderOptions?.gateway?.caching;
+	if (caching && caching !== "off" && caching !== "disabled") count++;
+	for (const msg of prompt) if (msg.providerOptions?.anthropic?.cacheControl) count++;
+	return Math.min(count, 4);
+}
+function computePrefixSignature(prompt, tools) {
+	const systemParts = [];
+	for (const msg of prompt) {
+		if (msg.role !== "system") continue;
+		if (typeof msg.content === "string") systemParts.push(msg.content);
+		else if (Array.isArray(msg.content)) {
+			for (const part of msg.content) if (typeof part === "string") systemParts.push(part);
+			else if (part?.text) systemParts.push(part.text);
+		}
+	}
+	const toolParts = (tools ?? []).map((tool) => [
+		tool.name ?? "",
+		tool.description ?? "",
+		tool.parameters ? JSON.stringify(tool.parameters) : ""
+	]);
+	return createHash("sha256").update(JSON.stringify([systemParts, toolParts])).digest("hex").slice(0, 10);
+}
+function setCacheAttributesOnSpan(params, usage) {
+	const activeSpan = trace.getActiveSpan();
+	if (!activeSpan) return;
+	const { cachedReadTokens, cachedWriteTokens } = extractUsageTokens(usage);
+	activeSpan.setAttribute(SPAN_KEYS.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, typeof cachedReadTokens === "number" ? cachedReadTokens : 0);
+	activeSpan.setAttribute(SPAN_KEYS.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS, typeof cachedWriteTokens === "number" ? cachedWriteTokens : 0);
+	const prompt = params.prompt ?? [];
+	const markerCount = countCacheMarkers(prompt, params.providerOptions);
+	activeSpan.setAttribute(SPAN_KEYS.CACHE_INTENT_MARKER_COUNT, markerCount);
+	const prefixSignature = computePrefixSignature(prompt, params.tools);
+	activeSpan.setAttribute(SPAN_KEYS.CACHE_INTENT_PREFIX_SIGNATURE, prefixSignature);
+}
 const gatewayCostMiddleware = {
 	specificationVersion: "v3",
 	overrideModelId({ model }) {
 		return normalizeModelId(model.modelId);
 	},
-	async wrapGenerate({ doGenerate }) {
+	async wrapGenerate({ doGenerate, params }) {
 		const result = await doGenerate();
 		try {
 			setGatewayAttributesOnSpan(result.providerMetadata);
 		} catch (error) {
 			logger.warn({ error }, "Failed to extract gateway cost in wrapGenerate");
 		}
+		try {
+			setCacheAttributesOnSpan(params, result.usage);
+		} catch (error) {
+			logger.warn({ error }, "Failed to set cache attributes in wrapGenerate");
+		}
 		return result;
 	},
-	async wrapStream({ doStream }) {
+	async wrapStream({ doStream, params }) {
 		const { stream, ...rest } = await doStream();
 		return {
 			stream: stream.pipeThrough(new TransformStream({ transform(chunk, controller) {
 				controller.enqueue(chunk);
-				if (chunk.type === "finish") try {
-					setGatewayAttributesOnSpan(chunk.providerMetadata);
-				} catch (error) {
-					logger.warn({ error }, "Failed to extract gateway cost in wrapStream");
+				if (chunk.type === "finish") {
+					try {
+						setGatewayAttributesOnSpan(chunk.providerMetadata);
+					} catch (error) {
+						logger.warn({ error }, "Failed to extract gateway cost in wrapStream");
+					}
+					try {
+						setCacheAttributesOnSpan(params, chunk.usage);
+					} catch (error) {
+						logger.warn({ error }, "Failed to set cache attributes in wrapStream");
+					}
 				}
 			} })),
 			...rest
@@ -74,4 +132,4 @@ const gatewayCostMiddleware = {
 };
 
 //#endregion
-export { extractUsageTokens, gatewayCostMiddleware, normalizeModelId };
+export { computePrefixSignature, countCacheMarkers, extractUsageTokens, gatewayCostMiddleware, normalizeModelId };

package/dist/validation/drizzle-schema-helpers.d.ts

@@ -1,10 +1,10 @@
 import { z } from "@hono/zod-openapi";
-import * as drizzle_zod403 from "drizzle-zod";
+import * as drizzle_zod15 from "drizzle-zod";
 import { AnySQLiteTable } from "drizzle-orm/sqlite-core";
 
 //#region src/validation/drizzle-schema-helpers.d.ts
-declare function createSelectSchemaWithModifiers<T extends AnySQLiteTable>(table: T, overrides?: Partial<Record<keyof T['_']['columns'], (schema: z.ZodTypeAny) => z.ZodTypeAny>>): drizzle_zod403.BuildSchema<"select", T["_"]["columns"], drizzle_zod403.BuildRefine<T["_"]["columns"], undefined>, undefined>;
-declare function createInsertSchemaWithModifiers<T extends AnySQLiteTable>(table: T, overrides?: Partial<Record<keyof T['_']['columns'], (schema: z.ZodTypeAny) => z.ZodTypeAny>>): drizzle_zod403.BuildSchema<"insert", T["_"]["columns"], drizzle_zod403.BuildRefine<Pick<T["_"]["columns"], keyof T["$inferInsert"]>, undefined>, undefined>;
+declare function createSelectSchemaWithModifiers<T extends AnySQLiteTable>(table: T, overrides?: Partial<Record<keyof T['_']['columns'], (schema: z.ZodTypeAny) => z.ZodTypeAny>>): drizzle_zod15.BuildSchema<"select", T["_"]["columns"], drizzle_zod15.BuildRefine<T["_"]["columns"], undefined>, undefined>;
+declare function createInsertSchemaWithModifiers<T extends AnySQLiteTable>(table: T, overrides?: Partial<Record<keyof T['_']['columns'], (schema: z.ZodTypeAny) => z.ZodTypeAny>>): drizzle_zod15.BuildSchema<"insert", T["_"]["columns"], drizzle_zod15.BuildRefine<Pick<T["_"]["columns"], keyof T["$inferInsert"]>, undefined>, undefined>;
 declare const createSelectSchema: typeof createSelectSchemaWithModifiers;
 declare const createInsertSchema: typeof createInsertSchemaWithModifiers;
 /**