@anvailabs/sandhi 0.7.0 → 0.9.0

package/README.md

@@ -86,4 +86,11 @@ for await (const eventJson of provider.streamJson(request)) {
 credentials cannot be overridden. Invalid documents fail before network I/O; provider failures
 throw `SandhiProviderError` with a structured `ProviderErrorV1` payload.
 
+Canonical streams may emit accounting-only `usage` events before content or after a
+numeric usage snapshot. When `usage.completeness` is `"unavailable"` and a valid
+`cache_read_observation` is present, merge that metadata without adding its counters or replacing the last
+numeric snapshot/completeness. It is not a second final usage verdict. These events
+preserve evidence for consumers that stop reading after content; transparent and
+translated provider wire responses are unchanged.
+
 Apache-2.0. The transport surface links `sandhi-providers` (async HTTP stack) into the addon.

package/contracts.d.ts

@@ -1,11 +1,15 @@
 // Generated by scripts/gen-binding-contract-facades.py; DO NOT EDIT.
-// schema-sha256: b6ef1e7aeedcf9356c5babbd40e95f457edda7b26719a91af16906b880481e14
+// schema-sha256: 7f9ce844567386398289921d885209b0b49587bba0f148aac64e803f90a029f5
 export type JsonValue = unknown
 export type Role = "developer" | "system" | "user" | "assistant" | "tool" | "function"
 export type FinishReasonV1 = "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | "unknown"
 export type UsageCompleteness = "final" | "partial" | "unavailable"
 export type UsageBasis = "provider_reported" | "estimated"
 export type LatencySource = "origin" | "boundary"
+export type CacheReadStatus = "reported" | "absent" | "malformed" | "unsupported"
+export type CacheReadSource = "origin_usage" | "caller_supplied" | "explicit_capability"
+export interface CacheReadObservation { status: CacheReadStatus; source: CacheReadSource }
+export interface CacheReadCoverage { reported: number; absent: number; malformed: number; unsupported: number; unknown: number }
 export type ContentPart =
   | { type: "text"; text: string }
   | { type: "image_url"; image_url: string; detail?: string }
@@ -31,6 +35,7 @@ export interface ChatRequestV1 {
 }
 export interface UsageV2 {
   tokens_in: number; tokens_out: number; cache_creation_tokens: number; cache_read_tokens: number
+  cache_read_observation?: CacheReadObservation
   completeness?: UsageCompleteness; basis?: UsageBasis; attempts?: number; outcome?: string
   upstream_request_id?: string
   duration_ms?: number; duration_source?: LatencySource
@@ -43,6 +48,7 @@ export interface LatencySummary { samples: number; p50_ms: number; p95_ms: numbe
 export interface UsageAggregateV1 {
   key: string; calls: number; tokens_in: number; tokens_out: number;
   cache_creation_tokens: number; cache_read_tokens: number; reasoning_tokens: number;
+  cache_read_coverage?: CacheReadCoverage
   billable_tokens: number; latency?: LatencySummary
 }
 export interface AssistantOutputV1 { content?: MessageContent; tool_calls?: ToolCallV1[]; refusal?: string }

package/index.d.ts

@@ -4,11 +4,16 @@
 /* auto-generated by NAPI-RS */
 
 /** The neutral token breakdown parsed from a provider response. */
+export interface CacheReadObservationValue {
+  status: string
+  source: string
+}
 export interface UsageBreakdown {
   tokensIn: number
   tokensOut: number
   cacheCreationTokens: number
   cacheReadTokens: number
+  cacheReadObservation?: CacheReadObservationValue
   reasoningTokens: number
   reasoningIncluded?: boolean
   durationMs?: number
@@ -33,6 +38,7 @@ export interface Event {
   reasoningIncluded?: boolean
   cacheCreationTokens: number
   cacheReadTokens: number
+  cacheReadObservation?: CacheReadObservationValue
   usageCompleteness: string
   attempts: number
   outcome?: string
@@ -135,7 +141,7 @@ export declare class Gateway {
    * provider Sandhi doesn't natively parse: do your own parsing and pass the counts. Same
    * attribution + budget + emit as `meter()`.
    */
-  meterTokens(virtualKey: string, provider: string, model: string, tokensIn: number, tokensOut: number, cacheCreationTokens?: number | undefined | null, cacheReadTokens?: number | undefined | null, sessionId?: string | undefined | null, route?: string | undefined | null): Event
+  meterTokens(virtualKey: string, provider: string, model: string, tokensIn: number, tokensOut: number, cacheCreationTokens?: number | undefined | null, cacheReadTokens?: number | undefined | null, sessionId?: string | undefined | null, route?: string | undefined | null, cacheReadObservation?: unknown | undefined | null): Event
   /** All events emitted so far (in-memory). */
   events(): Array<Event>
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvailabs/sandhi",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Sandhi — the metering layer for AI agents (Node binding): in-process virtual keys, budgets, and neutral usage-event metering.",
   "license": "Apache-2.0",
   "repository": "https://github.com/anvai-labs/sandhi",
@@ -47,7 +47,7 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@anvailabs/sandhi-linux-x64-gnu": "0.7.0",
-    "@anvailabs/sandhi-darwin-arm64": "0.7.0"
+    "@anvailabs/sandhi-linux-x64-gnu": "0.9.0",
+    "@anvailabs/sandhi-darwin-arm64": "0.9.0"
   }
 }