# saturate token aggregation math

`83eac7a`→[main](/content/gh/entireio/cli/commits/main/index.html)·

peyton-alt·3w ago·3 files·+83 added/-6 removed

## Sessions

df57a472eb61View transcript

## Changes

3

- cmd/entire/cli

- Mcheckpoint_tokens.go+17/-5

- Msession_tokens.go+8/-1

- Msessions_test.go+58

```
281 unmodified lines

282
283
284
285
286
287
288
289
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309

281 unmodified lines

result.APICallCount = a.APICallCount
	}
	if b != nil {
		result.InputTokens += b.InputTokens
		result.CacheCreationTokens += b.CacheCreationTokens
		result.CacheReadTokens += b.CacheReadTokens
		result.OutputTokens += b.OutputTokens
		result.APICallCount += b.APICallCount
		result.InputTokens = saturatingIntAdd(result.InputTokens, b.InputTokens)
		result.CacheCreationTokens = saturatingIntAdd(result.CacheCreationTokens, b.CacheCreationTokens)
		result.CacheReadTokens = saturatingIntAdd(result.CacheReadTokens, b.CacheReadTokens)
		result.OutputTokens = saturatingIntAdd(result.OutputTokens, b.OutputTokens)
		result.APICallCount = saturatingIntAdd(result.APICallCount, b.APICallCount)
	}
	result.SubagentTokens = addCheckpointTokenUsage(tokenUsageSubagents(a), tokenUsageSubagents(b))
	return result
}

func saturatingIntAdd(a, b int) int {
	maxValue := int(^uint(0) >> 1)
	minValue := -maxValue - 1
	if b > 0 && a > maxValue-b {
		return maxValue
	}
	if b < 0 && a < minValue-b {
		return minValue
	}
	return a + b
}

func tokenUsageSubagents(usage *agent.TokenUsage) *agent.TokenUsage {
	if usage == nil {
		return nil
	}
}

Mcmd/entire/cli/checkpoint_tokens.go+17/-5

```
287 unmodified lines

288
289
290
291
291
292
293
294
29 unmodified lines

324
325
326
327
328
329
330
331
332
333
334
335
336

287 unmodified lines

Signals:  []string{"api_call_count"},
		})
	}
	if signals.Tokens != nil && signals.Tokens.SubagentTotal > 0 && signals.Tokens.SubagentTotal*100 >= signals.Tokens.Total*10 {
	if signals.Tokens != nil && tokenShareAtLeastOneTenth(signals.Tokens.SubagentTotal, signals.Tokens.Total) {
		recs = append(recs, sessionTokensRecommendation{
			ID:       "subagent-heavy",
			Severity: "medium",
29 unmodified lines

return recs
}

func tokenShareAtLeastOneTenth(part, total int) bool {
	if part <= 0 || total <= 0 {
		return false
	}
	return part >= (total-1)/10+1
}

func tokenPercent(value, total int) float64 {
	if total <= 0 {
		return 0
	}
}

Mcmd/entire/cli/session_tokens.go+8/-1

```
1046 unmodified lines

1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
536 unmodified lines

1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652

1046 unmodified lines

}
}

func TestRecommendationRulesSubagentHeavyAvoidsOverflow(t *testing.T) {
	t.Parallel()

maxInt := int(^uint(0) >> 1)
	recs := recommendationRules(tokenRecommendationSignals{
		Tokens: &sessionTokensUsage{
			Total:         maxInt,
			SubagentTotal: maxInt,
		},
	})

for _, rec := range recs {
		if rec.ID == "subagent-heavy" {
			return
		}
	}
	t.Fatalf("expected subagent-heavy recommendation, got %+v", recs)
}

func TestTokensCmd_JSONOutputReportsLimitations(t *testing.T) {
	setupStopTestRepo(t)

536 unmodified lines

}
}

func TestAddCheckpointTokenUsageSaturatesOverflow(t *testing.T) {
	t.Parallel()

maxInt := int(^uint(0) >> 1)
	usage := addCheckpointTokenUsage(
		&agent.TokenUsage{
			InputTokens:         maxInt,
			CacheCreationTokens: maxInt,
			CacheReadTokens:     maxInt,
			OutputTokens:        maxInt,
			APICallCount:        maxInt,
			SubagentTokens: &agent.TokenUsage{
				InputTokens: maxInt,
			},
		},
		&agent.TokenUsage{
			InputTokens:         1,
			CacheCreationTokens: 1,
			CacheReadTokens:     1,
			OutputTokens:        1,
			APICallCount:        1,
			SubagentTokens: &agent.TokenUsage{
				InputTokens: 1,
			},
		},
	)

if usage.InputTokens != maxInt ||
		usage.CacheCreationTokens != maxInt ||
		usage.CacheReadTokens != maxInt ||
		usage.OutputTokens != maxInt ||
		usage.APICallCount != maxInt {
		t.Fatalf("expected saturated top-level usage, got %+v", usage)
	}
	if usage.SubagentTokens == nil || usage.SubagentTokens.InputTokens != maxInt {
		t.Fatalf("expected saturated subagent usage, got %+v", usage.SubagentTokens)
	}
}

func TestInfoCmd_EndedSession(t *testing.T) {
	setupStopTestRepo(t)