koala73 / koala73/worldmonitor

feat(mcp): surface theater-posture source attribution to agent consumers (get_military_surge)

Open
#6,093 2 comments 0 reactions 0 assignees View on GitHub
enhancement P2
Dominant language
TypeScript
Stars
86.6k
Forks
13.1k
Avg merge
8h 4m
Merged PRs (30d)
825

Description

## Summary

PR #6092 (issue #5945 residual) made theater-posture publication attribute its actual source (`opensky` / `adsb.lol` / `wingbits` / `vessel-only`) on the operator surfaces: authenticated relay `/metrics` (`theaterPosture.lastRun` + `sourceCountsSinceBoot`), `seed-meta:theater-posture` (`sourceVersion` + `producer`), and the relay log line.

The **canonical payload** written to `theater-posture:sebuf:v1` is still `{ theaters }` with no source field. `server/worldmonitor/military/v1/get-theater-posture.ts` returns it verbatim, and the MCP tool `get_military_surge` consumes it via `readCachesWithFreshness`, whose freshness envelope carries only `cached_at`/`stale`/`unavailable_inputs` — `sourceVersion` from seed-meta is discarded for every tool.

Net effect: an on-call human reading `/metrics` can discount a single-flight Wingbits-fallback posture reading; an agent calling `get_military_surge` gets the identical posture assessment with zero signal that it came from degraded single-flight fallback rather than a comprehensive OpenSky read. The #5945 misattribution risk is closed for humans but remains open one hop downstream on the only surface an LLM reasons over.

## Proposed scope

- Add `sourceVersion` (and optionally `flightCount`) alongside `theaters` in the theater-posture canonical payload (additive; both writers).
- Forward it through `get-theater-posture.ts` and surface it in `get_military_surge`'s output schema so agent consumers can flag or discount degraded-source readings.
- Respect the API-contract gates (sebuf schema, MCP parity tests, stats/docs registries) — this is why it was split out of #6092 rather than folded in.

## Acceptance

- [ ] Canonical theater-posture payload carries source attribution from both writers (relay loop + seed-military-flights).
- [ ] `get_military_surge` (and `get-theater-posture`) expose it in their response schema.
- [ ] A test proves a Wingbits-fallback cycle is distinguishable from an OpenSky cycle through the MCP tool response.

Related: #5945, PR #6092. Found by the agent-native lens during #6092's multi-agent review.

https://claude.ai/code/session_01ENW1FZgjbDCbVKBkcaLr79

Contributor guide

Open the contributing guide

Research direction

Start with server/worldmonitor/military/v1/get-theater-posture.ts and trace the theater-posture:sebuf:v1 payload through both writers into get_military_surge. Read the sebuf schema, MCP parity tests, and stats/docs registries before changing the response shape. Done means both writers preserve source attribution and a test distinguishes Wingbits fallback from OpenSky through the MCP response.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend-api-design, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.