@anuma/sdk 6.7.2 → 6.8.0

package/dist/expo/index.d.mts

@@ -4862,6 +4862,44 @@ interface EntityOperationsContext {
     allowUnscopedRows?: boolean;
 }
 
+/**
+ * Shared portal LLM call for the memory pipeline.
+ *
+ * The three LLM-driven steps (`extractFacts`, `consolidateMemory`,
+ * `decomposeQuery`) share the same shape: POST to `/api/v1/chat/completions`
+ * with a system+user prompt and `response_format: json_object`, parse
+ * `choices[0].message.content` as JSON, validate, return null on any failure.
+ * This helper owns the fetch+timeout+parse+log boilerplate so each caller
+ * stays focused on its prompt and validator.
+ *
+ * PROMPT CACHING. The portal inserts explicit prompt-cache breakpoints only for
+ * `anthropic/` models. Its request schema does carry OpenAI's
+ * `prompt_cache_key`, but that is a routing hint for OpenAI's own implicit
+ * cache rather than a switch that enables caching, and we deliberately don't
+ * send it: the memory pipeline runs open-weights models by default (gpt-oss for
+ * extraction/topics, ling for consolidation), and this module already has one
+ * hard lesson about OpenAI-standard fields a non-OpenAI provider hard-400s on
+ * (`response_format`, below). Revisit only with a verified per-provider gate.
+ *
+ * So on the models this pipeline actually uses, the only cache that can hit is
+ * the provider's own implicit prefix cache — which makes prefix stability the
+ * one lever a caller controls. Messages are assembled system-first (below), so
+ * every caller must pass a CONSTANT `systemPrompt` and keep all per-call
+ * material in `userMessage`: a single interpolated timestamp, id, or count in a
+ * system prompt shifts every byte after it and misses the cache on every
+ * request thereafter. The memory callers are regression-gated on that property
+ * in `promptPrefixStability.test.ts`.
+ *
+ * Whether those implicit caches hit is observable: each successful response
+ * logs the portal's reported token counts at debug level, including
+ * `portal.cached_tokens` (the prompt tokens the provider served from cache —
+ * the portal omits the field when there was no hit). See {@link logPortalUsage}.
+ *
+ * There is no batch/async-bulk route on the portal, so a backfill or reindex
+ * has no discounted-throughput path either; its only levers are the same stable
+ * prefix and caller-side batching (e.g. topicExtract's 10-memories-per-call).
+ */
+
 /**
  * Auth for portal LLM calls (extraction, consolidation, decomposition,
  * reflection). Mirrors `memoryEngine`'s `EmbeddingOptions` dual-auth:
@@ -4880,6 +4918,60 @@ interface PortalLlmAuth {
     /** Function to get an auth token (e.g., Privy's getIdentityToken). Token is sent as `Authorization: Bearer`. */
     getToken?: () => Promise<string | null>;
 }
+/**
+ * Why a portal JSON completion gave up, as a STABLE low-cardinality code.
+ *
+ * The retry loop has always classified its failures precisely, but only as an
+ * interpolated `reason` string for `log.warn` — and prod ships no SDK log
+ * (sdk#883), so in production every one of these collapsed into a single
+ * `empty-after-retry` with no way to tell them apart. That is what made the
+ * 2026-08-11 audit need a Prometheus cross-check to discover that the portal
+ * was returning HTTP 200 with an empty body on ~60% of extraction turns.
+ *
+ * Codes are deliberately an enum, not the `reason` string: the strings embed
+ * status codes and error messages, so they are unbounded and useless as an
+ * analytics property. Keep this list SHORT and stable — it is a telemetry
+ * contract, and a value added here has to mean the same thing in six months.
+ *
+ * @public
+ */
+type PortalLlmFailureReason = 
+/** No usable credential — `getToken` returned null or threw. Terminal. */
+"auth-unavailable"
+/** Non-retryable HTTP status (400/403/404, or 401 on the static-apiKey path). */
+ | "http-terminal"
+/** Retryable status (408/409/425/429/5xx) that never succeeded. */
+ | "http-retryable"
+/** Network error or the per-attempt timeout aborted the fetch. */
+ | "network"
+/** HTTP 200 but the envelope itself wasn't JSON. */
+ | "body-parse-failed"
+/**
+ * HTTP 200 with NO completion content. The reasoning-class failure mode:
+ * the model spends its budget on unreturned thinking and answers empty.
+ */
+ | "empty-content"
+/** Content present, but no parseable JSON in it (prose, a clarifying question). */
+ | "invalid-json"
+/** Content parsed to a literal `null`, which is never a valid response. */
+ | "null-completion"
+/** `totalTimeoutMs` was spent before the next attempt could run. */
+ | "time-budget-exhausted";
+/**
+ * A give-up report: the classified {@link PortalLlmFailureReason} plus the
+ * little context worth carrying into telemetry. Both extra fields are bounded
+ * (a status code, a small attempt count), so both are safe as event properties.
+ *
+ * @public
+ */
+interface PortalLlmFailure {
+    /** Stable code for the last failure observed. */
+    reason: PortalLlmFailureReason;
+    /** HTTP status, when the failure was an HTTP one. */
+    httpStatus?: number;
+    /** How many attempts ran before giving up (1-based, ≥ 1). */
+    attempts: number;
+}
 
 /**
  * Optional LLM injection classifier — Tier-0 security second layer (PR5).
@@ -5984,8 +6076,14 @@ interface ExtractFactsOptions extends PortalLlmAuth {
      * `{candidates: []}` "nothing durable here". Lets callers distinguish a
      * silently-degrading extractor from quiet turns (the two are otherwise
      * indistinguishable). See {@link extractAndRetain}'s `outcome`.
+     *
+     * Receives the classified {@link PortalLlmFailure}. Knowing THAT extraction
+     * failed was not enough: the 2026-08-11 audit found ~60% of production turns
+     * ending here and had to cross-check Prometheus to learn that the cause was
+     * HTTP-200-with-empty-body rather than the 403 everyone assumed. Forward
+     * `failure.reason` into analytics so the next such question is a query.
      */
-    onExhaustedEmpty?: () => void;
+    onExhaustedEmpty?: (failure: PortalLlmFailure) => void;
     /**
      * Called when the extractor DID produce candidates but PII de-anonymization
      * dropped every one of them — the model mangled its placeholders (so they
@@ -6108,6 +6206,11 @@ declare function extractAndRetain(messages: AutoExtractMessage[], retainCtx: Ret
      * "extracted but held for review".
      */
     quarantined: QuarantinedMemoryInfo[];
+    /**
+     * Present only when `outcome` is `empty-after-retry` — the classified cause of
+     * the give-up, so "extraction is failing" can be reported as *why* it failed.
+     */
+    failure?: PortalLlmFailure;
 }>;
 
 /**
@@ -10232,4 +10335,4 @@ declare function refreshNotionAccessToken(params: NotionRefreshTokenParams): Pro
  */
 declare function createNotionTools(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig[];
 
-export { type AutoExtractMessage, type AutoExtractor, type Budget, CHUNKS_DISCARDED_ORIGIN, type CachedChunkVectors, type CachedServerTools, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ChunkVectorCache, type ChunkingOptions, type ConsolidationFallbackReason, type ConversationMemoryInput, ConversationMemory as ConversationMemoryModel, type ConversationMemoryOperationsContext, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateDecaySweeperOptions, type CreateMessageOptions, type CreateVaultFolderOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_DECAY_POLICY, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetConversationsPageOptions, type GetMessagesPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type Logger, LoggerProvider, type LoggerProviderProps, MAX_HOPS, MEDIUM_TTL_MS, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, type MessageRedactionResult, type MessageSkeleton, NEVER_TTL_MS, NODE_BUDGET, NOTION_OAUTH_CONFIG, type NeighborRefiner, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, type NowSource, type ObservationTrend, type ObservationTrendInput, PAST_EVENT_GRACE_MS, PII_PATTERNS, PROFILE_DOC_VERSION, type PhotoIngestResult, type PhotoMediaRef, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type PromptPreProcessor, type PromptPreProcessorContext, type PublishedPhotoMemory, type QuantizedEmbedding, type QuarantinedMemoryInfo, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankableVaultMemory, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, SHORT_TTL_MS, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageDetachedResult, type SendMessageWithStorageResult, type ServerToolsOptions, type ServerToolsResponse, type SignMessageFn, type StockPriceClassification, type StockPricePreProcessorOptions, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredConversationMemory, type StoredMessage, type StoredMessageWithSimilarity, type StoredVaultFolder, VaultFolder as StoredVaultFolderModel, type StoredVaultMemory, VaultMemory as StoredVaultMemoryModel, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, type SynthesizeProfileOptions, TOOL_RESULT_ORIGIN, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildNotionAuthUrl, capHopsForDensity, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageSourceResolver, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decodeChunkVector, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, encodeChunkVector, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getConversationsPageOp, getDecayCandidatesRawOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoriesByIdsOp, getVaultMemoryOp, getVaultRankingProjectionsOp, hardDeleteDecayedOp, hasEncryptionKey, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isPiiRedactor, isRerankerAvailable, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, parseMedia, preEmbedVaultMemories, quantizeEmbedding, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, refreshNotionAccessToken, registerNotionClient, relinkMemoryTopicsOp, requestEncryptionKey, resolvePiiRedactor, restoreVaultMemoryOp, resumeStream, retain, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, seedEncryptionKeys, setLogger, setMemoryVisibilityOp, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, supersedeVaultMemoryOp, synthesizeProfile, traverseGraphLane, ttlForType, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, verifyMemoriesForPublish, xhrTransport };
+export { type AutoExtractMessage, type AutoExtractor, type Budget, CHUNKS_DISCARDED_ORIGIN, type CachedChunkVectors, type CachedServerTools, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ChunkVectorCache, type ChunkingOptions, type ConsolidationFallbackReason, type ConversationMemoryInput, ConversationMemory as ConversationMemoryModel, type ConversationMemoryOperationsContext, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateDecaySweeperOptions, type CreateMessageOptions, type CreateVaultFolderOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_DECAY_POLICY, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetConversationsPageOptions, type GetMessagesPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type Logger, LoggerProvider, type LoggerProviderProps, MAX_HOPS, MEDIUM_TTL_MS, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, type MessageRedactionResult, type MessageSkeleton, NEVER_TTL_MS, NODE_BUDGET, NOTION_OAUTH_CONFIG, type NeighborRefiner, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, type NowSource, type ObservationTrend, type ObservationTrendInput, PAST_EVENT_GRACE_MS, PII_PATTERNS, PROFILE_DOC_VERSION, type PhotoIngestResult, type PhotoMediaRef, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type PromptPreProcessor, type PromptPreProcessorContext, type PublishedPhotoMemory, type QuantizedEmbedding, type QuarantinedMemoryInfo, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankableVaultMemory, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, SHORT_TTL_MS, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageDetachedResult, type SendMessageWithStorageResult, type ServerToolsOptions, type ServerToolsResponse, type SignMessageFn, type StockPriceClassification, type StockPricePreProcessorOptions, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredConversationMemory, type StoredMessage, type StoredMessageWithSimilarity, type StoredVaultFolder, VaultFolder as StoredVaultFolderModel, type StoredVaultMemory, VaultMemory as StoredVaultMemoryModel, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, type SynthesizeProfileOptions, TOOL_RESULT_ORIGIN, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildNotionAuthUrl, capHopsForDensity, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageSourceResolver, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decodeChunkVector, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, encodeChunkVector, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getConversationsPageOp, getDecayCandidatesRawOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoriesByIdsOp, getVaultMemoryOp, getVaultRankingProjectionsOp, hardDeleteDecayedOp, hasEncryptionKey, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isPiiRedactor, isRerankerAvailable, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, parseMedia, preEmbedVaultMemories, quantizeEmbedding, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, refreshNotionAccessToken, registerNotionClient, relinkMemoryTopicsOp, requestEncryptionKey, resolvePiiRedactor, restoreVaultMemoryOp, resumeStream, retain, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, seedEncryptionKeys, setLogger, setMemoryVisibilityOp, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, supersedeVaultMemoryOp, synthesizeProfile, traverseGraphLane, ttlForType, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, verifyMemoriesForPublish, xhrTransport };

package/dist/expo/index.d.ts

@@ -4862,6 +4862,44 @@ interface EntityOperationsContext {
     allowUnscopedRows?: boolean;
 }
 
+/**
+ * Shared portal LLM call for the memory pipeline.
+ *
+ * The three LLM-driven steps (`extractFacts`, `consolidateMemory`,
+ * `decomposeQuery`) share the same shape: POST to `/api/v1/chat/completions`
+ * with a system+user prompt and `response_format: json_object`, parse
+ * `choices[0].message.content` as JSON, validate, return null on any failure.
+ * This helper owns the fetch+timeout+parse+log boilerplate so each caller
+ * stays focused on its prompt and validator.
+ *
+ * PROMPT CACHING. The portal inserts explicit prompt-cache breakpoints only for
+ * `anthropic/` models. Its request schema does carry OpenAI's
+ * `prompt_cache_key`, but that is a routing hint for OpenAI's own implicit
+ * cache rather than a switch that enables caching, and we deliberately don't
+ * send it: the memory pipeline runs open-weights models by default (gpt-oss for
+ * extraction/topics, ling for consolidation), and this module already has one
+ * hard lesson about OpenAI-standard fields a non-OpenAI provider hard-400s on
+ * (`response_format`, below). Revisit only with a verified per-provider gate.
+ *
+ * So on the models this pipeline actually uses, the only cache that can hit is
+ * the provider's own implicit prefix cache — which makes prefix stability the
+ * one lever a caller controls. Messages are assembled system-first (below), so
+ * every caller must pass a CONSTANT `systemPrompt` and keep all per-call
+ * material in `userMessage`: a single interpolated timestamp, id, or count in a
+ * system prompt shifts every byte after it and misses the cache on every
+ * request thereafter. The memory callers are regression-gated on that property
+ * in `promptPrefixStability.test.ts`.
+ *
+ * Whether those implicit caches hit is observable: each successful response
+ * logs the portal's reported token counts at debug level, including
+ * `portal.cached_tokens` (the prompt tokens the provider served from cache —
+ * the portal omits the field when there was no hit). See {@link logPortalUsage}.
+ *
+ * There is no batch/async-bulk route on the portal, so a backfill or reindex
+ * has no discounted-throughput path either; its only levers are the same stable
+ * prefix and caller-side batching (e.g. topicExtract's 10-memories-per-call).
+ */
+
 /**
  * Auth for portal LLM calls (extraction, consolidation, decomposition,
  * reflection). Mirrors `memoryEngine`'s `EmbeddingOptions` dual-auth:
@@ -4880,6 +4918,60 @@ interface PortalLlmAuth {
     /** Function to get an auth token (e.g., Privy's getIdentityToken). Token is sent as `Authorization: Bearer`. */
     getToken?: () => Promise<string | null>;
 }
+/**
+ * Why a portal JSON completion gave up, as a STABLE low-cardinality code.
+ *
+ * The retry loop has always classified its failures precisely, but only as an
+ * interpolated `reason` string for `log.warn` — and prod ships no SDK log
+ * (sdk#883), so in production every one of these collapsed into a single
+ * `empty-after-retry` with no way to tell them apart. That is what made the
+ * 2026-08-11 audit need a Prometheus cross-check to discover that the portal
+ * was returning HTTP 200 with an empty body on ~60% of extraction turns.
+ *
+ * Codes are deliberately an enum, not the `reason` string: the strings embed
+ * status codes and error messages, so they are unbounded and useless as an
+ * analytics property. Keep this list SHORT and stable — it is a telemetry
+ * contract, and a value added here has to mean the same thing in six months.
+ *
+ * @public
+ */
+type PortalLlmFailureReason = 
+/** No usable credential — `getToken` returned null or threw. Terminal. */
+"auth-unavailable"
+/** Non-retryable HTTP status (400/403/404, or 401 on the static-apiKey path). */
+ | "http-terminal"
+/** Retryable status (408/409/425/429/5xx) that never succeeded. */
+ | "http-retryable"
+/** Network error or the per-attempt timeout aborted the fetch. */
+ | "network"
+/** HTTP 200 but the envelope itself wasn't JSON. */
+ | "body-parse-failed"
+/**
+ * HTTP 200 with NO completion content. The reasoning-class failure mode:
+ * the model spends its budget on unreturned thinking and answers empty.
+ */
+ | "empty-content"
+/** Content present, but no parseable JSON in it (prose, a clarifying question). */
+ | "invalid-json"
+/** Content parsed to a literal `null`, which is never a valid response. */
+ | "null-completion"
+/** `totalTimeoutMs` was spent before the next attempt could run. */
+ | "time-budget-exhausted";
+/**
+ * A give-up report: the classified {@link PortalLlmFailureReason} plus the
+ * little context worth carrying into telemetry. Both extra fields are bounded
+ * (a status code, a small attempt count), so both are safe as event properties.
+ *
+ * @public
+ */
+interface PortalLlmFailure {
+    /** Stable code for the last failure observed. */
+    reason: PortalLlmFailureReason;
+    /** HTTP status, when the failure was an HTTP one. */
+    httpStatus?: number;
+    /** How many attempts ran before giving up (1-based, ≥ 1). */
+    attempts: number;
+}
 
 /**
  * Optional LLM injection classifier — Tier-0 security second layer (PR5).
@@ -5984,8 +6076,14 @@ interface ExtractFactsOptions extends PortalLlmAuth {
      * `{candidates: []}` "nothing durable here". Lets callers distinguish a
      * silently-degrading extractor from quiet turns (the two are otherwise
      * indistinguishable). See {@link extractAndRetain}'s `outcome`.
+     *
+     * Receives the classified {@link PortalLlmFailure}. Knowing THAT extraction
+     * failed was not enough: the 2026-08-11 audit found ~60% of production turns
+     * ending here and had to cross-check Prometheus to learn that the cause was
+     * HTTP-200-with-empty-body rather than the 403 everyone assumed. Forward
+     * `failure.reason` into analytics so the next such question is a query.
      */
-    onExhaustedEmpty?: () => void;
+    onExhaustedEmpty?: (failure: PortalLlmFailure) => void;
     /**
      * Called when the extractor DID produce candidates but PII de-anonymization
      * dropped every one of them — the model mangled its placeholders (so they
@@ -6108,6 +6206,11 @@ declare function extractAndRetain(messages: AutoExtractMessage[], retainCtx: Ret
      * "extracted but held for review".
      */
     quarantined: QuarantinedMemoryInfo[];
+    /**
+     * Present only when `outcome` is `empty-after-retry` — the classified cause of
+     * the give-up, so "extraction is failing" can be reported as *why* it failed.
+     */
+    failure?: PortalLlmFailure;
 }>;
 
 /**
@@ -10232,4 +10335,4 @@ declare function refreshNotionAccessToken(params: NotionRefreshTokenParams): Pro
  */
 declare function createNotionTools(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig[];
 
-export { type AutoExtractMessage, type AutoExtractor, type Budget, CHUNKS_DISCARDED_ORIGIN, type CachedChunkVectors, type CachedServerTools, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ChunkVectorCache, type ChunkingOptions, type ConsolidationFallbackReason, type ConversationMemoryInput, ConversationMemory as ConversationMemoryModel, type ConversationMemoryOperationsContext, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateDecaySweeperOptions, type CreateMessageOptions, type CreateVaultFolderOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_DECAY_POLICY, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetConversationsPageOptions, type GetMessagesPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type Logger, LoggerProvider, type LoggerProviderProps, MAX_HOPS, MEDIUM_TTL_MS, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, type MessageRedactionResult, type MessageSkeleton, NEVER_TTL_MS, NODE_BUDGET, NOTION_OAUTH_CONFIG, type NeighborRefiner, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, type NowSource, type ObservationTrend, type ObservationTrendInput, PAST_EVENT_GRACE_MS, PII_PATTERNS, PROFILE_DOC_VERSION, type PhotoIngestResult, type PhotoMediaRef, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type PromptPreProcessor, type PromptPreProcessorContext, type PublishedPhotoMemory, type QuantizedEmbedding, type QuarantinedMemoryInfo, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankableVaultMemory, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, SHORT_TTL_MS, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageDetachedResult, type SendMessageWithStorageResult, type ServerToolsOptions, type ServerToolsResponse, type SignMessageFn, type StockPriceClassification, type StockPricePreProcessorOptions, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredConversationMemory, type StoredMessage, type StoredMessageWithSimilarity, type StoredVaultFolder, VaultFolder as StoredVaultFolderModel, type StoredVaultMemory, VaultMemory as StoredVaultMemoryModel, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, type SynthesizeProfileOptions, TOOL_RESULT_ORIGIN, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildNotionAuthUrl, capHopsForDensity, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageSourceResolver, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decodeChunkVector, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, encodeChunkVector, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getConversationsPageOp, getDecayCandidatesRawOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoriesByIdsOp, getVaultMemoryOp, getVaultRankingProjectionsOp, hardDeleteDecayedOp, hasEncryptionKey, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isPiiRedactor, isRerankerAvailable, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, parseMedia, preEmbedVaultMemories, quantizeEmbedding, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, refreshNotionAccessToken, registerNotionClient, relinkMemoryTopicsOp, requestEncryptionKey, resolvePiiRedactor, restoreVaultMemoryOp, resumeStream, retain, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, seedEncryptionKeys, setLogger, setMemoryVisibilityOp, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, supersedeVaultMemoryOp, synthesizeProfile, traverseGraphLane, ttlForType, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, verifyMemoriesForPublish, xhrTransport };
+export { type AutoExtractMessage, type AutoExtractor, type Budget, CHUNKS_DISCARDED_ORIGIN, type CachedChunkVectors, type CachedServerTools, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ChunkVectorCache, type ChunkingOptions, type ConsolidationFallbackReason, type ConversationMemoryInput, ConversationMemory as ConversationMemoryModel, type ConversationMemoryOperationsContext, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateDecaySweeperOptions, type CreateMessageOptions, type CreateVaultFolderOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_DECAY_POLICY, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetConversationsPageOptions, type GetMessagesPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type Logger, LoggerProvider, type LoggerProviderProps, MAX_HOPS, MEDIUM_TTL_MS, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, type MessageRedactionResult, type MessageSkeleton, NEVER_TTL_MS, NODE_BUDGET, NOTION_OAUTH_CONFIG, type NeighborRefiner, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, type NowSource, type ObservationTrend, type ObservationTrendInput, PAST_EVENT_GRACE_MS, PII_PATTERNS, PROFILE_DOC_VERSION, type PhotoIngestResult, type PhotoMediaRef, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type PromptPreProcessor, type PromptPreProcessorContext, type PublishedPhotoMemory, type QuantizedEmbedding, type QuarantinedMemoryInfo, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankableVaultMemory, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, SHORT_TTL_MS, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageDetachedResult, type SendMessageWithStorageResult, type ServerToolsOptions, type ServerToolsResponse, type SignMessageFn, type StockPriceClassification, type StockPricePreProcessorOptions, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredConversationMemory, type StoredMessage, type StoredMessageWithSimilarity, type StoredVaultFolder, VaultFolder as StoredVaultFolderModel, type StoredVaultMemory, VaultMemory as StoredVaultMemoryModel, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, type SynthesizeProfileOptions, TOOL_RESULT_ORIGIN, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildNotionAuthUrl, capHopsForDensity, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageSourceResolver, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decodeChunkVector, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, encodeChunkVector, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getConversationsPageOp, getDecayCandidatesRawOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoriesByIdsOp, getVaultMemoryOp, getVaultRankingProjectionsOp, hardDeleteDecayedOp, hasEncryptionKey, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isPiiRedactor, isRerankerAvailable, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, parseMedia, preEmbedVaultMemories, quantizeEmbedding, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, refreshNotionAccessToken, registerNotionClient, relinkMemoryTopicsOp, requestEncryptionKey, resolvePiiRedactor, restoreVaultMemoryOp, resumeStream, retain, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, seedEncryptionKeys, setLogger, setMemoryVisibilityOp, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, supersedeVaultMemoryOp, synthesizeProfile, traverseGraphLane, ttlForType, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, verifyMemoriesForPublish, xhrTransport };

package/dist/expo/index.mjs

@@ -132,7 +132,7 @@ import {
   upsertMessageOp,
   useEncryption,
   vaultMemoryToStored
-} from "./chunk-2YHVYDEL.mjs";
+} from "./chunk-YO5UXOC4.mjs";
 import {
   PII_PATTERNS,
   PiiRedactor,
@@ -140,7 +140,7 @@ import {
   isPiiRedactor,
   notifyConsolidationFallback,
   resolvePiiRedactor
-} from "./chunk-VOMDHMKH.mjs";
+} from "./chunk-OUFITMDL.mjs";
 import {
   INTERNAL_FLOW_MARKER,
   callPortalJsonCompletion,
@@ -151,9 +151,10 @@ import {
   resolvePortalAuthHeaders,
   setLogger,
   supportsResponseFormat,
+  taskTypeHeader,
   validateEndpointOverride,
   withInternalFlowMarker
-} from "./chunk-B5UPJRCU.mjs";
+} from "./chunk-CJ32HO6Q.mjs";
 import {
   BASE_URL,
   MCP_R2_DOMAIN,
@@ -4788,7 +4789,12 @@ async function callSummarizationLlm(prompt, model, token, baseUrl) {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${token}`
+        Authorization: `Bearer ${token}`,
+        // Names the task so the portal can own this prompt server-side instead of
+        // trusting the one we build. Summarization is the archetypal Class-B flow:
+        // one fixed purpose, no conversation, and today its instructions are ours
+        // to reword.
+        ...taskTypeHeader("summarize")
       },
       body: JSON.stringify({
         model,
@@ -6387,6 +6393,7 @@ async function classifyInjectionCandidates(candidates, options) {
       ...options.apiKey !== void 0 && { apiKey: options.apiKey },
       ...options.getToken !== void 0 && { getToken: options.getToken },
       ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+      taskType: "memory_injection_check",
       model: options.model ?? DEFAULT_MODEL,
       systemPrompt: SYSTEM_PROMPT,
       userMessage: `Candidate facts:
@@ -6861,7 +6868,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     content: m.content,
     similarity: m.similarity
   }));
-  const { consolidateMemory: doConsolidate } = await import("./consolidate-TWE6OSSZ.mjs");
+  const { consolidateMemory: doConsolidate } = await import("./consolidate-4BMNVOL4.mjs");
   const decision = await doConsolidate(trimmed, candidates, consolidateOptions);
   if (decision.action === "create") return null;
   if (decision.action === "supersede" && decision.content) {
@@ -7078,10 +7085,15 @@ async function extractFacts(messages, options) {
   }
   const transcript = transcriptLines.join("\n");
   const today = formatLocalDate(options.now ?? Date.now());
+  let failure;
   const parsed = await callPortalJsonCompletion({
+    onFailure: (f) => {
+      failure = f;
+    },
     ...options.apiKey !== void 0 && { apiKey: options.apiKey },
     ...options.getToken !== void 0 && { getToken: options.getToken },
     ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+    taskType: "memory_extract",
     ...options.endpointOverride !== void 0 && {
       endpointOverride: options.endpointOverride
     },
@@ -7101,7 +7113,7 @@ Extract durable user facts.`,
     ...options.backoffMs && { backoffMs: options.backoffMs }
   });
   if (parsed === null) {
-    options.onExhaustedEmpty?.();
+    options.onExhaustedEmpty?.(failure ?? { reason: "empty-content", attempts: 1 });
     return [];
   }
   const fallbackSourceId = [...messages].reverse().find((m) => m.role === "user")?.id;
@@ -7145,14 +7157,16 @@ async function extractAndRetain(messages, retainCtx, options) {
     ...resolvedConsolidatePii !== void 0 && { piiRedaction: resolvedConsolidatePii }
   } : void 0;
   let exhaustedEmpty = false;
+  let exhaustedFailure;
   let droppedAfterRedaction = false;
   const callerOnExhaustedEmpty = options.extract.onExhaustedEmpty;
   const callerOnCandidatesDropped = options.extract.onCandidatesDropped;
   const candidates = await extractFacts(messages, {
     ...options.extract,
-    onExhaustedEmpty: () => {
+    onExhaustedEmpty: (failure) => {
       exhaustedEmpty = true;
-      callerOnExhaustedEmpty?.();
+      exhaustedFailure = failure;
+      callerOnExhaustedEmpty?.(failure);
     },
     onCandidatesDropped: () => {
       droppedAfterRedaction = true;
@@ -7271,12 +7285,19 @@ async function extractAndRetain(messages, retainCtx, options) {
     results,
     failedCount: failedWrites,
     outcome,
-    quarantined: quarantinedInfo
+    quarantined: quarantinedInfo,
+    // Only meaningful alongside `outcome: "empty-after-retry"`. Returned as well
+    // as pushed through the callback so a consumer that only inspects the result
+    // (rather than wiring a hook) can still report WHY.
+    ...exhaustedFailure !== void 0 && { failure: exhaustedFailure }
   };
 }
+var UTTERANCE_ECHO_RE = /^(?:said|says|asked|answered|replied|guessed|typed)\s*:\s*(?:'[^']*'|"[^"]*"|‘[^’]*’|“[^”]*”)[\s.!?]*$/iu;
 function isLowSignalContent(content, ownNames) {
-  const normalized = content.trim().replace(/[.!?]+$/, "").toLowerCase();
+  const trimmed = content.trim();
+  const normalized = trimmed.replace(/[.!?]+$/, "").toLowerCase();
   if (normalized.length < MIN_CONTENT_LENGTH) return true;
+  if (UTTERANCE_ECHO_RE.test(trimmed)) return true;
   if (ownNames.some(
     (n) => normalized === n.trim().replace(/[.!?]+$/, "").toLowerCase()
   )) {
@@ -7635,6 +7656,7 @@ function createLlmDecayClassifier(options) {
           ...options.apiKey !== void 0 && { apiKey: options.apiKey },
           ...options.getToken !== void 0 && { getToken: options.getToken },
           ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+          taskType: "memory_decay",
           model: options.model ?? DEFAULT_MODEL2,
           systemPrompt: SYSTEM_PROMPT3,
           userMessage: `Memory content:
@@ -8758,6 +8780,7 @@ When a memory refers to one of these, reuse the EXACT existing name (same spelli
       ...options.apiKey !== void 0 && { apiKey: options.apiKey },
       ...options.getToken !== void 0 && { getToken: options.getToken },
       ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+      taskType: "memory_topic",
       ...options.endpointOverride !== void 0 && {
         endpointOverride: options.endpointOverride
       },
@@ -8947,6 +8970,7 @@ ${evidence}`);
       ...options.apiKey !== void 0 && { apiKey: options.apiKey },
       ...options.getToken !== void 0 && { getToken: options.getToken },
       ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+      taskType: "memory_verify_support",
       model: options.model ?? DEFAULT_MODEL4,
       systemPrompt: SYSTEM_PROMPT5,
       userMessage: `Stored facts and their sources:

package/dist/expo/{recall-M3JVFTZL.mjs → recall-IEKVX4JL.mjs}

@@ -1,7 +1,7 @@
 import {
   recall
-} from "./chunk-2YHVYDEL.mjs";
-import "./chunk-B5UPJRCU.mjs";
+} from "./chunk-YO5UXOC4.mjs";
+import "./chunk-CJ32HO6Q.mjs";
 import "./chunk-GYKJOWEO.mjs";
 export {
   recall

package/dist/index.cjs

@@ -76,6 +76,7 @@ __export(index_exports, {
   PII_PATTERNS: () => PII_PATTERNS,
   PiiRedactor: () => PiiRedactor,
   SseIdleTimeoutError: () => SseIdleTimeoutError,
+  TASK_TYPE_HEADER: () => TASK_TYPE_HEADER,
   TOOL_CATALOG: () => TOOL_CATALOG,
   TOOL_RESULT_ORIGIN: () => TOOL_RESULT_ORIGIN,
   activatedToolSetNames: () => activatedToolSetNames,
@@ -194,6 +195,7 @@ __export(index_exports, {
   selectServerSideTools: () => selectServerSideTools,
   setLogger: () => setLogger,
   shouldAnalyzeStyle: () => shouldAnalyzeStyle,
+  taskTypeHeader: () => taskTypeHeader,
   toolSetSystemPrompts: () => toolSetSystemPrompts,
   withSseKeepalive: () => withSseKeepalive
 });
@@ -3800,6 +3802,12 @@ function createStreamingDeAnonymizer(redactor, emit) {
     }
   };
 }
+
+// src/lib/taskType.ts
+var TASK_TYPE_HEADER = "X-Anuma-Task-Type";
+function taskTypeHeader(taskType) {
+  return taskType ? { [TASK_TYPE_HEADER]: taskType } : {};
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUILT_IN_TOOL_SETS,
@@ -3818,6 +3826,7 @@ function createStreamingDeAnonymizer(redactor, emit) {
   PII_PATTERNS,
   PiiRedactor,
   SseIdleTimeoutError,
+  TASK_TYPE_HEADER,
   TOOL_CATALOG,
   TOOL_RESULT_ORIGIN,
   activatedToolSetNames,
@@ -3936,6 +3945,7 @@ function createStreamingDeAnonymizer(redactor, emit) {
   selectServerSideTools,
   setLogger,
   shouldAnalyzeStyle,
+  taskTypeHeader,
   toolSetSystemPrompts,
   withSseKeepalive
 });