Consume and surface provider-neutral external budget advisories

Parent

Part of #610. Complements the local list-price session estimate with a separate signal from an external budget authority.

User outcome

When a configured provider or gateway reports that a spending threshold is approaching, mecatl surfaces a clear, bounded warning without exposing deployment-specific protocol details or pretending that the advisory equals the local session estimate.

Scope

Define a provider-neutral advisory value with a minimal closed shape, for example:

level: approaching | critical
estimated: bool
observed_at
period_ends_at
source: external

The exact transport and decoding of a deployment-specific advisory remain outside the public harness core. A provider/embedding can project its signal into the neutral value.

Surface accepted advisories through:

• a typed session event;
• a bounded client-visible TUI notification;
• optional durable observability;
• an optional short harness-authored model-visible note advising against unnecessary calls/fan-out while preserving correctness and required safety work.

Deduplicate repeated advisories by a stable bounded identity such as (source, period, level/threshold) so concurrent streams do not flood the operator.

Separation from local estimates

The UI may colocate:

External budget: approaching configured threshold
This session: estimated $2.41 at known list prices

It must not calculate a remaining external balance from the local estimate. The scopes, prices, accounting delay, and concurrent activity may differ.

Security and privacy

• Accept only closed enums and bounded machine fields, never arbitrary upstream warning text.
• Do not expose payer identity, group membership, absolute shared limit/balance, credentials, or provider-private route data.
• Never concatenate external text into event framing or prompts.
• Unknown/invalid advisory data is dropped without changing model-call semantics.
• Deployments without an advisory source remain byte-identical.

Acceptance criteria

• A fake provider/embedding can supply a valid neutral advisory without a live gateway or network dependency.
• Valid advisories produce one typed event and one bounded client notification per deduplication key.
• Invalid versions/enums/timestamps, oversized data, and arbitrary text are rejected or safely ignored.
• No private transport contract or provider-specific header/event name appears in the engine API, public documentation, or generic tests.
• The TUI distinguishes an external budget advisory from mecatl's local list-price estimate.
• If model visibility is enabled, the built engine's system/turn prompt carries a tested concise behavior contract and no raw advisory data.
• Safety checks, guardrails, and already-running model streams are never silently bypassed or interrupted by an advisory.
• No-source deployments preserve existing behavior.
• Tests are fully offline.

Out of scope

• Defining a proprietary transport protocol.
• Local soft threshold policy.
• Hard budget enforcement or terminating active calls.
• Durable email/Slack/administrator notifications.
• Exposing absolute shared budget state.

Start by locating the session-event path, client TUI notification, model prompt construction, and fake provider/embedding test seams named by the issue. Done means valid advisories are safely deduplicated and surfaced, invalid or private data is ignored, local estimates remain separate, safety and active streams are unchanged, and tests run fully offline.