BOHICA-LABS / BOHICA-LABS/vsdd-factory
feat(observability): infer compaction events from a context-size retrograde drop (telemetry-only fallback)
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
For environments where the factory's compaction hooks aren't the signal source (e.g. compaction cadence is wanted purely from the observability stack, or #317's in-hook emit isn't wired), there is currently **no way to observe compactions from telemetry alone**. Claude Code's native OTel exposes token-*usage* counters but **no context-window-occupancy gauge**, and nothing infers a compaction from the telemetry. This requests a fallback: track a context-size proxy and treat a **retrograde drop** as an inferred compaction event.
## The observation
A session's per-message **input-token footprint** grows as the conversation accumulates, then **drops sharply immediately after a compaction** (the prior context was summarized/shrunk). So a retrograde step-down in per-request input size between consecutive requests in a session is an observable proxy for "a compaction just happened" — even with no hook and no occupancy gauge.
## What exists / what's missing
- `claude-telemetry` already ships Claude Code's native metrics to Prometheus, including `claude_code_token_usage_tokens_total{type=input|output|cacheRead|cacheCreation}`.
- That metric is a **monotonic counter** (cumulative), so a naive read never goes retrograde. Detecting the step-down needs the **per-request input-token size** (a gauge, or the counter's per-request delta), keyed by session.
- Nothing today derives an inferred-compaction event or a cadence from this.
## Proposed feature
1. Expose/recover a per-request **input-token-size** signal per session (emit a gauge, or compute the per-request delta of the existing counter).
2. Detect a **sharp retrograde drop** between consecutive requests in a session (threshold/ratio configurable) and record it as an **inferred `context.compaction`** event.
3. Feed those inferred events into the same cadence detection + advisory as the primary path (sibling issue, linked below) — so cadence works whether the source is the in-hook emit (#317) or this telemetry-only proxy.
## Constraints (SOUL.md alignment)
- **Advisory / opt-in** — a detection/inference layer over telemetry the user already opted into via `claude-telemetry`; no new collection, no phone-home (local collector only).
- **Single source** — derive from the existing token metric; do not add a parallel hand-maintained record.
- **Gradual elaboration** — this is the *fallback*; prefer #317's explicit event where available. Build the proxy only where the explicit signal can't be.
## Relationship
- Fallback signal source for #318 (compaction-cadence detection/advisory) when #317 (explicit OTEL emit from the hook) isn't available.
- Same underlying pathology as #306 (thrash via repeated compaction); this is the telemetry-only way to see it.
## Environment
- vsdd-factory develop tip (E-18; `claude-telemetry` + `factory-obs` Prometheus). Metric: `claude_code_token_usage_tokens_total` (cumulative counter).
Contributor guide
Assessment
This issue has not been assessed yet.