librechat-data-provider 0.8.504 → 0.8.506

package/dist/types/types/runs.d.ts

@@ -35,6 +35,131 @@ export declare enum StepEvents {
     ON_SUMMARIZE_COMPLETE = "on_summarize_complete",
     ON_SUBAGENT_UPDATE = "on_subagent_update"
 }
+/** Token-tracking event names streamed to the client (separate from StepEvents dispatch). */
+export declare enum UsageEvents {
+    ON_CONTEXT_USAGE = "on_context_usage",
+    ON_TOKEN_USAGE = "on_token_usage"
+}
+/** Mirrors TokenBudgetBreakdown from @librechat/agents (data-provider cannot import it). */
+export type TTokenBudgetBreakdown = {
+    maxContextTokens: number;
+    instructionTokens: number;
+    systemMessageTokens: number;
+    dynamicInstructionTokens: number;
+    toolSchemaTokens: number;
+    summaryTokens: number;
+    toolCount: number;
+    messageCount: number;
+    messageTokens: number;
+    availableForMessages: number;
+    /** Per-tool schema token counts (post-multiplier), keyed by tool name */
+    toolTokenCounts?: Record<string, number>;
+    /** Names of counted tools that are deferred (`defer_loading`) and discovered */
+    deferredToolNames?: string[];
+};
+/** Per-model-call context snapshot, dispatched after pruning and before the LLM call. */
+export type TContextUsageEvent = {
+    runId?: string;
+    agentId?: string;
+    breakdown: TTokenBudgetBreakdown;
+    /** Usable budget this call: maxContextTokens minus output reserve */
+    contextBudget?: number;
+    /** Calibrated instruction overhead actually applied this call */
+    effectiveInstructionTokens?: number;
+    /** Calibrated message tokens before pruning (excluding instructions) */
+    prePruneContextTokens?: number;
+    /** Tokens still free after instructions + pruned messages */
+    remainingContextTokens?: number;
+    calibrationRatio?: number;
+    /** Output tokens of the response's final model call (the call this pre-invoke
+     *  snapshot precedes). Populated only on the persisted `metadata.contextUsage`
+     *  blob so a reloaded multi-call turn adds the same post-snapshot delta the
+     *  live finalizer did — not the full response `tokenCount`, which the snapshot
+     *  already includes for earlier steps. */
+    completedOutputTokens?: number;
+};
+/**
+ * Request payload for a server-side context-usage projection: "what context
+ * would the next call send for this branch under this config", computed by the
+ * agents SDK without invoking the model. Powers the gauge in states the live
+ * snapshot can't cover (page load of a snapshot-less branch, window/model
+ * switch). `messageId` is the viewed branch's tail; the server walks its parent
+ * chain.
+ */
+export type TContextProjectionRequest = {
+    conversationId: string;
+    messageId: string;
+    endpoint: string;
+    model?: string;
+    agentId?: string;
+    spec?: string;
+    maxContextTokens?: number;
+    /** Provider-calibrated ratio from a prior snapshot, applied as a static seed. */
+    calibrationRatio?: number;
+    /** Client-only cache-bust: a branch content revision so a message edit
+     *  (which keeps the same tail id) refetches. The server ignores it. */
+    revision?: number;
+};
+/**
+ * Per-response usage rollup persisted on `responseMessage.metadata.usage`, in
+ * display units (input excludes cache; output includes repaired completion).
+ * Normalized per-event on the backend before summing so a reloaded conversation
+ * reproduces the live branch/total usage exactly, even for mixed-provider turns
+ * (summarization/subagent calls on a different provider than the primary).
+ */
+export type TResponseUsage = {
+    input: number;
+    output: number;
+    cacheWrite: number;
+    cacheRead: number;
+    /** Authoritative USD cost; present only when `interface.contextCost` was on at save */
+    cost?: number;
+};
+/** Provider-reported usage for a single completed model call. */
+export type TTokenUsageEvent = {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    input_token_details?: {
+        cache_creation?: number;
+        cache_read?: number;
+    };
+    model?: string;
+    provider?: string;
+    /** Non-primary buckets fold into session cost/totals but not the live
+     *  context gauge: hidden sequential-agent calls (`sequential`), summary
+     *  passes (`summarization`), and isolated subagent runs (`subagent`) */
+    usage_type?: 'summarization' | 'subagent' | 'sequential';
+    runId?: string;
+    /** Per-run emission sequence; keeps identical payloads from distinct model calls unique */
+    seq?: number;
+    /** Authoritative USD cost of this call from the backend (premium tiers, cache
+     *  rates); present only when `interface.contextCost` is enabled. Clients sum
+     *  this rather than re-deriving cost from base rates. */
+    cost?: number;
+};
+/**
+ * Full prompt token count for one completed model call — the EXACT context the
+ * model saw, provider-aware: additive providers (Bedrock) report `input_tokens`
+ * excluding cache, so cache reads/writes are added back; subset providers
+ * (Anthropic, OpenAI, …) already fold cache into `input_tokens`. When the
+ * provider is absent (custom/OpenAI-compatible payloads), fall back to the same
+ * magnitude heuristic `normalizeUsageUnits` uses — cache ≤ input means it's
+ * already included — so cached events aren't re-inflated. The ground truth the
+ * gauge reconciles its calibrated estimate to.
+ */
+export declare const promptTokensFromUsage: (event: TTokenUsageEvent) => number;
+/**
+ * Reconciles a pre-invoke context snapshot's CALIBRATED estimate to a call's
+ * ACTUAL prompt tokens. The SDK's calibration multiplier scales only
+ * `messageTokens` (instructions/summary are raw tiktoken counts), and it can
+ * over-shoot badly when a provider injects server-side content the SDK never
+ * counted (e.g. Anthropic web search) — pinning the gauge several× too high and
+ * persisting it. Trust the provider's own prompt count: keep the raw
+ * instruction/summary rows, set `messageTokens` to the remainder, and recompute
+ * the free space. No-op when `promptTokens` is unusable.
+ */
+export declare const reconcileContextUsage: (snapshot: TContextUsageEvent, promptTokens: number) => TContextUsageEvent;
 /** Lifecycle phase carried on subagent-progress envelopes (mirrors SDK SubagentUpdatePhase). */
 export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
 /** Single streamed subagent update forwarded by the SDK's SubagentExecutor. */

package/dist/types/types.d.ts

@@ -7,7 +7,7 @@ import type { ContentTypes } from './types/runs';
 import type { Agent } from './types/assistants';
 export * from './schemas';
 export type TMessages = TMessage[];
-export type TEndpointOption = Pick<TConversation, 'endpoint' | 'endpointType' | 'model' | 'modelLabel' | 'chatGptLabel' | 'promptPrefix' | 'temperature' | 'topP' | 'topK' | 'top_p' | 'frequency_penalty' | 'presence_penalty' | 'maxOutputTokens' | 'maxContextTokens' | 'max_tokens' | 'maxTokens' | 'resendFiles' | 'imageDetail' | 'reasoning_effort' | 'verbosity' | 'instructions' | 'additional_instructions' | 'append_current_datetime' | 'tools' | 'stop' | 'region' | 'additionalModelRequestFields' | 'promptCache' | 'thinking' | 'thinkingBudget' | 'thinkingLevel' | 'effort' | 'thinkingDisplay' | 'assistant_id' | 'agent_id' | 'iconURL' | 'greeting' | 'spec' | 'artifacts' | 'file_ids' | 'system' | 'chatProjectId' | 'examples' | 'context'> & {
+export type TEndpointOption = Pick<TConversation, 'endpoint' | 'endpointType' | 'model' | 'modelLabel' | 'chatGptLabel' | 'promptPrefix' | 'temperature' | 'topP' | 'topK' | 'top_p' | 'frequency_penalty' | 'presence_penalty' | 'maxOutputTokens' | 'maxContextTokens' | 'max_tokens' | 'maxTokens' | 'resendFiles' | 'imageDetail' | 'reasoning_effort' | 'verbosity' | 'instructions' | 'additional_instructions' | 'append_current_datetime' | 'tools' | 'stop' | 'region' | 'additionalModelRequestFields' | 'promptCache' | 'promptCacheTtl' | 'thinking' | 'thinkingBudget' | 'thinkingLevel' | 'effort' | 'thinkingDisplay' | 'assistant_id' | 'agent_id' | 'iconURL' | 'greeting' | 'spec' | 'artifacts' | 'file_ids' | 'system' | 'chatProjectId' | 'examples' | 'context'> & {
     modelDisplayLabel?: string;
     key?: string | null;
     /** @deprecated Assistants API */
@@ -47,6 +47,8 @@ export type TPayload = Partial<TMessage> & Partial<TEndpointOption> & {
      * before the LLM turn runs.
      */
     manualSkills?: string[];
+    /** Browser IANA timezone (e.g. `America/New_York`) used to resolve local-time prompt variables server-side. */
+    timezone?: string;
 };
 export type TEditedContent = {
     index: number;
@@ -237,6 +239,11 @@ export type TArchiveConversationRequest = {
     isArchived: boolean;
 };
 export type TArchiveConversationResponse = TConversation;
+export type TPinConversationRequest = {
+    conversationId: string;
+    pinned: boolean;
+};
+export type TPinConversationResponse = TConversation;
 export type TSharedMessagesResponse = Omit<TSharedLink, 'messages'> & {
     messages: TMessage[];
 };
@@ -316,6 +323,16 @@ export type TConfig = {
 };
 export type TEndpointsConfig = Record<EModelEndpoint | string, TConfig | null | undefined> | undefined;
 export type TModelsConfig = Record<string, string[]>;
+/** Server-resolved context window and pricing for one model. Rates are USD per 1M tokens. */
+export type TModelTokenomics = {
+    context?: number;
+    prompt?: number;
+    completion?: number;
+    cacheWrite?: number;
+    cacheRead?: number;
+};
+/** endpoint → model → resolved tokenomics, from GET /api/endpoints/token-config */
+export type TTokenConfigMap = Record<string, Record<string, TModelTokenomics>>;
 export type TUpdateTokenCountResponse = {
     count: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "librechat-data-provider",
-  "version": "0.8.504",
+  "version": "0.8.506",
   "description": "data services for librechat apps",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -45,7 +45,7 @@
   "dependencies": {
     "axios": "^1.16.0",
     "dayjs": "^1.11.13",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.2.0",
     "zod": "^3.22.4"
   },
   "devDependencies": {