Preserve reported token usage presence

types.go

@@ -709,8 +709,13 @@ type StructuredOutputJSONSpec struct {
 //
 // An arbitrary returned error makes Run or RunPrepared return ErrLLMGenerate
 // while preserving the client error through errors.Is rather than translating
-// it. A nil response with a nil error also produces ErrLLMGenerate. Promptkit
-// copies the non-nil response before returning from either method.
+// it. A nil response with a nil error also produces ErrLLMGenerate and
+// ErrMalformedResponse. Promptkit copies the non-nil response before returning
+// from either method. When UsagePresence is nil, nonzero usage counts are
+// treated as known and zero counts as unknown for observation only; the legacy
+// interface cannot distinguish omitted zero from measured zero. An explicit
+// UsagePresence can report known zero counts. Result usage sums the supplied
+// Usage values independently of presence.
 type LLMClient interface {
 	Generate(context.Context, GenerateRequest) (*GenerateResponse, error)
 }
@@ -741,6 +746,19 @@ type GenerateResponse struct {
 	Content string `json:"content"`
 	// Usage is the client's token accounting.
 	Usage TokenUsage `json:"usage"`
+	// UsagePresence states which usage fields were reported, including zeros.
+	// Nil uses the legacy observation fallback described by LLMClient.
+	UsagePresence *TokenUsagePresence `json:"usage_presence,omitempty"`
+}
+
+// TokenUsagePresence identifies provider-reported token counts for observation.
+// It does not change TokenUsage values or successful-result accounting.
+type TokenUsagePresence struct {
+	PromptTokens     bool `json:"prompt_tokens"`
+	CompletionTokens bool `json:"completion_tokens"`
+	TotalTokens      bool `json:"total_tokens"`
+	CachedTokens     bool `json:"cached_tokens"`
+	CacheWriteTokens bool `json:"cache_write_tokens"`
 }
 
 // File returns a file-backed artifact reference whose URI is path.