Agent context packing

Mastra explain_incident and investigate_incident are core workflows. They must not dump a pretty-printed evidence package, raw logs, or unbounded tool payloads into the model.

Product SoT (engineering): repo docs/AGENT_CONTEXT.md. OSS catalog: Open source tools.

Pipeline

raw signals / tool results
  → redact / sanitize
  → Context Packer (deterministic)
  → optional Headroom compress
  → model
  → validate / citations / rank freeze

The packer copies candidate_id, rank, and score exactly. It never invents causality. Packed JSON is validated with packedContextSchema before the model call.

What the model sees

Incident digest (id, title, window, LKG, release, mapped SHA)
Top-N candidates by existing rank
Capped evidence snippets (stack frames, paths, log lines)
Windowed timeline with omission markers
Compact JSON (no pretty-print)
Optional same-tenant agent-memory summaries on investigate only (FEATURE_AGENT_MEMORY, default off; HYPOTHESIS; never ranks)
Optional critic notes after investigate ok (FEATURE_CRITIC_LOOP, default off; HYPOTHESIS; never a re-ranker)
Optional durable investigate checkpoint (FEATURE_DURABLE_SUPERVISOR, default off): packed digest hash only — not the prompt. Resume reloads package ranks.

MCP get_evidence_package can still return the full package for humans inspecting ChangeGraph. That is not the model prompt.

Budgets

Set in the product app env (defaults are safe):

CONTEXT_MAX_TOKENS, CONTEXT_MAX_CANDIDATES, CONTEXT_MAX_STACK_FRAMES, CONTEXT_MAX_LOG_LINES, CONTEXT_MAX_PATHS, CONTEXT_MAX_TOOL_RESULT_CHARS, CONTEXT_MAX_CRITIQUE_NOTES, CONTEXT_MAX_CRITIQUE_CHARS.

Token estimate is a lightweight character approximation used to trim. It is not a billed tokenizer.

Headroom

Headroom is an optional post-pack compressor. Purpose: shrink an already redacted, already packed digest before the model call. It does not score candidates and it does not invent causality.

The packer, explain_incident, and investigate_incident all work without Headroom. Investigation still requires an LLM provider (not_configured when unset).

If you run a Headroom proxy (headroom proxy), set:

Variable	Role
`HEADROOM_URL`	Proxy base URL (alias `HEADROOM_BASE_URL`). Unset = packer only.
`HEADROOM_API_KEY`	Optional bearer for the proxy
`HEADROOM_TIMEOUT_MS`	Default 2500. Timeout / 5xx → packed prompt (`fallback: true`)

Compression runs after redaction. If the proxy is down, ChangeGraph uses the packed prompt as-is. Catalog: Open source tools.

Security

Secrets are deny-listed before packing. Production paths do not log full prompts. Recoverable compression cannot restore unsanitized tokens: the adapter sanitizes Headroom output again.