Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Record context size as its own field, not as usage

Claudee61526e69ed4
diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.go
index 61750522..24c196a1 100644
--- a/cli/beacon-hooks/cmd/endpoint_events.go
+++ b/cli/beacon-hooks/cmd/endpoint_events.go
@@ -66,6 +66,38 @@ func rawPayloadKey(platform string) string {
return rawPayloadKeys[platform]
}
+// applyContextSize promotes a runtime's reported context size into gen_ai.context.
+//
+// Separate from usage on purpose. gen_ai.usage is additive and every report sums it; context size
+// is a level at one moment, and Qwen Code -- the first runtime to report one -- is exactly where
+// summing goes wrong: its Stop payload's input_tokens is the prompt for that turn, which already
+// contains every prior turn, so a session's total would grow with the square of its length. Read as
+// context occupancy the same number is exact and worth having.
+//
+// Both halves are required before either is written. "input_tokens" is Qwen's name for the context
+// measure and also the ecosystem's name for an additive usage count, so a reported limit beside it
+// is what says which one this payload means. Promoting a bare input_tokens here would reclassify
+// other runtimes' spend as context.
+//
+// Read from the shared alias lists rather than a per-runtime branch, the way tool call ids are, so
+// a second runtime reporting the same thing needs a spelling added and nothing else.
+func applyContextSize(fields, input map[string]interface{}) {
+ if fields == nil || input == nil {
+ return
+ }
+ limit, ok := firstToolIntAcross([]map[string]interface{}{input}, asymptoteobserve.ContextLimitKeys...)
+ if !ok || limit <= 0 {
+ return
+ }
+ used, ok := firstToolIntAcross([]map[string]interface{}{input}, asymptoteobserve.ContextUsedKeys...)
+ if !ok || used <= 0 {
+ return
+ }
+ fields["gen_ai"] = mergeNested(fields["gen_ai"], map[string]interface{}{
+ "context": map[string]interface{}{"used_tokens": used, "limit_tokens": limit},
+ })
+}
+
func emitHookEventWithFidelity(logger *logging.Logger, action, category, severity, message, fidelity string, input map[string]interface{}, fields map[string]interface{}) {
if fields == nil {
fields = map[string]interface{}{}
@@ -75,6 +107,7 @@ func emitHookEventWithFidelity(logger *logging.Logger, action, category, severit
fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{key: input})
}
applyToolCallID(fields, input)
+ applyContextSize(fields, input)
if model := getFirstStr(input, "model"); model != "" {
fields["model"] = model
}
diff --git a/cli/beacon-hooks/cmd/qwen_event_test.go b/cli/beacon-hooks/cmd/qwen_event_test.go
index fd816302..6feed1b7 100644
--- a/cli/beacon-hooks/cmd/qwen_event_test.go
+++ b/cli/beacon-hooks/cmd/qwen_event_test.go
@@ -2,6 +2,7 @@ package cmd
import (
"encoding/json"
+ "fmt"
"os"
"path/filepath"
"strings"
@@ -398,6 +399,54 @@ func TestQwenStopContextFieldsAreNotNormalizedIntoTokenUsage(t *testing.T) {
}
}
+// The other half of the same decision: the context measure IS normalized, into gen_ai.context
+// rather than gen_ai.usage.
+//
+// The reason they were withheld was never that the numbers are wrong -- they are exact -- but that
+// gen_ai.usage is additive and these are a level at one moment, so summing them inflates a session
+// by roughly the square of its length. A block that nothing sums is the right home, and it makes
+// Qwen's context utilization readable without making its spend wrong.
+//
+// input_tokens is the used-token count: the fixture's 110100 over a 262144 window is the 0.42 its
+// sibling context_usage reports, so context_usage is their ratio and stays in raw rather than being
+// stored a second time in different units.
+func TestQwenStopContextIsNormalizedIntoGenAIContext(t *testing.T) {
+ logPath := setupQwenHook(t)
+
+ input := readQwenFixture(t, "stop.json")
+ sessionID, _ := resolveSessionIDWithTranscript(input, platformFlag)
+ logger := newHookLogger("stop", platformFlag, sessionID)
+ emitHookEvent(logger, "tool.completed", "tool", "info", "Agent response completed", input, sessionFields(sessionID, input))
+
+ event := lastEndpointEvent(t, logPath)
+ genAI, ok := event["gen_ai"].(map[string]interface{})
+ if !ok {
+ t.Fatalf("event has no gen_ai block: %#v", event)
+ }
+ context, ok := genAI["context"].(map[string]interface{})
+ if !ok {
+ t.Fatalf("gen_ai has no context block: %#v", genAI)
+ }
+ raw := event["raw"].(map[string]interface{})["qwen"].(map[string]interface{})
+ for _, pair := range []struct{ normalized, source string }{
+ {"used_tokens", "input_tokens"},
+ {"limit_tokens", "context_limit"},
+ } {
+ got, want := context[pair.normalized], raw[pair.source]
+ if got == nil {
+ t.Errorf("gen_ai.context.%s missing, want the value of raw.qwen.%s (%v)", pair.normalized, pair.source, want)
+ continue
+ }
+ if fmt.Sprint(got) != fmt.Sprint(want) {
+ t.Errorf("gen_ai.context.%s = %v, want raw.qwen.%s = %v", pair.normalized, got, pair.source, want)
+ }
+ }
+ // The additive block stays empty: this is the guarantee the sibling test above protects.
+ if usage, ok := genAI["usage"]; ok {
+ t.Fatalf("gen_ai.usage = %#v; context size must never land in the block reports sum", usage)
+ }
+}
+
// The lifecycle events a session is reconstructed from. Prompt text and the session model are what
// make a Qwen session legible in the dashboard rather than a list of anonymous tool calls.
func TestQwenSessionLifecycleIsRecorded(t *testing.T) {
diff --git a/cli/beacon/internal/endpoint/schema/event.go b/cli/beacon/internal/endpoint/schema/event.go
index baba4f38..3f172d0d 100644
--- a/cli/beacon/internal/endpoint/schema/event.go
+++ b/cli/beacon/internal/endpoint/schema/event.go
@@ -98,6 +98,7 @@ type HealthInfo = asymptoteobserve.HealthInfo
type ServerInfo = asymptoteobserve.ServerInfo
type GenAIInfo = asymptoteobserve.GenAIInfo
type GenAIAgentInfo = asymptoteobserve.GenAIAgentInfo
+type GenAIContextInfo = asymptoteobserve.GenAIContextInfo
type GenAIConversationInfo = asymptoteobserve.GenAIConversationInfo
type GenAIDataSourceInfo = asymptoteobserve.GenAIDataSourceInfo
type GenAIEmbeddingsInfo = asymptoteobserve.GenAIEmbeddingsInfo
diff --git a/cli/beacon/internal/tokens/tokens.go b/cli/beacon/internal/tokens/tokens.go
index f2107040..ffdfb3a5 100644
--- a/cli/beacon/internal/tokens/tokens.go
+++ b/cli/beacon/internal/tokens/tokens.go
@@ -130,6 +130,8 @@ type usageEvent struct {
spanID string
parentSpanID string
usage Usage
+ contextUsed int64
+ contextLimit int64
cumulative bool
metricName string
rawSource string
@@ -347,10 +349,17 @@ func userKey(user schema.UserInfo) string {
func collectUsageEvents(events []schema.Event, sessionUsers sessionUserIndex) []*usageEvent {
var out []*usageEvent
for i, event := range events {
- if event.GenAI == nil || event.GenAI.Usage == nil {
+ // Context-only events count too. A runtime can report how full the window was without
+ // reporting spend -- Qwen Code does exactly that -- and those events carry the whole of
+ // its context utilization. Gating on usage alone dropped them before they reached the
+ // utilization report, which is the one place they belong.
+ if event.GenAI == nil || (event.GenAI.Usage == nil && event.GenAI.Context == nil) {
continue
}
usage := event.GenAI.Usage
+ if usage == nil {
+ usage = &schema.GenAIUsageInfo{}
+ }
ue := &usageEvent{
order: i,
action: event.Event.Action,
@@ -410,7 +419,15 @@ func collectUsageEvents(events []schema.Event, sessionUsers sessionUserIndex) []
if usage.CostUSD != nil {
ue.usage.CostUSD = *usage.CostUSD
}
- if ue.usage.TotalTokens() == 0 && ue.usage.ReasoningOutputTokens == 0 && ue.usage.CostUSD == 0 {
+ if context := event.GenAI.Context; context != nil {
+ if context.UsedTokens != nil {
+ ue.contextUsed = *context.UsedTokens
+ }
+ if context.LimitTokens != nil {
+ ue.contextLimit = *context.LimitTokens
+ }
+ }
+ if ue.usage.TotalTokens() == 0 && ue.usage.ReasoningOutputTokens == 0 && ue.usage.CostUSD == 0 && ue.contextUsed == 0 {
continue
}
if event.Raw != nil {
@@ -681,11 +698,20 @@ func sortedBuckets(buckets map[time.Time]*Usage) []TimeBucket {
func buildUtilization(events []*usageEvent, nearLimitRatio float64) []ModelUtilization {
type sample struct{ inputTotal int64 }
samples := map[string]map[string]*sample{}
+ reportedWindow := map[string]int64{}
for _, ue := range events {
if ue.model == "" {
continue
}
- inputTotal := ue.usage.InputTokens + ue.usage.CacheReadInputTokens + ue.usage.CacheCreationInputTokens
+ // A reported context size is the measurement; summing the usage fields only approximates
+ // it. Prefer the runtime's own number when it gave one, and take its window with it -- a
+ // reported limit reflects the tier actually in force, which a static model table cannot.
+ inputTotal := ue.contextUsed
+ if inputTotal <= 0 {
+ inputTotal = ue.usage.InputTokens + ue.usage.CacheReadInputTokens + ue.usage.CacheCreationInputTokens
+ } else if ue.contextLimit > 0 && ue.contextLimit > reportedWindow[ue.model] {
+ reportedWindow[ue.model] = ue.contextLimit
+ }
if inputTotal <= 0 {
continue
}
@@ -702,6 +728,11 @@ func buildUtilization(events []*usageEvent, nearLimitRatio float64) []ModelUtili
for model, calls := range samples {
utilization := ModelUtilization{Model: model, Calls: len(calls)}
window, known := ContextWindow(model)
+ // A window the runtime reported beats the static table, which is a best-effort snapshot
+ // and cannot know which tier a call actually ran under.
+ if reported := reportedWindow[model]; reported > 0 {
+ window, known = reported, true
+ }
if known {
utilization.ContextWindow = window
}
diff --git a/cli/beacon/internal/tokens/tokens_test.go b/cli/beacon/internal/tokens/tokens_test.go
index 74881471..f451a5e8 100644
--- a/cli/beacon/internal/tokens/tokens_test.go
+++ b/cli/beacon/internal/tokens/tokens_test.go
@@ -441,3 +441,73 @@ func TestAggregateTopLimitCapsGroups(t *testing.T) {
t.Fatalf("by_model = %#v", report.ByModel)
}
}
+
+// A runtime that reports its own context size and window is measured against those, not against
+// the static model table and not against a sum of usage fields.
+//
+// Both substitutions matter. Summing input + cache read + cache creation approximates occupancy and
+// is all Beacon has for runtimes that report nothing; a reported number is the measurement itself.
+// And a reported window reflects the tier the call actually ran under, which a table keyed on a
+// model name cannot know.
+func TestUtilizationPrefersReportedContextOverInference(t *testing.T) {
+ events := []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "qwen_code", "s1", "qwen3-coder-plus", func(e *schema.Event) {
+ e.GenAI.Usage = nil
+ e.GenAI.Context = &schema.GenAIContextInfo{
+ UsedTokens: int64Ptr(110100),
+ LimitTokens: int64Ptr(262144),
+ }
+ }),
+ }
+ report := Aggregate(events, Options{})
+ if len(report.Utilization) != 1 {
+ t.Fatalf("utilization = %+v, want one row for a context-only event", report.Utilization)
+ }
+ row := report.Utilization[0]
+ if row.ContextWindow != 262144 {
+ t.Errorf("context window = %d, want the runtime's reported 262144", row.ContextWindow)
+ }
+ if row.MaxInputTokens != 110100 {
+ t.Errorf("max input = %d, want the runtime's reported 110100", row.MaxInputTokens)
+ }
+ // 110100 / 262144 is the 0.42 Qwen reports as context_usage, which is how the fixture's three
+ // fields are known to describe one measurement.
+ if row.MaxRatio < 0.419 || row.MaxRatio > 0.421 {
+ t.Errorf("max ratio = %v, want ~0.42", row.MaxRatio)
+ }
+}
+
+// Context is a level, not spend. A context-only event must not add anything to the totals a report
+// sums, or a Qwen session's cost would grow with the square of its length.
+func TestContextOnlyEventsAddNothingToTotals(t *testing.T) {
+ events := []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "qwen_code", "s1", "qwen3-coder-plus", func(e *schema.Event) {
+ e.GenAI.Usage = nil
+ e.GenAI.Context = &schema.GenAIContextInfo{
+ UsedTokens: int64Ptr(110100),
+ LimitTokens: int64Ptr(262144),
+ }
+ }),
+ }
+ report := Aggregate(events, Options{})
+ if got := report.Totals.TotalTokens(); got != 0 {
+ t.Fatalf("totals = %d tokens, want 0 -- context occupancy is not spend", got)
+ }
+ if report.Totals.CostUSD != 0 {
+ t.Fatalf("totals cost = %v, want 0", report.Totals.CostUSD)
+ }
+}
+
+// A runtime that reports no context keeps the inferred behaviour and the static window.
+func TestUtilizationStillInfersWhenNoContextIsReported(t *testing.T) {
+ events := []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-opus-5", func(e *schema.Event) {
+ e.GenAI.Usage.InputTokens = int64Ptr(1000)
+ e.GenAI.Usage.CacheRead = &schema.GenAIUsageCacheReadInfo{InputTokens: int64Ptr(500)}
+ }),
+ }
+ report := Aggregate(events, Options{})
+ if len(report.Utilization) != 1 || report.Utilization[0].MaxInputTokens != 1500 {
+ t.Fatalf("utilization = %+v, want the summed 1500", report.Utilization)
+ }
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index a138d6b5..3ad3da58 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -1256,6 +1256,9 @@ func GenAIFromAttrs(attrs map[string]interface{}) *GenAIInfo {
if usage := GenAIUsageFromAttrs(attrs); usage != nil {
genai.Usage = usage
}
+ if context := GenAIContextFromAttrs(attrs); context != nil {
+ genai.Context = context
+ }
if name := FirstString(attrs, "gen_ai.workflow.name"); name != "" {
genai.Workflow = &GenAIWorkflowInfo{Name: name}
}
@@ -1377,6 +1380,24 @@ func GenAIUsageFromAttrs(attrs map[string]interface{}) *GenAIUsageInfo {
return usage
}
+// GenAIContextFromAttrs reads a reported context size off OTLP attributes.
+//
+// Both halves are required, which is the rule the shared alias lists set: the used-token key is
+// also the ecosystem's name for an additive usage count, and a reported limit beside it is what
+// says this payload describes how full the window was rather than what a call spent. See
+// asymptoteobserve.ContextUsedKeys.
+func GenAIContextFromAttrs(attrs map[string]interface{}) *GenAIContextInfo {
+ limit, ok := Int64Attr(attrs, asymptoteobserve.ContextLimitKeys...)
+ if !ok || limit <= 0 {
+ return nil
+ }
+ used, ok := Int64Attr(attrs, asymptoteobserve.ContextUsedKeys...)
+ if !ok || used <= 0 {
+ return nil
+ }
+ return &GenAIContextInfo{UsedTokens: &used, LimitTokens: &limit}
+}
+
func MCPFromAttrs(attrs map[string]interface{}) *MCPInfo {
server := FirstString(attrs, "mcp.server", "beacon.mcp.server", "mcp.server.name", "gen_ai.mcp.server", "mcp_server_name")
tool := FirstString(attrs, "mcp.tool", "beacon.mcp.tool", "mcp.tool.name")
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
index e18b8f10..fccafa52 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
@@ -58,6 +58,7 @@ type GenAIRetrievalInfo = asymptoteobserve.GenAIRetrievalInfo
type GenAITokenInfo = asymptoteobserve.GenAITokenInfo
type GenAIToolInfo = asymptoteobserve.GenAIToolInfo
type GenAIToolCallInfo = asymptoteobserve.GenAIToolCallInfo
+type GenAIContextInfo = asymptoteobserve.GenAIContextInfo
type GenAIUsageInfo = asymptoteobserve.GenAIUsageInfo
type GenAIUsageCacheCreationInfo = asymptoteobserve.GenAIUsageCacheCreationInfo
type GenAIUsageCacheReadInfo = asymptoteobserve.GenAIUsageCacheReadInfo
diff --git a/docs/runtimes/qwen-code.mdx b/docs/runtimes/qwen-code.mdx
index bb8c2302..19d33584 100644
--- a/docs/runtimes/qwen-code.mdx
+++ b/docs/runtimes/qwen-code.mdx
@@ -126,7 +126,7 @@ A project-level install reports that Qwen Code runs project hooks only in a trus
| Subagents | Supported through `SubagentStart` and `SubagentStop` |
| Approval decisions | Supported. Observed from `PermissionRequest`, not synthesized from pre-tool |
| Tool call identity | Supported. Qwen's `tool_use_id` / `tool_call_id` is promoted to `gen_ai.tool.call.id` and joins pre-tool and post-tool events |
-| Token usage and cost | Not normalized. See [Known gaps](#known-gaps) |
+| Token usage and cost | Not collected. Context utilization is, through `gen_ai.context`. See [Known gaps](#known-gaps) |
| Local JSONL and dashboard | Supported |
| MDM deployment | Supported for the endpoint agent. Qwen hooks are installed separately in the logged-in user's context or project context |
@@ -170,7 +170,8 @@ Qwen carries signal with no endpoint-schema field of its own: `permission_mode`
## Known gaps
- **No OTLP path.** Qwen Code is a Gemini CLI fork without Gemini's OpenTelemetry export, so there is no collector endpoint to configure. Hooks are the only collection path, and `beacon endpoint install --harness qwen` says so rather than appearing to succeed.
-- **Token usage is not normalized.** Qwen's `Stop` payload carries `context_usage`, `context_limit`, and `input_tokens`, which are session-level context counters rather than per-call usage. They are preserved under `raw.qwen` but not normalized into `gen_ai.usage`, so Qwen Code activity does not appear in `beacon token-usage` reports or the dashboard token view.
+- **Token spend is not collected, and cannot be.** Qwen's `Stop` payload carries no per-call token counts. Its `input_tokens` is the prompt for that turn, which in a multi-turn session already contains every prior turn, so summing it into `gen_ai.usage` would inflate a session's total by roughly the square of its length. Qwen Code therefore contributes no rows to the spend totals in `beacon token-usage`.
+- **Context utilization is collected.** The same numbers describe how full the window was, which is a level rather than an amount, so they normalize into `gen_ai.context` instead: `input_tokens` becomes `gen_ai.context.used_tokens` and `context_limit` becomes `gen_ai.context.limit_tokens`. Qwen Code appears in the context utilization section of `beacon token-usage`, measured against the window it reported rather than a static model table. `context_usage` is the ratio of the two and stays in `raw.qwen` rather than being stored a second time in different units.
- **A policy deny is honored in one of two phases.** The seam runs in both the `pre-tool` and `permission-request` hooks, and Asymptote returns Claude Code's deny shape, which Qwen's `PreToolUse` contract honors. Qwen's `PermissionRequest` event reads a differently shaped `hookSpecificOutput.decision` object, so a deny raised from that phase is not honored. Because the seam fails open, the cost is a deny that does not take effect on one phase, never a tool call blocked for the wrong reason.
- **Assistant text is not collected.** `MessageDisplay` is not registered, so Asymptote records no assistant output or reasoning for Qwen Code. See [Events that are not collected](#events-that-are-not-collected).
- **Project-level installs need a trusted folder.** Qwen gates project hooks behind trusted-folder status, so a user-level install is the one that works without further interaction. Grok Build has the same caveat.
diff --git a/docs/telemetry-schema/normalization.mdx b/docs/telemetry-schema/normalization.mdx
index 7879e98b..278018e4 100644
--- a/docs/telemetry-schema/normalization.mdx
+++ b/docs/telemetry-schema/normalization.mdx
@@ -17,6 +17,21 @@ The prefix is not discarded. It is recorded as `gen_ai.provider.name`, so a prov
Model ids themselves are never rewritten. Date suffixes, dots and vendor spellings are preserved as the runtime reported them, because a rule that folds `claude-sonnet-4.6` into `claude-sonnet-4-6` also turns `gpt-4.1` into `gpt-4-1`, which is not a model under any name. A split row is visible to a reader; an invented id is not.
+## Context size is not usage
+
+`gen_ai.usage` is additive: every report sums it to answer what a session spent. `gen_ai.context` is a level at one moment -- how full the model's window was on a call -- and summing it answers nothing.
+
+Qwen Code is the runtime that forced the split. Its `Stop` hook reports the prompt token count for a turn, which in a multi-turn session already contains every prior turn; added up, a session's total grows with roughly the square of its length. Read as context occupancy the same number is exact, so it is recorded in a block nothing sums:
+
+| Source signal | Normalized field |
+|---------------|------------------|
+| `input_tokens` alongside a reported limit, `gen_ai.context.used_tokens` | `gen_ai.context.used_tokens` |
+| `context_limit`, `gen_ai.context.limit_tokens` | `gen_ai.context.limit_tokens` |
+
+Both halves are required before either is recorded. `input_tokens` is also the ecosystem's usual name for a genuine additive usage count, so a reported limit beside it is what distinguishes a payload describing window occupancy from one reporting spend. Without that pairing the rule would reclassify other runtimes' spend as context.
+
+A reported `limit_tokens` also takes precedence over Asymptote's static context-window table when computing utilization, because it reflects the tier the call actually ran under rather than the default for a model name.
+
## Source mapping
| Source signal | Normalized field or action |
diff --git a/pkg/asymptoteobserve/event.go b/pkg/asymptoteobserve/event.go
index 7cfc2b91..9320c181 100644
--- a/pkg/asymptoteobserve/event.go
+++ b/pkg/asymptoteobserve/event.go
@@ -353,6 +353,28 @@ type GenAIUsageReasoningInfo struct {
OutputTokens *int64 `json:"output_tokens,omitempty"`
}
+// GenAIContextInfo records how full the model's context was, which is a level rather than an
+// amount and therefore does not belong in GenAIUsageInfo.
+//
+// Everything in gen_ai.usage is additive: a report sums it across events to answer "what did this
+// session spend". Context size is the opposite -- it is a measurement at one moment, and summing it
+// answers nothing. Qwen Code is the case that forced the distinction: its Stop hook reports the
+// prompt token count for the turn, which in a multi-turn session already contains every prior turn,
+// so adding those up inflates a session's total by roughly the square of its length. The number is
+// exact and useful; it just is not spend.
+//
+// Keeping it in its own block means a consumer cannot reach it by accident. A rule or dashboard
+// that sums gen_ai.usage still gets only additive fields, and one that wants context utilization
+// asks for it by name.
+//
+// UsedTokens is how much of the window the request occupied. LimitTokens is the window the runtime
+// reported for that call, which is better than a local model table when present because it reflects
+// the tier actually in force. Neither has an OpenTelemetry GenAI semconv equivalent.
+type GenAIContextInfo struct {
+ UsedTokens *int64 `json:"used_tokens,omitempty"`
+ LimitTokens *int64 `json:"limit_tokens,omitempty"`
+}
+
// GenAIUsageInfo mirrors the OpenTelemetry GenAI semconv usage attribute
// names. Token counts are int64 to match OTLP integer values. CostUSD has no
// semconv equivalent; it carries runtime-reported USD cost only (for example
@@ -372,6 +394,7 @@ type GenAIWorkflowInfo struct {
type GenAIInfo struct {
Agent *GenAIAgentInfo `json:"agent,omitempty"`
+ Context *GenAIContextInfo `json:"context,omitempty"`
Conversation *GenAIConversationInfo `json:"conversation,omitempty"`
DataSource *GenAIDataSourceInfo `json:"data_source,omitempty"`
Embeddings *GenAIEmbeddingsInfo `json:"embeddings,omitempty"`
diff --git a/pkg/asymptoteobserve/identity.go b/pkg/asymptoteobserve/identity.go
index 33074769..ffd774f9 100644
--- a/pkg/asymptoteobserve/identity.go
+++ b/pkg/asymptoteobserve/identity.go
@@ -123,3 +123,43 @@ func eventUUID(kind, name string) string {
hex.Encode(out, id[:])
return fmt.Sprintf("%s-%s-%s-%s-%s", out[0:8], out[8:12], out[12:16], out[16:20], out[20:32])
}
+
+// ContextUsedKeys and ContextLimitKeys are the names a runtime uses for how full the model's
+// context was on a call, and for the window it was measured against.
+//
+// Promoted to gen_ai.context on every capture path from these lists, for the reason ToolCallIDKeys
+// exists: a promotion list holding only a canonical name no runtime writes drops every real value
+// into raw. A new runtime adds its spelling here rather than growing a branch in a mapper.
+//
+// Both must be present before either is promoted, which is not the usual alias-list rule and is
+// deliberate. "input_tokens" is the name Qwen Code gives the context measure, and it is also the
+// name half the ecosystem gives a genuine additive usage count -- so the key alone cannot say which
+// it is. A reported context limit alongside it is what distinguishes a payload describing how full
+// the window is from one reporting what a call spent. Without that pairing this list would quietly
+// reclassify other runtimes' spend as context.
+//
+// The distinction matters because gen_ai.usage is additive and every report sums it, while context
+// size is a level at one moment. Qwen is the case that proves it: its Stop payload's input_tokens
+// is the prompt for that turn, which already contains every prior turn, so summing inflates a
+// session by roughly the square of its length. The same number read as context occupancy is exact
+// and useful -- 110100 of a 262144 window.
+//
+// Canonical names first, so an explicitly mapped value beats a runtime-native one.
+var ContextUsedKeys = []string{
+ "gen_ai.context.used_tokens",
+ "beacon.gen_ai.context.used_tokens",
+ // Qwen Code's Stop payload. Its sibling context_usage is this value divided by the limit, so
+ // it is derivable and stays in raw rather than being stored twice in different units.
+ "input_tokens",
+}
+
+// ContextLimitKeys names the context window a runtime reported for a call. A reported window beats
+// the local model table in cli/beacon/internal/tokens, because it reflects the tier actually in
+// force rather than the default for the model name. Its presence is also what licenses reading a
+// used-token count from an ambiguous key; see ContextUsedKeys.
+var ContextLimitKeys = []string{
+ "gen_ai.context.limit_tokens",
+ "beacon.gen_ai.context.limit_tokens",
+ // Qwen Code's Stop payload.
+ "context_limit",
+}
diff --git a/spec/threat-rules/FIELDS.md b/spec/threat-rules/FIELDS.md
index 27f95230..562c24d5 100644
--- a/spec/threat-rules/FIELDS.md
+++ b/spec/threat-rules/FIELDS.md
@@ -45,6 +45,8 @@ Regenerate with `beacon rules fields --markdown > spec/threat-rules/FIELDS.md`.
| `e.gen_ai.agent.id` | string |
| `e.gen_ai.agent.name` | string |
| `e.gen_ai.agent.version` | string |
+| `e.gen_ai.context.limit_tokens` | int |
+| `e.gen_ai.context.used_tokens` | int |
| `e.gen_ai.conversation.id` | string |
| `e.gen_ai.data_source.id` | string |
| `e.gen_ai.embeddings.dimension_count` | int |