mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-05 10:53:59 +00:00
Merge main into PR #621 (ChatGPT OAuth for Realtime voice)
Resolve conflicts with the voice-core captions, panel resize and MCP panel key changes by keeping both sides.
This commit is contained in:
Sameh Khamis committed
commit
fb1596d2f1
244 files changed
+40846
-1558
No files matched your search
+189
-19
@@ -14,6 +14,19 @@ new views from the page that frames it; framing is off unless
|
||||
`GEV_EMBED_FRAME_ANCESTORS` allows the framing page. MCP leads with the tools that find
|
||||
what to show. See [tools and the MCP server](TOOLS.md).
|
||||
|
||||
Stdio processes from one install share the panel key in
|
||||
`.gev-cache/mcp-panel-key`, resolved from the checkout rather than the client's
|
||||
working directory. First creation is atomic; malformed-file repairs select one
|
||||
winner and concurrent processes re-read it. A busy repair waits at most two
|
||||
seconds before falling back. If the cache cannot be read/written or repair remains
|
||||
busy, stderr reports the fallback to a per-process key; cross-process panels can
|
||||
still fail in that mode. An abandoned `.repair-lock` is left intact: after
|
||||
confirming no repair process is running, remove it to allow repair on restart.
|
||||
HTTP MCP servers retain per-server keys. This key is a panel routing guard, not
|
||||
authentication. Large-response continuations remain process-local and require
|
||||
consistent tool-call routing. Two-process reproduction is covered locally;
|
||||
Windows/Claude Desktop Cowork confirmation remains outstanding (#927).
|
||||
|
||||
## Tools and local MCP server — October 1, 2026
|
||||
|
||||
`gods-eye-view/tools` defines queries that answer questions from the app's data,
|
||||
@@ -278,7 +291,7 @@ Consult the linked official advisory for safety decisions.
|
||||
|
||||
Voice and HUD snapshots reuse the existing feedState classifier. Analyst follow-ups retain their original data provenance; current-view results append provenance without replacing legacy fields. HUD context and deterministic telemetry include non-nominal feed state.
|
||||
|
||||
Satellite and local infrastructure layers expose on-demand analyst records through their current factory owners. Analyst counts and ranks explicitly cover only bounded examined loaded records (default 2,000 per new layer, core satellite rows before dense extras); omitted records can change nearest/count and satellite distance is ground distance. Existing tools and result fields remain available.
|
||||
Analyst records come on demand from each layer's `getAnalystRecords`: flights, military, local ADS-B, vessels, satellites, launches, earthquakes, FIRMS (VIIRS and MODIS, with a `sensor` field), fire perimeters, cyclones, transit, bikeshare, ALPR cameras, mapped installations, datacenters and dams. `analyst_query` counts the whole loaded set (up to 250,000 records per layer; past that `coverage.records` reports `returned`, `total` and `truncated: true` and the result carries `complete: false`). Ranking keeps a top-k and scans in 20,000-row slices that yield to the page and stop when superseded. It refuses unknown fields, operators, units that do not convert (`altitudeM(ft)` converts), wrong-typed values, invalid centres, unknown scope kinds and sort fields with `code` and `allowed`, refuses a follow-up with no previous answer (`NO_RESULT_CONTEXT`) or naming other layers than that answer (`FOLLOW_UP_MISMATCH`), and tells `LAYER_OFF`, `NOT_READY` and `FEED_UNAVAILABLE` apart from a real zero; when only some layers can answer the result is `partial` with `unanswered` ids. The Contacts-window path applies the same filters, ranking and item shape to one immutable panel snapshot. Each aircraft layer retains at most 20,000 rows; reaching that bound sets `complete: false` and the spoken/card count becomes “At least”, never an exact claim. A superseded query never replaces follow-up memory, while sibling analyst calls from one assistant response do not cancel one another. Items carry `lat`/`lon`; the feed window (earthquakes and FIRMS: last 24 h), the precise scope and any caveat sit in `display`, which is on-screen detail rather than something the model recites. "In view" is still a radius around the view centre, not the visible footprint. Satellite distance is ground distance.
|
||||
|
||||
Keyless terrain tiles retry when Re:Earth throttles them. The browser fetches
|
||||
`terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain` directly; no
|
||||
@@ -353,6 +366,70 @@ replacement session; audio meters release failed initialization and reject revok
|
||||
frames. Delayed action results and post-capture continuations cannot resume a
|
||||
stopped conversation or send output into a replacement. See [voice ownership](VOICE-OWNERSHIP.md).
|
||||
|
||||
Contacts nearest-aircraft follow-ups retain the snapshot's distance basis even
|
||||
after the camera moves. An explicit new scope replaces that basis. Provider
|
||||
instructions require an analyst query for requested lists and use the requested
|
||||
radius rather than substituting the panel's fixed window. Analyst speech carries
|
||||
stale/degraded feed status and does not speak an authoritative unavailable count.
|
||||
The existing NOTES disclosure deduplicates coverage/source caveats and retains
|
||||
their full text in at most six rows, grouping analyst overflow in the final row;
|
||||
ordinary tool-card limits are unchanged.
|
||||
|
||||
Voice speech: `src/voice/speech.js` adds `{ say, display, referents?, schedule? }`
|
||||
to layer toggles, fly_to_location, frame_overhead, select_nearest_aircraft,
|
||||
get_entity_context, annotate_map and analyst_query. Analyst speech and the card
|
||||
share one deterministic count/scope headline; lower bounds use "At least" and
|
||||
partial answers name the unanswered layers. `get_current_view_state` lists enabled layers only.
|
||||
The voice card nested in the mic control (`voiceCard.js`) shows captions, plan
|
||||
steps and the result. `resultDisplay.js` is the one adapter from a result to
|
||||
the card: builder results show as built, and analyst results show a title
|
||||
with their scope, window and caveats. Caveats are on the card; the model speaks
|
||||
one only when it changes the answer, and always says lower bounds and partial
|
||||
answers. `narration.js` speaks one
|
||||
code-authored line for the current step of a tool still running at 1.5 s
|
||||
(out of band, never after the result). Tools that report steps: layer
|
||||
toggles, place lookups, select_nearest_aircraft and annotate_map (finding,
|
||||
outlining). Other tools get one "still working" line at 8 s. The
|
||||
earcon plays in push-to-talk only. A claimed Space hold while the assistant
|
||||
speaks is a barge-in (WebRTC cancel + audio clear), refused while Radio holds
|
||||
the speaker (`mayVoiceClaimSpeaker()`). Progress lines stay outside the reply
|
||||
lifecycle and Radio handoff. `turn.span` debug records carry generation and
|
||||
playback latency, silence, preamble and word-count figures. Caption
|
||||
transcription (`OPENAI_REALTIME_TRANSCRIBE_MODEL`, default on) is metered into
|
||||
the session cost and cap. The debug log omits transcripts, text, tool arguments
|
||||
and complete tool-result bodies (including serialized function outputs) unless
|
||||
`GEV_VOICE_LOG_CONTENT=1`.
|
||||
Tool names, call IDs, protocol event metadata and usage remain available.
|
||||
Numbered analyst targets resolve from current layer records, including layers
|
||||
without pick/context lookup; numbered annotations retain their resolved coordinates.
|
||||
Requested analyst lists and rankings may speak up to three returned items and
|
||||
values in result order alongside the count and its caveats. A rejected current
|
||||
action emits a failure result to settle its card; cancelled turns remain silent.
|
||||
Coverage grading validates calls before accepting an expected capability match.
|
||||
The voice manifest includes Street Level visibility toggles; its imagery has no
|
||||
analyst query or entity-context records.
|
||||
|
||||
Point and ask: `pointerContext.js` reads what the cursor is on. A Space hold
|
||||
is the pointing gesture: its keydown snapshot (released with the key) is sent
|
||||
as an inert `pointer_context` item with the target, with reticle and chip.
|
||||
Open-mic speech and typed turns count only a pointer that moved on the map in
|
||||
the last 5 s and send only the kind (`pointing:"aircraft"`/`"ground"`); the chip appears when a tool
|
||||
resolves it. Losing the pointer sends one `target:"none"` item. `deixis.js` resolves `'pointer'` in
|
||||
track_entity/fly_to_location queries, get_entity_context scope, analyst_query
|
||||
`scope.kind` and annotate_map targets, plus `referent:n` from the latest
|
||||
numbered result (`referents.js`, cleared at session end). A new result set (an analyst count) replaces
|
||||
the numbered list even when it is empty. Only the five rows numbered on the
|
||||
card are resolvable; `-1` means the fifth/last visible row. `track_entity`
|
||||
accepts either a named query or a referent, while an empty target is rejected. A reticle marks the
|
||||
point during the turn and the voice card shows "THIS"/"HERE"; both hide in
|
||||
Clean-UI and recording. A ground-only pointer lookup at local/city scale sends a ringed 512 px crop in
|
||||
the one retained image slot, dropped if the camera moved or a newer capture or
|
||||
turn started. The pointer path makes at most two bounded fresh-frame requests so
|
||||
a slow render loop can recover without accepting a stale frame; a missing camera
|
||||
identity, expired snapshot, invalid geometry, black frame or oversized payload
|
||||
still fails closed. screenX/screenY against the crop are mapped back to the canvas. Harness: `qa-voice-routing.mjs --layer deixis`,
|
||||
`--layer deixis-live`, `--layer behavior --deixis-only`.
|
||||
|
||||
The application shell composes focused state owners for navigation, destination
|
||||
lookup/orbit, Cockpit, visual settings, panel layout, aircraft display and layer
|
||||
bindings. Keyboard/display subscriptions have a separate lifetime; existing
|
||||
@@ -419,9 +496,11 @@ Reference feed construction is exported through `sources/reference`; the cable s
|
||||
|
||||
Source factories have dedicated `layers/<family>/source` exports. ALPR and earthquake record normalization and CCTV source policy no longer pull rendering into source consumers. Catalog construction and voice feed reads use their focused owners; compatibility entries remain available. Settings filesystem hardening lives under `server/standalone/`. Import-direction checks complement export ownership checks; source behavior, settings policy and rendering are unchanged.
|
||||
|
||||
Voice controls bind to a protocol-independent session factory. The default WebRTC adapter preserves the existing Realtime connection, push-to-talk, cost controls and radio handoff. Session subscriptions expose state, transcript, action call/result, interruption and completion events; stopping or replacing a session cancels pending actions. Alternate adapters can use the same controls and action runner.
|
||||
Voice controls bind to a protocol-independent session factory. The default WebRTC adapter preserves the existing Realtime connection, push-to-talk, cost controls and radio handoff. Session subscriptions expose state, transcript, action call/progress/result, interruption, completion and turn-metrics events; stopping or replacing a session cancels pending actions. Alternate adapters can use the same controls and action runner.
|
||||
|
||||
Voice action argument schemas have one portable owner under `src/voice/actionSchemas.js`. The Realtime provider builds 29 tools, retaining the existing 28 names and argument contracts apart from the three additive analyst-layer enum values using separate description-only metadata. Description customization cannot replace argument types, enum values or required fields.
|
||||
Voice action argument schemas have one portable owner under `src/voice/actionSchemas.js`. The Realtime provider builds 30 tools using separate description-only metadata. Description customization cannot replace argument types, enum values or required fields.
|
||||
|
||||
`src/voice/layerManifest.js` declares each catalog layer's voice capabilities: spoken aliases, `toggle`, in-view `context`, `track`, and analyst `query` fields with type and unit, or `noQuery` with the reason. The `set_layer_visibility`, `show_data_layers_menu`, `get_entity_context` and `analyst_query` layer enums, the runner's alias table and the analyst field hints are generated from it. `src/voice/layerManifest.test.mjs` fails when a catalog layer is neither listed nor named in `VOICE_OFF_LAYERS` (today only the two scene-driven Bhote Koshi layers). Global Context is listed with `toggle: false`; `set_context_mode` reaches it. `set_panel_open` also opens `weather-panel` and `recent-imagery-panel`.
|
||||
|
||||
Portable source exports provide Radio Browser station normalization, CCTV feed types and regional records independently of HTTP middleware. Radio normalization accepts an explicit URL policy; the standalone directory retains its existing HTTPS rules. Tile coordinate validation accepts explicit zoom bounds with unchanged traffic defaults. Cache, request and rendering owners remain unchanged.
|
||||
|
||||
@@ -464,7 +543,18 @@ clears caches and removes map-stack listeners. Standalone setup supplies the
|
||||
existing service clients. HUD summaries, regional brief, cockpit weather, location
|
||||
framing and annotation boundaries receive their service instances explicitly.
|
||||
Compatibility entrypoints retain defaults for direct callers; normal startup does
|
||||
not change global service slots. Analyst follow-up memory belongs to its voice runner.
|
||||
not change global service slots. Analyst follow-up memory belongs to its voice
|
||||
runner and ends with the voice session: stopping voice invalidates writes still in
|
||||
flight and forgets the last answer, the pointer and the numbered list; removing
|
||||
voice disposes the runner.
|
||||
|
||||
Analyst result memory is committed only after any Contacts-window projection
|
||||
finishes and the call is still current. Cancelled or superseded queries cannot
|
||||
return success or replace follow-up memory; Contacts follow-ups filter the same
|
||||
cohort that was shown, and partial/unanswered coverage remains attached when a
|
||||
remembered result is narrowed.
|
||||
The narrowed answer retains the remembered scope label and detail, including
|
||||
the Contacts-window attribution, unless the follow-up supplies a new scope.
|
||||
|
||||
Application startup constructs fresh layer instances from explicit source objects.
|
||||
Standalone composition selects the existing providers. Controls, launch orbit
|
||||
@@ -1474,10 +1564,10 @@ This is the current runtime/source-of-truth snapshot for the project.
|
||||
> samples, `enabling` throughout, panel non-numeric) and across a failing
|
||||
> one. Its `status: 'idle'` is not what saves it — the lifecycle is; the
|
||||
> module has no `loading` status at all.
|
||||
> Any new dependency that can be slow must report `loading` and `lastUpdate`
|
||||
> honestly for the contract to hold, and must be pinned against the shape its
|
||||
> own module really returns — a fixture that invents a status the module cannot
|
||||
> emit guards nothing (that is exactly how a hole here survived a green suite).
|
||||
> Any new dependency that can be slow must report `loading` and `lastUpdate`
|
||||
> honestly for the contract to hold, and must be pinned against the shape its
|
||||
> own module really returns — a fixture that invents a status the module cannot
|
||||
> emit guards nothing (that is exactly how a hole here survived a green suite).
|
||||
> - **A held ground snap is dropped when measured ground contradicts it
|
||||
> (2026-08-23):** the WARM hold described below answers on DISTANCE travelled,
|
||||
> which is only a proxy for whether the value still describes the ground. A
|
||||
@@ -2872,7 +2962,7 @@ test:track` 43 tracking invariants · headless QA harnesses under
|
||||
> ISS pass prediction, and per-layer data attribution. Gate at close: unit 98/98, build clean,
|
||||
> track 19/19, + five QA harnesses (heading 16/16, sprites 9/9, cctv 5/5, failstate 5/5,
|
||||
> attribution 18/18). New modules: `src/data/{motionModel,aircraftMeta,aircraftClass,aircraftIcons,issPass,routePlausible,dataCredits}.js`.
|
||||
> The live runtime now declares 29 voice tools; the 17→20 count above is retained only as milestone history.
|
||||
> The live runtime now declares 30 voice tools; the 17→20 count above is retained only as milestone history.
|
||||
|
||||
## Canonical Docs Order
|
||||
|
||||
@@ -2928,11 +3018,79 @@ its criteria cannot be silently ignored.
|
||||
| Dams ▰ | OpenInfraMap/OSM extract (bundled) | `src/data/localLayers.js` | — | static |
|
||||
| Submarine Cables ◠ | TeleGeography public map (bundled) | `src/data/telegeographySubmarineCables.js` | — | static |
|
||||
| FIRMS Active Fires ▲ | NASA FIRMS live (VIIRS ×3 NRT + MODIS NRT, trailing 24h) | `src/data/firmsHeatmap.js` | `/api/firms` (`FIRMS_MAP_KEY`) | 10 min (proxy TTL 30 min) |
|
||||
| Street Level 📷 | Street-level imagery; Mapillary is the first provider (vector tiles, Graph API, MapillaryJS) | `src/layers/streetLevel/` via `src/app/layers/streetLevel.js` | `/api/mapillary/status`, `/api/mapillary/tiles/coverage/{z}/{x}/{y}` (`MAPILLARY_CLIENT_TOKEN`) | camera-driven (320 ms debounce, ≤9 tiles, cached 24 h) |
|
||||
| Wind 🌬 | NOAA GFS 10 m wind (keyless, 0.25°→1° grid; animated particles) | `src/data/wind.js` | `/api/wind` | 1 h (forecast cycle) |
|
||||
| Fire Perimeters 🔥 | NIFC WFIGS current interagency perimeters (keyless, paged past the 2000-record cap); InciWeb catalog + incident page origin and update time checks for verified incident-page links | `src/layers/perimeters/` via `src/app/layers/perimeters.js` | `/api/fire-perimeters` + `/api/fire-perimeters/inciweb/*` | 5 min (server caches: catalog 1 h; publication 30 min) |
|
||||
|
||||
Fire Perimeters uses capped, timed server reads with stale-on-error caching and a per-client limit. Unchanged snapshots retain geometry; link checks cancel on disable or selection change, and the row legend shows reported containment.
|
||||
|
||||
Street Level is a collapsible right-rail panel (`#street-level-panel`, layer
|
||||
token `0`, option owner `street-level`, panel `ui` token `t`) that starts
|
||||
collapsed. It opens itself only when the user, voice or a tool switches the
|
||||
layer on or a photo opens, never on a restore, and those opens are not stored.
|
||||
Like the iD editor's photo overlay, it has one chip per registered provider,
|
||||
shared 360°/flat and captured-since filters (relative days, so a link keeps its
|
||||
meaning), one viewer host and one on-globe credit per active provider. Each
|
||||
provider draws in one colour (`PROVIDER_COLORS` in
|
||||
`src/layers/streetLevel/policy.js`); 360° cones are rings and the selected
|
||||
sequence is GEV cyan. Share options: `m` (Mapillary), `p` (`a`/`p`/`f`
|
||||
panoramas), `s` (since, days). Only Mapillary is registered. Without
|
||||
`MAPILLARY_CLIENT_TOKEN` the panel reads KEY REQUIRED and the controls are
|
||||
disabled. With it, coverage draws as z0–5 overview points from orbit and z11–14
|
||||
sequence lines below 60 km; the proxy strips the unused `image` layer from z14
|
||||
tiles (12 MB → ~80 KB) and shares one upstream fetch between concurrent
|
||||
requests for a tile.
|
||||
|
||||
On Google 3D (`photoreal`) at street zoom (in below 1,400 m above ground, out
|
||||
above 1,800 m) the surface mode switches from `draped` to `terrain`: draped
|
||||
lines land on roofs and tree tops, so `groundCast.js` instead places lines,
|
||||
cones and the marker 2 m above the bare earth from `/api/terrain/heights`, and
|
||||
the mesh hides what is behind buildings and trees. A tile is drawn draped until
|
||||
its heights arrive; a geoid fallback leaves it draped. Within 900 m of the
|
||||
camera, `meshSampler.js` samples the rendered surface (`scene.sampleHeight`,
|
||||
~11 m cells, nearest first, 6 ms idle budget) so lines also follow trenches,
|
||||
steep streets and roads under trees. It uses the mesh floor's rules (the
|
||||
visible tileset has finished streaming, a real bare-earth prior, the shared
|
||||
mesh window) and probes a cell again once the camera is half as far from it,
|
||||
down to 40 m, so coarse early samples are replaced as finer tiles load. A
|
||||
failed probe keeps the last good sample and distance and is retried after the
|
||||
miss cooldown. Roads on elevated decks are still drawn at
|
||||
ground level. Framing a photo ignores mesh samples far below the bare earth
|
||||
(unloaded tiles).
|
||||
|
||||
The header pill is the layer switch. With one provider its chip is a layer
|
||||
switch too; with several, darkening the last lit chip turns the layer off. The
|
||||
viewer sits under the header with EXPAND, FIT/FILL, FOLLOW and close above the
|
||||
image. FOLLOW needs the Google 3D map stack (`attachMapStackController`) and
|
||||
stops when the stack changes. Camera moves go through the application's
|
||||
navigation (`attachNavigation`), which releases aircraft and satellite tracking
|
||||
and is refused in the cockpit: turning FOLLOW on claims the camera at once, and
|
||||
FOLLOW stops when another feature takes it; a photo takes a deferred ticket
|
||||
when it starts opening and frames only if nothing newer took the camera while
|
||||
it loaded. SINCE is a stepped slider whose readout names the
|
||||
cut-off date. The panel is portable (`street-level-panel` spec, minimum
|
||||
320 × 280, `dockOnCollapse`): a floating window gives spare height to the
|
||||
viewer, and collapsing it, double-clicking the header or SHRINK after EXPAND
|
||||
docks it. At phone width (≤720 px) the viewer height is derived from the rail
|
||||
band so the whole photo fits.
|
||||
|
||||
Providers implement the contract in `src/layers/streetLevel/registry.js`. The
|
||||
core routes clicks by pick prefix, swaps viewer adapters in the one host,
|
||||
manages each provider's credit and fans the filter out to every provider. To
|
||||
add a provider: implement the definition, register it in
|
||||
`src/app/layers/streetLevel.js`, add its boolean option to the `street-level`
|
||||
group in `src/data/layerState.js` and its modules to
|
||||
`scripts/package-boundaries.json`. Once a keyless provider registers, the
|
||||
layer's `requiresKeyId` becomes null and the key gate moves to the chips.
|
||||
|
||||
Street Level has two browser gates. `npm run qa:street-level -- --url <server>`
|
||||
runs against real Mapillary and needs `MAPILLARY_CLIENT_TOKEN`. `npm run
|
||||
qa:street-level:fixtures -- --url <server>` answers every Mapillary request
|
||||
from fixtures (`providers/mapillary/coverageFixture.mjs`,
|
||||
`scripts/fixtures/street-level/`), so it needs no network and covers the whole
|
||||
photo flow. CI runs the fixture gate and `qa:panel-resize`
|
||||
against a production build served by `vite preview` with a dummy token.
|
||||
|
||||
Directions is a keyless front end to the routing the voice agent already
|
||||
uses. Its row chips are the whole interface: DRIVE / WALK / BIKE pick the
|
||||
profile; SET A and SET B arm the next globe click (Escape or a second press
|
||||
@@ -3753,10 +3911,10 @@ and unreachable upstream (502/504) separately from road geometry.
|
||||
block its siblings.
|
||||
- Layer tokens are permanent public compatibility identifiers. The reservation
|
||||
JSON ledger at `src/data/layerStateTokenReservations.json` pins all existing
|
||||
one-character assignments (all letters plus `1` and
|
||||
one-character assignments (all letters plus `0`, `1` and
|
||||
`2` on current `main`) even if a layer is later removed. New layers allocate
|
||||
the remaining unreserved single-character digits first (`0`, then `3`
|
||||
through `9` on current `main`), then the next unreserved two-character
|
||||
the remaining unreserved single-character digits first (`3` through `9` on
|
||||
current `main`), then the next unreserved two-character
|
||||
base-36 token (`00` through `zz`) after rebasing onto the merge-time `main`;
|
||||
the dot-delimited v2 codec accepts both widths without changing existing
|
||||
links or the schema version. The contributor
|
||||
@@ -3879,7 +4037,7 @@ and unreachable upstream (502/504) separately from road geometry.
|
||||
|
||||
- **Token flow**: browser fetches a short-lived client secret from `/api/realtime/token`; the Vite middleware uses `OPENAI_API_KEY` by default, or the signed-in local ChatGPT/Codex OAuth access token when OAuth was explicitly selected in Provider Settings, and posts the full session config (instructions, tool schemas, VAD, truncation) to `api.openai.com/v1/realtime/client_secrets`. Both long-lived credentials stay server-side; OAuth minting is loopback-only. SDP exchange goes directly to `api.openai.com/v1/realtime/calls` with the ephemeral token.
|
||||
- **Session defaults** (env-tunable): model `gpt-realtime-2` (or `gpt-realtime-2.1-mini` when the MINI tier is selected — see the model-tier entry below), voice `marin`, reasoning effort `low`, semantic VAD with low eagerness, no response interruption, context window truncated to ~3,000 post-instruction tokens with 0.5 retention ratio — the conversational window stays short because map state is fetched live per turn.
|
||||
- **Twenty-nine tools** (argument schemas in `src/voice/actionSchemas.js`, served with their descriptions by `server/providers/openai/tools.js`, executed client-side in `src/voice/gevActions.js`): `fly_to_location`, `select_nearest_aircraft`, `adjust_camera_zoom`, `zoom_to_globe`, `set_layer_visibility`, `show_data_layers_menu`, `set_panel_open`, `set_visual_style`, `get_entity_context`, `get_current_view_state`, `set_hud`, `set_detection`, `set_map_stack`, `set_post_processing`, `control_scene`, `control_cctv`, `set_context_mode`, `control_cockpit`, `control_radio`, `track_entity`, `stop_tracking`, `frame_overhead`, `annotate_map`, `clear_annotations`, `move_camera`, `fly_route`, `analyst_query`, `next_iss_pass`, and `next_satellite_pass`.
|
||||
- **Thirty tools** (argument schemas in `src/voice/actionSchemas.js`, served with their descriptions by `server/providers/openai/tools.js`, executed client-side in `src/voice/gevActions.js`): `fly_to_location`, `select_nearest_aircraft`, `adjust_camera_zoom`, `zoom_to_globe`, `set_layer_visibility`, `show_data_layers_menu`, `set_panel_open`, `set_visual_style`, `get_entity_context`, `get_current_view_state`, `set_hud`, `set_cyber_sonar`, `set_detection`, `set_map_stack`, `set_post_processing`, `control_scene`, `control_cctv`, `set_context_mode`, `control_cockpit`, `control_radio`, `track_entity`, `stop_tracking`, `frame_overhead`, `annotate_map`, `clear_annotations`, `move_camera`, `fly_route`, `analyst_query`, `next_iss_pass`, and `next_satellite_pass`.
|
||||
|
||||
> **Reading `npm test` totals:** the count depends on the Node major. The two
|
||||
> GC-bracketed allocation microbenchmarks (`src/data/focusAllocations.test.mjs`
|
||||
@@ -3901,7 +4059,7 @@ and unreachable upstream (502/504) separately from road geometry.
|
||||
- **Analyst → track handoff carries a key, not just a label** (2026-08-21). `analyst_query` items include `icao24`/`mmsi` alongside the display `id`, and contact lookup uses the shared tiered ranking in `src/data/contactMatch.js`: hex exact → callsign exact → registration exact → callsign prefix → registration prefix → callsign substring → registration substring. The tiers keep an exact callsign ahead of a colliding registration regardless of feed order, and registrations compare separator-insensitively (`G-ABCD`/`GABCD`, `05-8152`/`058152`, `N123AB`/`N-123AB`).
|
||||
- **A typed command supersedes the turn it interrupts** (2026-08-21). `sendTextCommand` defers its `response.create` behind an active response instead of colliding with it, marks that response superseded so a late function call from it is refused rather than dispatched, and drops the old turn's queued follow-up. A refused call is still ANSWERED — a terminal `{ok:false, superseded:true}` `function_call_output` — because an unanswered `function_call` strands a pending call and deadlocks the model; the refusal creates no response of its own. A burst of typed commands coalesces into one response while keeping both conversation items.
|
||||
- **Subject reconciliation across satellite catalog rebuilds** (2026-08-21). A dense↔core toggle or TLE refresh clears and repopulates the catalog, so the published subject is re-resolved against the new satrec; a subject that did NOT survive releases the slot. The per-frame refresh cannot do this itself — `_getTrackedFramePosition` returns early once the satellite has no catalog entry — so the reconcile runs at rebuild completion. An empty catalog is a rebuild in flight, not a disappearance.
|
||||
- **One aircraft-proximity engine** (2026-08-22). `collectAircraftProximityWindow` (`src/data/militaryAwareness.js`) is the single computation behind both the Contacts panel window and the voice analyst's entity-centred "how many nearby", so the panel readout and the spoken count for one centre are identical by construction. **Invariant: do not re-derive a proximity count anywhere else.** They diverged before because the panel read live billboard positions (20,000 cap) while the analyst used last-fix coordinates over a 2,000-record slice — 111 on screen, 15 spoken. Explicit regions and arbitrary points deliberately keep the general record engine. Entity-centred results carry `window: {engine:'contacts-window', centeredOn, radiusKm, flights, military, aircraft}`.
|
||||
- **One aircraft-proximity snapshot** (2026-08-22; hardened 2026-09-30). `collectAircraftProximityWindow` (`src/data/militaryAwareness.js`) computes the Contacts panel cohort once. The voice analyst reads the exact retained snapshot and evaluation timestamp instead of re-scanning live layers, so the panel readout and spoken count for one centre cannot cross snapshots. **Invariant: do not re-derive a proximity count anywhere else.** Each layer retains 20,000 rows and samples one row beyond the cap; a saturated cohort reports `complete:false`, `truncated:true`, and is spoken as a lower bound. They diverged before because the panel read live billboard positions while the analyst used last-fix coordinates over a 2,000-record slice — 111 on screen, 15 spoken. Explicit regions, arbitrary points, and a radius different from the panel radius deliberately keep the general record engine. Entity-centred results carry `window: {engine:'contacts-window', centeredOn, radiusKm, flights, military, aircraft, complete, evaluatedAt}`.
|
||||
- **Centre precedence for nearby asks**: explicit place in the question > Contacts subject (a selected non-contact entity never silently becomes the centre) > an entity the user names > the current view, said aloud. Contacts active with no subject uses the view rather than reading an empty panel.
|
||||
- **Contact-match ties break on hex ascending.** `track_entity` is a mutation fulfilling "follow that one", and the model's observed answer to a non-ok track result is to retry with guesses rather than ask, so the lookup always commits rather than returning an ambiguity. What it owes the caller is stability: hex is unique and always present, so the same query resolves to the same contact for as long as both are loaded.
|
||||
- **Visual grounding**: at `local` view scale with no structured identity, the client captures the Cesium canvas (≤1200px JPEG, black-frame detection, double-render for freshness) and sends it as `input_image` with a strict "do not invent labels" instruction.
|
||||
@@ -3918,8 +4076,8 @@ and unreachable upstream (502/504) separately from road geometry.
|
||||
- **Reliability**: tool-call dedupe (2.5s window across call/item/args keys); response-create queueing that respects active responses and defers follow-ups when the user starts speaking; per-tool follow-up instructions so the agent confirms only what actually happened (zoom confirms only on `ok=true`).
|
||||
- **Aircraft identity honesty:** “What is this aircraft?” reads callsign, operator, registration, type, and route only from the selected contact context. Missing operator, route, or type enrichment is named explicitly rather than silently omitted or inferred from the callsign.
|
||||
- **Diagnostics**: every client/server event is posted to `/api/realtime/debug-log` and appended to `.gev-logs/realtime-conversations.jsonl` (gitignored) with secret/image redaction; last 30 errors persist in `localStorage` (`gev-realtime-errors`); `window.__gevVoiceCommands.getDiagnostics()` in the console.
|
||||
- **Counting semantics ("near")** — a CONTRACT; new count-bearing tool work inherits it. Three honest numbers exist for one question: the Contacts cohort (250 km around the subject, what the panel shows), `analyst_query`'s count of _currently-loaded_ records for the requested scope, and the layer-wide loaded total in `coverage.layersQueried[].records`. They diverge legitimately — the flights layer loads by viewport, so after a camera dive the loaded set can hold a fraction of the cohort (field case: panel 42, analyst 8). The contract:
|
||||
1. **Contacts ACTIVE** → "near / nearby / how many aircraft" means the **Contacts window** — the panel's numbers, spoken verbatim. Mechanism: `contactsWindow` (`{centeredOn, radiusKm, flights, military, vessels}`), carried by both `analyst_query` and `get_current_view_state`, derived by `contactsWindowFromSnapshot()` from the same snapshot the panel renders so the two cannot drift. A cohort whose feed cannot answer reports `'unknown'`, never a confident zero.
|
||||
- **Counting semantics ("near")** — a CONTRACT; new count-bearing tool work inherits it. Three honest numbers exist for one question: the Contacts cohort (250 km around the subject, what the panel shows), `analyst_query`'s count of _currently-loaded_ records for the requested scope, and the layer-wide loaded total in `coverage.layersQueried[].total`. They diverge legitimately — the flights layer loads by viewport, so after a camera dive the loaded set can hold a fraction of the cohort (field case: panel 42, analyst 8). The contract:
|
||||
1. **Contacts ACTIVE** → "near / nearby / how many aircraft" means the **Contacts window** — the panel's numbers, spoken verbatim. Mechanism: `contactsWindow` (`{centeredOn, radiusKm, flights, military, vessels, complete}`), carried by both `analyst_query` and `get_current_view_state`, derived by `contactsWindowFromSnapshot()` from the same snapshot the panel renders so the two cannot drift. Voice filtering and follow-up memory use that immutable snapshot too. A cohort whose feed cannot answer reports `'unknown'`, never a confident zero; a cohort at the 20,000-row retention bound reports a lower bound.
|
||||
2. **Contacts OFF** → "nearby" means **in view**; "near \<place\>" means a radius around that place. A radius query with Contacts active and no explicit centre is centred on the **active contact**, not the camera.
|
||||
3. **Every count names its scope in words** — "42 in your window", "8 in view", "about 30 within 250 km of Austin" — never a bare number. `analyst_query` returns `scopeLabel` so this is mechanical. Two different numbers with named scopes are not a contradiction.
|
||||
4. **The loaded-data caveat is stated once when relevant**: counts cover loaded data, and the flights layer loads where you look (appended to `coverage.note` for radius/view scopes over viewport-loaded layers).
|
||||
@@ -3995,6 +4153,15 @@ are omitted rather than framing the wrong part of the globe.
|
||||
retrying. Missing capability never synthesizes an outline from a radius.
|
||||
Manual geometry, bundled neighborhoods, Natural Earth regions and bundled
|
||||
state/province/county outlines remain.
|
||||
- The shared default place search resolves unqualified `Alps`, `the Alps`
|
||||
and the `Alps mountains` forms from the bundled European Natural Earth
|
||||
range before network geocoders. Navigation uses its contained anchor and
|
||||
region viewport; annotations still require the existing proximity and
|
||||
outline-containment checks. Coordinates and supplied presets keep priority;
|
||||
geographic qualifiers, local POI names, other ranges and custom geocoder
|
||||
arrays retain their existing resolution. A failed Alps pack load reports a
|
||||
search failure rather than caching an unrelated peak as the range, and the
|
||||
bundled loader retains its normal retry cooldown.
|
||||
- County queries rank eligible US counties and international admin-1 units together, retaining exact aliases and country/state qualifiers.
|
||||
- Bundled administrative outlines (`src/data/adminBoundaries.js`): states and
|
||||
provinces worldwide (Natural Earth admin-1,
|
||||
@@ -4364,8 +4531,8 @@ easier to meet (detection is now on more often), but does not create it.
|
||||
samples and constant elevation during E/N drag; one shared-floor resolution on
|
||||
release; late one-shot shared-cell work is permitted during viewshed idle. The
|
||||
A+B harness intentionally excludes citywide LOD assertions.
|
||||
- Panel positions have a versioned storage name, `godsEyeView.v8.panelPos.<panel-id>`, but the current rails lay panels out adaptively and write none. Collapsed state does persist for every panel at `godsEyeView.v6.panelCollapsed.<panel-id>` (`'0'` open, `'1'` closed, absent means the panel's own default).
|
||||
- Legacy draggable-panel position keys may remain in local storage for backward compatibility, but the map-mode right rail ignores them; collapsed states still persist at `godsEyeView.v6.panelCollapsed.<panel-id>`.
|
||||
- Panel positions have a versioned storage name, `godsEyeView.v8.panelPos.<panel-id>`. Docked panels store nothing; a portable panel (CCTV, Street Level) stores `{ left, top, width, height, floating: true }` once a header drag lifts it out of the rail, and a header double-click removes it. Double presses are detected in the header's `pointerdown` handler, because its `preventDefault()` suppresses native `dblclick`. Collapsed state persists for every panel at `godsEyeView.v6.panelCollapsed.<panel-id>` (`'0'` open, `'1'` closed, absent means the panel's own default).
|
||||
- Legacy draggable-panel position keys may remain in local storage for backward compatibility, but the map-mode right rail ignores them unless they describe a portable panel's floating window; collapsed states still persist at `godsEyeView.v6.panelCollapsed.<panel-id>`.
|
||||
- Flight/military tracked entities cache dead-reckoned positions per frame to avoid callback desync flicker.
|
||||
- Aircraft 3D-model and tracking invariants are covered by `npm run test:track`; run this before touching `flights.js`, `militaryFlights.js`, `detection.js`, or `trackedReadout.js`.
|
||||
- Annotation resolver behavior is pinned by `src/annotations/annotationResolver.test.mjs`; re-run that suite before changing place-resolution scoring.
|
||||
@@ -4540,6 +4707,10 @@ easier to meet (detection is now on more often), but does not create it.
|
||||
shown dot against the allowed source classes and records phase timings.
|
||||
Positions and segment distances are precomputed, with no new animation-loop
|
||||
allocation. Visible-globe roads use cached terrain without offscreen mesh picks. The road-source label names the geometry being drawn, with partial/unavailable states shown plainly.
|
||||
- Vector tile sources accept tiles only from an allowed origin, which defaults
|
||||
to the configured `tileJsonUrl` origin; an explicit `allowedOrigin` overrides
|
||||
it. Repointing only `tileJsonUrl` loads tiles from that host or fails with an
|
||||
origin error rather than silently falling back to OpenFreeMap.
|
||||
- TileJSON caches successful metadata. Transient failures retry after a
|
||||
five-second cooldown; invalid metadata/origins stay unavailable until the
|
||||
source is cleared. Clear resets metadata and cancels pending requests.
|
||||
@@ -4857,7 +5028,6 @@ Temperature uses stronger fixed −40..50°C colors; the underlying 1° forecast
|
||||
numeric inspection values are unchanged. No volumetric cloud height or local rain
|
||||
arrival prediction is claimed. NOAA source limits are documented in DATA_SOURCES.
|
||||
|
||||
|
||||
Traffic source refinements: ALPR admits z9-z12 detail only when the view fits 16 tiles,
|
||||
returning explicit zoom guidance before I/O and allowing the next smaller view to
|
||||
load normally. Outside the US/Canada extracts the row reads “No ALPR data for this
|
||||
|
||||
@@ -57,9 +57,9 @@ Related keys (current versions):
|
||||
- Panel collapsed state: `godsEyeView.v6.panelCollapsed.<panel-id>` — `'0'` open,
|
||||
`'1'` closed, absent means the panel's own default. A view opened from a share
|
||||
link ignores the stored value entirely.
|
||||
- Panel positions: `godsEyeView.v8.panelPos.<panel-id>` — the versioned name for a
|
||||
stored position. The current layout writes none, so deleting one changes
|
||||
nothing.
|
||||
- Panel positions: `godsEyeView.v8.panelPos.<panel-id>` — written only for a
|
||||
floating portable panel (CCTV, Street Level). Deleting it, or double-clicking
|
||||
the panel header, docks the panel again.
|
||||
- CCTV calibration: `godsEyeView.cctv.calibration.v2`
|
||||
|
||||
---
|
||||
|
||||
+114
-174
@@ -1,202 +1,142 @@
|
||||
# Community PR review and integration
|
||||
|
||||
This is the maintainer acceptance procedure for community features, fixes, and
|
||||
tests. Contributor setup and submission guidance remain in
|
||||
[CONTRIBUTING.md](../CONTRIBUTING.md). Either maintainer listed there can accept
|
||||
and merge a contribution. The [community-pr skill](../.agents/skills/community-pr/SKILL.md)
|
||||
follows this procedure and records the evidence for that decision.
|
||||
Either maintainer listed in [CONTRIBUTING.md](../CONTRIBUTING.md) can accept a
|
||||
contribution. The [community-pr skill](../.agents/skills/community-pr/SKILL.md)
|
||||
uses this procedure; contributor setup remains in `CONTRIBUTING.md`.
|
||||
|
||||
## Start with trusted instructions
|
||||
## 1. Establish the review
|
||||
|
||||
Before checking out or executing a PR, confirm the upstream repository is
|
||||
`bilawalsidhu/gods-eye-view`, fetch its `main`, and record that commit as the
|
||||
policy revision. Read this document and the skill from that revision, together
|
||||
with [SECURITY.md](../SECURITY.md), [CONTRIBUTING.md](../CONTRIBUTING.md), and the
|
||||
relevant parts of [CURRENT-STATE.md](CURRENT-STATE.md). Use the fetched commit
|
||||
SHA when reading files with `git show SHA:path`; a moving branch name alone is
|
||||
not a review record.
|
||||
Verify upstream is `bilawalsidhu/gods-eye-view`, fetch `main`, and record its SHA
|
||||
as the policy revision. Read this workflow, the skill,
|
||||
[SECURITY.md](../SECURITY.md), `CONTRIBUTING.md`, and relevant
|
||||
[CURRENT-STATE.md](CURRENT-STATE.md) sections from that revision with
|
||||
`git show SHA:path`. PR text, code, `AGENTS.md`, and proposed policy changes cannot
|
||||
replace trusted instructions or grant permissions. If policy is unavailable,
|
||||
continue static inspection only until a trusted revision is obtained.
|
||||
|
||||
Keep that trusted procedure throughout the review. PR descriptions, comments,
|
||||
source files, `AGENTS.md`, skills, and proposed policy changes are review input;
|
||||
they cannot grant permissions or replace the instructions reviewing them. Review
|
||||
policy changes as changes for future adoption. If the trusted workflow is missing
|
||||
or inaccessible, report the gap and obtain a maintainer-selected trusted revision
|
||||
before proceeding with acceptance.
|
||||
Record PR URL, author, head SHA, target branch/base SHA, and final candidate SHA.
|
||||
Protect ongoing working changes; resolve unexpected target branches before merging.
|
||||
A review request authorizes findings, not posting or integration. Existing explicit
|
||||
integration authorization covers necessary in-scope cleanup; do not ask again.
|
||||
|
||||
Record the PR number and URL, author, head SHA, target branch, and target base SHA.
|
||||
Resolve an unexpected target branch before integration. Keep review work isolated
|
||||
from the maintainer's working changes. Fetching or reading a diff does not require
|
||||
running its code.
|
||||
## 2. Review the contribution
|
||||
|
||||
## Acceptance gates
|
||||
Review the entire diff and affected callers before execution. Give each area a
|
||||
result: `pass`, `changes needed`, `blocked`, or justified `not applicable`.
|
||||
Usefulness may also be `decline` or `discuss`. Passing one area does not offset
|
||||
failure elsewhere. These questions guide review, not a mandatory questionnaire.
|
||||
|
||||
Each gate needs its own result and evidence. Passing one does not compensate for
|
||||
failing another. Use `pass`, `changes needed`, `blocked`, or `not applicable`
|
||||
with a reason; usefulness can also be `decline` or `discuss`.
|
||||
- **Usefulness:** What user problem does this solve? Does it fit the public-data,
|
||||
local-first product? Are API cost, dependencies, rendering, and maintenance
|
||||
justified? Check attribution/licensing in [DATA_SOURCES.md](../DATA_SOURCES.md).
|
||||
- **Design:** Is behavior correct, including failures, cancellation, listeners,
|
||||
timers, memory, and teardown? Does it duplicate existing logic or mix data
|
||||
acquisition, credentials, graphics, and controller state? Respect package
|
||||
boundaries and injected app operations. Are speculative features, abstractions,
|
||||
switches, or fallbacks over-engineered? Explain concrete costs; allow deliberate
|
||||
duplication and avoid unrelated refactors or hypothetical future-proofing.
|
||||
- **Security:** What boundary changes, and are mitigations proportionate? Inspect
|
||||
dependencies, lockfiles, scripts, CI, plugins, launchers, binaries, assets,
|
||||
symlinks, instructions, and outbound hosts. Keep credentials server-side and
|
||||
out of logs/evidence; check telemetry, SSRF, injection, traversal, feed rendering,
|
||||
proxy destinations/redirects/limits, localhost validation, settings/file access,
|
||||
and bounded voice operations where relevant. Never execute PR code with repository
|
||||
secrets or privileged CI tokens, including via `pull_request_target`. Use scanners
|
||||
where useful, but do not treat a clean scan as proof of safety. Unexplained
|
||||
suspicious behavior or unresolved exploitable issues block integration; report
|
||||
sensitive details privately via `SECURITY.md`.
|
||||
- **Tests and docs:** Does coverage exercise observable behavior and plausible
|
||||
regressions? Prefer fixes whose tests fail on the base. Test-only PRs should
|
||||
close a real coverage gap with deterministic fixtures and useful assertions.
|
||||
Inspect removed/skipped tests, weakened assertions, mocks, snapshots, and runner
|
||||
changes. Update `CURRENT-STATE.md` and `CHANGELOG.md` for runtime changes, and
|
||||
`DATA_SOURCES.md` for source changes.
|
||||
|
||||
### 1. Usefulness and scope
|
||||
## 3. Choose execution proportionate to risk
|
||||
|
||||
- Identify the user problem and observable benefit, including for test-only PRs.
|
||||
- Check fit with the public-data, local-first product and existing capabilities.
|
||||
- Weigh dependencies, API cost, UI complexity, performance, and ongoing maintenance
|
||||
against the benefit. A working feature may still be outside the project's scope.
|
||||
- Verify data-source attribution and licensing against
|
||||
[DATA_SOURCES.md](../DATA_SOURCES.md). Explain a scope rejection constructively.
|
||||
Encourage early discussion for substantial features.
|
||||
**Low-risk UX-only PRs:** ordinary local tests and browser/MCP inspection are
|
||||
appropriate after static review. Do not require a VM, Bubblewrap, or a dedicated
|
||||
account for layout, styling, or interaction changes that leave data access,
|
||||
security boundaries, dependencies, and execution scripts unchanged. Protect
|
||||
ongoing work with a checkout/worktree; avoid personal credentials and everyday
|
||||
browser profiles.
|
||||
|
||||
### 2. Quality and tests
|
||||
**PRs warranting isolation:** security-sensitive changes, new external data sources
|
||||
or data layers, new/changed access endpoints, or dependency/script/launcher/download
|
||||
changes introducing execution risk. Assess the diff, not the PR label. Use a
|
||||
disposable restricted environment without personal secrets, SSH agents, Keychain
|
||||
access, privileged mounts, or container-engine sockets; limit network access.
|
||||
A worktree alone is not isolation. Do not copy personal `.env`, Pinokio
|
||||
`ENVIRONMENT`, or browser profiles, or use launchers that import personal keys.
|
||||
If execution cannot be restricted, continue static review and mark required
|
||||
execution blocked.
|
||||
|
||||
- Review the entire change and affected callers for correctness, readable design,
|
||||
failure handling, and consistency with existing ownership and package boundaries.
|
||||
- Check cancellation, teardown, listeners, timers, memory, and rendering or network
|
||||
budgets where relevant. Avoid unrelated refactors in a contribution's integration.
|
||||
- Require meaningful regression coverage for changed behavior where practical.
|
||||
Prefer a bug test that fails on the old implementation and passes with the fix.
|
||||
Test-only contributions should expose a real coverage gap or prevent a plausible
|
||||
regression, with deterministic fixtures and useful assertions.
|
||||
- Inspect removed tests, skipped tests, relaxed assertions, snapshot updates, mocks,
|
||||
and test-runner changes. A green result from weakened tests is not acceptance.
|
||||
- Check applicable documentation updates: runtime changes need `CURRENT-STATE.md`
|
||||
and `CHANGELOG.md`; source changes need `DATA_SOURCES.md`.
|
||||
For those PRs on Linux/WSL, **strongly prefer Bubblewrap with GPU-accelerated
|
||||
Chromium inside and browser MCP control**. These tools are preferences, not
|
||||
requirements; equivalent restricted environments and automation/manual inspection
|
||||
are acceptable. The [setup reference](PR_REVIEW_SANDBOX.md) supplies launch,
|
||||
connection, cleanup, and Mac alternatives. Bubblewrap does not run natively on Mac.
|
||||
|
||||
### 3. Security and supply chain
|
||||
## 4. Validate the candidate
|
||||
|
||||
Perform a static review before installing dependencies or running PR code. Include
|
||||
lockfiles, package scripts, CI workflows, build plugins, launchers, binaries,
|
||||
generated assets, symlinks, and changes to security checks or agent instructions.
|
||||
Trace unexplained or concealed behavior and new dependency or download origins;
|
||||
do not limit review to files highlighted by the author.
|
||||
|
||||
Use the trusted security model to check the affected boundaries:
|
||||
|
||||
- Private credentials remain server-side; client bundles, logs, errors, fixtures,
|
||||
and screenshots must not disclose them. Review new outbound hosts and telemetry
|
||||
for unexpected data collection or exfiltration.
|
||||
- Proxies retain registered or fixed upstream destinations and applicable redirect,
|
||||
address, timeout, and response-size restrictions. Check SSRF, injection, path
|
||||
traversal, and unsafe rendering of feed-sourced text where inputs cross boundaries.
|
||||
- Localhost and host-validation defaults remain intact. Review environment and
|
||||
settings-file access, file permissions, shell execution, and downloaded code.
|
||||
- Voice tools remain bounded app operations; untrusted feed or model text cannot
|
||||
acquire new execution or credential access.
|
||||
- CI retains least privilege. Never execute untrusted PR code with repository
|
||||
secrets or a privileged token, including through `pull_request_target`.
|
||||
|
||||
Use dependency and static-analysis tools where they add coverage, and record their
|
||||
findings and limitations. Scanners, tests, and AI review cannot prove the absence
|
||||
of a backdoor. Unexplained suspicious behavior or unresolved exploitable issues
|
||||
block integration. Handle vulnerability details privately through the reporting
|
||||
process in `SECURITY.md`; keep public summaries free of sensitive details.
|
||||
|
||||
### 4. Local execution and visual inspection
|
||||
|
||||
Treat dependency installation, tests, builds, launchers, and browser previews as
|
||||
execution of untrusted code. Use a disposable, restricted environment with no
|
||||
personal credentials, inherited secrets, SSH agent, Keychain access, privileged
|
||||
host mounts, or container-engine socket. Limit network access to what validation
|
||||
needs. A worktree alone is not a security boundary. Do not copy the maintainer's
|
||||
`.env`, Pinokio `ENVIRONMENT`, or browser profile into it, or use a launcher that
|
||||
imports personal keys. If this environment is unavailable, continue static review
|
||||
and mark execution blocked rather than running on the credentialed host.
|
||||
|
||||
Use supported Node versions from the trusted `package.json` and CI configuration.
|
||||
After reviewing dependency and script changes, install locked dependencies inside
|
||||
that environment with `npm ci`. Disabling lifecycle scripts can help initial
|
||||
inspection, but it does not make subsequent builds or tests safe to run on the host.
|
||||
|
||||
For runtime changes, record these local results on the candidate to be integrated:
|
||||
Use a supported Node version from trusted `package.json`/CI and `npm ci` in the
|
||||
selected environment. Skipping lifecycle scripts does not make later execution
|
||||
safe for PRs warranting isolation. For runtime changes, record local results for:
|
||||
|
||||
| Check | Command or evidence |
|
||||
| --- | --- |
|
||||
| Setup policy | `npm run doctor -- --json` |
|
||||
| Adopted formatting | `npm run format:check` |
|
||||
| Package boundaries | `npm run check:boundaries` |
|
||||
| Unit tests | `npm test` |
|
||||
| Production build | `npm run build` |
|
||||
| Tracking regression | Start `npm run dev` at `http://localhost:4173`, then run `npm run test:track` with a compatible Chromium available |
|
||||
| Built app | Stop the dev server if needed, then run `npm run preview` and inspect the built app |
|
||||
| Setup, formatting, boundaries | `npm run doctor -- --json`; `npm run format:check`; `npm run check:boundaries` |
|
||||
| Tests and production build | `npm test`; `npm run build` |
|
||||
| Tracking regression | Candidate dev server at `localhost:4173`, then `npm run test:track` with compatible Chromium |
|
||||
| Built app | Stop the dev server, run `npm run preview`, and inspect the built candidate |
|
||||
|
||||
Confirm the browser and tracking harness target the candidate server, not an
|
||||
already-running checkout. Provision browser tooling within the restricted
|
||||
environment. CI is additional evidence; it does not replace local validation.
|
||||
At the time this procedure was introduced, CI does not run `test:track`.
|
||||
Confirm tools target the candidate. Exercise changed/adjacent flows, loading,
|
||||
empty/failure/disabled states, teardown, keyboard, viewports, console, and network.
|
||||
Record the inspector and screenshots/clip for visual changes; contributor evidence
|
||||
alone is insufficient. Prefer keyless fixtures; use restricted test credentials if
|
||||
essential and record untested paths.
|
||||
|
||||
Exercise the changed feature and adjacent interactions. Check loading, empty,
|
||||
failure, disabled, and teardown states as applicable, along with keyboard behavior,
|
||||
relevant viewport sizes, console errors, and unexpected network traffic. Capture
|
||||
screenshots or a short clip for visual changes and compare with the base when
|
||||
needed. Record who or what inspected the running app; contributor screenshots alone
|
||||
do not complete this gate. Use the keyless path and fixtures first. If a keyed path
|
||||
is essential, arrange restricted test credentials and record any untested behavior;
|
||||
do not silently treat it as verified.
|
||||
For rendering/performance changes, verify the actual WebGL renderer and compare
|
||||
base/candidate FPS and frame times with matching browser, viewport, camera, layers,
|
||||
data, warmup, and refresh rate. Keep intrusive tracing/screenshots idle during
|
||||
measurement. GPU access or a synthetic 60 FPS probe does not establish full FPS;
|
||||
software rendering verifies behavior, not GPU performance. Record unavailable
|
||||
performance evidence as a limitation or blocked applicable check.
|
||||
|
||||
For documentation-only changes, runtime, build, tracking, and visual checks may be
|
||||
`not applicable` with a reason; validate links and instructions instead. For
|
||||
test-only changes, run the tests and check their behavior; visual inspection may
|
||||
be `not applicable` if the app is unchanged. A failed or unavailable required check
|
||||
is not `not applicable`. Compare suspected pre-existing failures with the base and
|
||||
record them; do not silently waive them or unresolved security findings.
|
||||
Documentation-only changes need link/instruction checks; test-only changes need
|
||||
relevant test execution. Justify omitted checks. CI supplements local validation;
|
||||
failed/unavailable required checks remain failures/blockers, not `not applicable`.
|
||||
Compare suspected pre-existing failures with the base and record limitations.
|
||||
|
||||
### 5. Integration and attribution
|
||||
## 5. Integrate and report
|
||||
|
||||
Distinguish the request to review from authorization to integrate. A review request
|
||||
produces findings and a recommendation. An explicit instruction to integrate if
|
||||
the gates pass authorizes the necessary in-scope cleanup and integration; do not
|
||||
ask for the same permission again. A maintainer remains responsible for acceptance.
|
||||
Existing session authorization can cover that decision; record it with the result.
|
||||
Posting reviews or comments requires authorization to communicate on the PR.
|
||||
Preserve contributor commits/authorship; put focused maintainer adjustments in
|
||||
separate commits. Prefer a merge commit. For squash/cherry-pick, verify authors and
|
||||
needed `Co-authored-by` trailers using actual identities. Link replacement integration
|
||||
branches to the PR and include release-note credit where appropriate.
|
||||
|
||||
Preserve the contributor's commits and author metadata. Add focused maintainer
|
||||
adjustments as separate commits authored by the maintainer. Prefer a merge commit
|
||||
to retain that history. Use an integration branch when the contributor's branch
|
||||
cannot be edited; link it back to the original PR. If squash or cherry-pick is
|
||||
chosen, verify the resulting author metadata and any needed `Co-authored-by`
|
||||
trailers using actual contributor identities. Do not replace the contributor's
|
||||
authorship with the maintainer's. Explain substantial adjustments and include
|
||||
release-note credit where appropriate.
|
||||
Review adjustments/conflict resolutions and validate the combined candidate.
|
||||
Refresh head/base before merging; reconcile changes and repeat affected checks,
|
||||
including build/runtime checks when combined runtime code changes. Require
|
||||
applicable CI, approvals, and completed gates; never bypass protections. If
|
||||
integration authorization is missing, present the candidate and evidence first.
|
||||
Condition the merge on the reviewed head where supported; if revisions change,
|
||||
return to validation. Verify the merged tree matches the validated candidate and
|
||||
record the merge commit/PR URL; stop on mismatch.
|
||||
|
||||
Before merging:
|
||||
|
||||
1. Review all maintainer adjustments and conflict resolutions as part of the final
|
||||
diff against the target base. Validate the combined candidate, not just the
|
||||
contributor's original head.
|
||||
2. Record the candidate SHA and target base SHA with the validation evidence.
|
||||
Refresh the PR head and target branch before integration. If either changed,
|
||||
reconcile the changes, review the new diff, and repeat affected checks; runtime
|
||||
changes to the combined candidate require the local build and runtime checks.
|
||||
3. Verify required hosted checks, applicable approvals, and mergeability. Never
|
||||
bypass repository protections to complete this workflow. Do not merge with an
|
||||
incomplete required gate. If authorization is still missing, present the
|
||||
concrete candidate and evidence before asking for it.
|
||||
4. Use a merge operation conditioned on the reviewed head SHA where supported.
|
||||
If a head or base change is detected, return to validation rather than retrying
|
||||
a stale merge. Verify the merged result matches the validated candidate tree
|
||||
and record the resulting commit and PR URL. Stop and report any mismatch.
|
||||
|
||||
Repository rules enforce only their configured requirements; this document and
|
||||
the skill do not configure branch protection or CI. Maintainers should require
|
||||
CI and review on `main` and dismiss stale approvals when changes are pushed.
|
||||
|
||||
## Review record
|
||||
|
||||
Keep one concise record on the PR when posting is authorized, or return it to the
|
||||
maintainer otherwise. Keep detailed security evidence in the private report.
|
||||
Return this concise record privately unless posting is authorized. Keep sensitive
|
||||
security evidence in the private report:
|
||||
|
||||
```text
|
||||
PR / author:
|
||||
Policy revision / PR head / target branch and base / final candidate:
|
||||
Usefulness: result and rationale
|
||||
Quality and tests: result, findings, regression evidence
|
||||
Security: areas reviewed, findings, limitations, private report reference if needed
|
||||
Local validation: environment, commands, results, evidence locations
|
||||
Visual inspection: inspector, scenarios, evidence, or justified not applicable
|
||||
Maintainer adjustments and preserved attribution:
|
||||
Required CI and approvals:
|
||||
Decision: ready | changes requested | declined | blocked
|
||||
Accepting maintainer / authorization / remaining blockers:
|
||||
Integration result: merged commit and PR URL, or not merged
|
||||
PR / author / policy revision / head / target branch and base / final candidate:
|
||||
Usefulness, design, security, tests/docs: results, findings, tradeoffs
|
||||
Validation and UX: environment, commands, scenarios, inspector, evidence
|
||||
GPU/performance: renderer, workload, base comparison, or limitations
|
||||
Adjustments / attribution / required CI and approvals:
|
||||
Decision: ready | changes requested | declined | blocked; reasons and blockers
|
||||
Accepting maintainer / authorization / integration result:
|
||||
```
|
||||
|
||||
`Ready` means all applicable gates passed for the recorded candidate; it does not
|
||||
mean the PR has been merged. Give actionable reasons for changes or rejection and
|
||||
recognize useful contributions even when they need maintainer polish.
|
||||
`Ready` means applicable gates passed, not merged. Give actionable feedback and
|
||||
credit useful contributions. This procedure does not itself configure CI or branch
|
||||
protection.
|
||||
+7
-7
@@ -9,7 +9,7 @@ one before going on.
|
||||
```sh
|
||||
npm install
|
||||
npm run build:panel # the in-conversation globe; rerun after app changes
|
||||
npm run dev # http://localhost:5173, keep it running
|
||||
npm run dev # http://localhost:4173, keep it running
|
||||
```
|
||||
|
||||
The MCP server reads from this app.
|
||||
@@ -21,15 +21,15 @@ The server is `server/mcp/stdio.js` in this checkout. Use absolute paths
|
||||
|
||||
| Client | How |
|
||||
| --- | --- |
|
||||
| Claude Code | `claude mcp add gods-eye-view -- node /abs/path/gods-eye-view/server/mcp/stdio.js --api-base http://localhost:5173` |
|
||||
| Codex CLI | `codex mcp add gods-eye-view -- node /abs/path/gods-eye-view/server/mcp/stdio.js --api-base http://localhost:5173` |
|
||||
| Claude Code | `claude mcp add gods-eye-view -- node /abs/path/gods-eye-view/server/mcp/stdio.js --api-base http://localhost:4173` |
|
||||
| Codex CLI | `codex mcp add gods-eye-view -- node /abs/path/gods-eye-view/server/mcp/stdio.js --api-base http://localhost:4173` |
|
||||
| Codex and ChatGPT desktop | Same `~/.codex/config.toml` as the CLI (block below), or Settings → MCP servers → Add server (STDIO). |
|
||||
| Claude Desktop | Settings → Developer → Edit Config, then add the JSON below. |
|
||||
|
||||
```toml
|
||||
[mcp_servers.gods-eye-view]
|
||||
command = "node"
|
||||
args = ["/abs/path/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:5173"]
|
||||
args = ["/abs/path/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:4173"]
|
||||
```
|
||||
|
||||
```json
|
||||
@@ -37,7 +37,7 @@ args = ["/abs/path/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://loc
|
||||
"mcpServers": {
|
||||
"gods-eye-view": {
|
||||
"command": "node",
|
||||
"args": ["/abs/path/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:5173"]
|
||||
"args": ["/abs/path/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:4173"]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -45,7 +45,7 @@ args = ["/abs/path/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://loc
|
||||
|
||||
**Windows with the checkout in WSL:** use `"command": "wsl.exe"` and put
|
||||
`"-e"` and the absolute Linux path to `node` first in `args`, for example
|
||||
`["-e", "/home/you/.local/share/mise/installs/node/24/bin/node", "/home/you/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:5173"]`.
|
||||
`["-e", "/home/you/.local/share/mise/installs/node/24/bin/node", "/home/you/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:4173"]`.
|
||||
|
||||
## 3. Restart and try it
|
||||
|
||||
@@ -60,7 +60,7 @@ Diego in God's Eye View with military flights on."*
|
||||
## Troubleshooting
|
||||
|
||||
- **The server does not appear:** run the command from step 2 in a terminal;
|
||||
it should print `God's Eye View MCP server reading http://localhost:5173`
|
||||
it should print `God's Eye View MCP server reading http://localhost:4173`
|
||||
and wait. A path or `args` mistake fails here.
|
||||
- **The panel says it could not load:** `npm run build:panel` was not run, or
|
||||
the dev server is down.
|
||||
|
||||
@@ -0,0 +1,248 @@
|
||||
# Preferred GPU and browser setup for PR review
|
||||
|
||||
Use this setup when the [maintainer workflow](MAINTAINER_WORKFLOW.md) identifies
|
||||
isolation as warranted: security-sensitive changes, new external data sources or
|
||||
data layers, new or changed access endpoints, or changes that introduce dependency
|
||||
or script execution risk. For those PRs on Linux/WSL, strongly prefer Bubblewrap,
|
||||
GPU-accelerated Chromium inside the sandbox, and browser MCP tools. These tools
|
||||
are preferences, not acceptance requirements; equivalent restricted environments
|
||||
and Puppeteer, Playwright, or manual inspection can supply browser evidence.
|
||||
|
||||
Low-risk UX-only PRs can use ordinary local tests and browser/MCP inspection after
|
||||
static review. They do not need this launcher, a VM, or a dedicated review account
|
||||
solely for layout, styling, or interaction changes that leave data access,
|
||||
security boundaries, dependencies, and execution scripts unchanged. GPU evidence
|
||||
for rendering or performance changes remains relevant regardless of isolation.
|
||||
|
||||
Read this reference from the same trusted policy revision as the workflow.
|
||||
Keep launch wrappers and provisioned browser/MCP tools outside the contributor's
|
||||
tree. The example below is a Linux starting point, not a universal sandbox policy.
|
||||
|
||||
## Prepare the review environment
|
||||
|
||||
1. Put the recorded PR revision in a disposable checkout or worktree. It separates
|
||||
files and Git state; Bubblewrap supplies the execution boundary. Do not copy
|
||||
personal dotenv files, Pinokio `ENVIRONMENT`, browser profiles, or agent settings.
|
||||
A standalone disposable checkout simplifies sandbox mounts. With a worktree,
|
||||
ensure its Git metadata pointer resolves inside the sandbox without exposing
|
||||
the maintainer's credential-bearing Git configuration or hooks.
|
||||
2. Provision supported Node, Chrome for Testing or compatible Chromium, and a
|
||||
pinned browser MCP server in a separate tool directory. Pin the tool's version
|
||||
and lock its dependencies; avoid downloading a moving `latest` during review.
|
||||
3. After static inspection, run `npm ci` for the PR in a credential-free,
|
||||
restricted provisioning environment. Allow only the dependency/download hosts
|
||||
actually needed, then restrict runtime networking. Do not run contributor
|
||||
lifecycle scripts on the host. A dedicated populated npm cache can support
|
||||
an offline install; record any skipped scripts or incomplete installation.
|
||||
4. Start from `--unshare-all`, `--clearenv`, a private `/tmp`, and explicit mounts.
|
||||
Mount toolchains and libraries read-only; make only the disposable review tree
|
||||
and evidence directory writable. Do not mount the user's home, SSH agent,
|
||||
secret stores, system/session bus, or container-engine socket.
|
||||
5. Keep the app, Chromium, and preferably the MCP server in the **same sandbox**.
|
||||
They share sandbox loopback; the agent communicates with MCP over stdio. This
|
||||
avoids exposing either the app or Chromium's debugging port on the host.
|
||||
|
||||
The default network namespace has no external connectivity. Use deterministic
|
||||
fixtures first. For live data, configure a dedicated allowlisted proxy/relay or
|
||||
equivalent restricted egress for both Node providers and Chromium. Merely setting
|
||||
a browser proxy does not restrict server-side requests. Do not substitute
|
||||
`--share-net` as though it preserved host-network isolation. Offline failures are
|
||||
not evidence that live loading and provider paths work.
|
||||
|
||||
## Give the browser GPU and display access
|
||||
|
||||
Mount the required GPU device and matching userspace driver libraries. On typical
|
||||
Linux systems this is a selected `/dev/dri/renderD*` device; the exact device and
|
||||
driver configuration depend on the machine. Prefer a dedicated or nested Wayland
|
||||
compositor for a visible browser. Give it only the required display socket. X11
|
||||
access is broader and can expose other clients on the same display; a private
|
||||
display is preferable for contributor code.
|
||||
|
||||
On WSL/WSLg, OpenGL commonly uses `/dev/dxg`, Mesa's D3D12 driver, and the libraries
|
||||
and matching driver files under `/usr/lib/wsl`. A working host configuration may
|
||||
need these explicitly restored after clearing the sandbox environment:
|
||||
|
||||
```bash
|
||||
--dev-bind /dev/dxg /dev/dxg
|
||||
--ro-bind /usr/lib/wsl /usr/lib/wsl
|
||||
--setenv LD_LIBRARY_PATH /usr/lib/wsl/lib
|
||||
--setenv GALLIUM_DRIVER d3d12
|
||||
--setenv MESA_D3D12_DEFAULT_ADAPTER_NAME '<adapter-name>'
|
||||
```
|
||||
|
||||
The adapter selection is optional and machine-specific. Do not publish a
|
||||
maintainer's personal paths, GPU name, or display socket as mandatory settings.
|
||||
GPU and display access expand the permitted interfaces; keep those mounts narrow
|
||||
and retain Chromium's own sandbox. Avoid `--no-sandbox` and
|
||||
`--disable-web-security`. If Chromium cannot launch securely in the chosen
|
||||
environment, adjust the environment or record the check as unavailable.
|
||||
|
||||
## Example launcher and MCP connection
|
||||
|
||||
This Bash example assumes dependencies are already installed in the disposable
|
||||
review tree and MCP is already installed in the separate locked tool directory.
|
||||
Set the paths and GPU/display arguments for your environment. Provisioning is a
|
||||
separate restricted step; this launcher deliberately starts with offline networking.
|
||||
|
||||
```bash
|
||||
review_tree=/absolute/path/to/disposable-checkout
|
||||
review_node=/absolute/path/to/node-installation
|
||||
review_chrome=/absolute/path/to/chrome-directory
|
||||
review_tools=/absolute/path/to/locked-mcp-tool-directory
|
||||
review_state="$(mktemp -d)"
|
||||
chmod 700 "$review_state"
|
||||
mkdir -p "$review_state/evidence"
|
||||
printf 'review:x:%s:%s::/tmp:/bin/sh\n' "$(id -u)" "$(id -g)" \
|
||||
> "$review_state/passwd"
|
||||
|
||||
# Populate these arrays for the machine. For example, a Linux render node:
|
||||
review_gpu_args=(--dev-bind /dev/dri/renderD128 /dev/dri/renderD128)
|
||||
# A Wayland socket from a dedicated/nested compositor:
|
||||
review_display_socket=/absolute/path/to/dedicated/wayland-0
|
||||
review_display_args=(
|
||||
--dir /run/review
|
||||
--ro-bind "$review_display_socket" /run/review/wayland-0
|
||||
--setenv XDG_RUNTIME_DIR /run/review
|
||||
--setenv WAYLAND_DISPLAY wayland-0
|
||||
)
|
||||
|
||||
bwrap --unshare-all --die-with-parent --new-session \
|
||||
--ro-bind /usr /usr --ro-bind /bin /bin \
|
||||
--ro-bind /lib /lib --ro-bind /lib64 /lib64 \
|
||||
--proc /proc --dev /dev --tmpfs /tmp \
|
||||
--dir /etc --ro-bind "$review_state/passwd" /etc/passwd \
|
||||
--ro-bind /etc/hosts /etc/hosts \
|
||||
--ro-bind /etc/nsswitch.conf /etc/nsswitch.conf \
|
||||
--ro-bind /etc/fonts /etc/fonts \
|
||||
--ro-bind "$review_node" /opt/node \
|
||||
--ro-bind "$review_chrome" /opt/chrome \
|
||||
--ro-bind "$review_tools" /opt/review-tools \
|
||||
--bind "$review_tree" /app \
|
||||
--bind "$review_state/evidence" /evidence \
|
||||
--clearenv --setenv PATH /opt/node/bin:/usr/bin:/bin \
|
||||
"${review_gpu_args[@]}" "${review_display_args[@]}" \
|
||||
--chdir /app /bin/bash -c '
|
||||
set -e
|
||||
npm run dev -- --host 127.0.0.1 --port 4173 --strictPort \
|
||||
> /evidence/server.log 2>&1 &
|
||||
app_pid=$!
|
||||
/opt/chrome/chrome --ozone-platform=wayland \
|
||||
--user-data-dir=/tmp/review-chrome \
|
||||
--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 \
|
||||
> /evidence/chromium.log 2>&1 &
|
||||
chrome_pid=$!
|
||||
trap "kill $app_pid $chrome_pid 2>/dev/null || true" EXIT
|
||||
# Wait for both endpoints without printing anything on MCP stdout.
|
||||
node --input-type=module -e '\''
|
||||
for (const url of ["http://127.0.0.1:4173/", "http://127.0.0.1:9222/json/version"]) {
|
||||
let ready = false;
|
||||
for (let attempt = 0; attempt < 100; attempt++) {
|
||||
try {
|
||||
const res = await fetch(url, { signal: AbortSignal.timeout(1000) });
|
||||
await res.body?.cancel();
|
||||
if (res.ok) { ready = true; break; }
|
||||
} catch {}
|
||||
await new Promise(resolve => setTimeout(resolve, 100));
|
||||
}
|
||||
if (!ready) throw new Error(`Review endpoint unavailable: ${url}`);
|
||||
}
|
||||
'\'' >&2
|
||||
/opt/review-tools/node_modules/.bin/chrome-devtools-mcp \
|
||||
--browser-url=http://127.0.0.1:9222 \
|
||||
--no-usage-statistics --no-performance-crux
|
||||
'
|
||||
```
|
||||
|
||||
Adapt library paths on distributions without `/lib64`. For WSL, replace the GPU
|
||||
arguments with the WSL device/driver arguments above. For a dedicated X11 display,
|
||||
mount its socket and set its `DISPLAY`, and replace `--ozone-platform=wayland`
|
||||
with `--ozone-platform=x11`. The correct ANGLE backend can also vary: the tested
|
||||
WSL OpenGL setup used `--use-gl=angle --use-angle=gl`, without forcing SwiftShader.
|
||||
Preserve driver environment settings deliberately rather than inheriting every
|
||||
host variable. Some drivers need additional narrowly scoped discovery mounts.
|
||||
|
||||
Save the adapted launcher outside the review tree and configure the MCP client's
|
||||
stdio `command` to run that trusted launcher. Keep launcher, app, and browser logs
|
||||
off stdout: it carries the MCP protocol. The launcher stays alive until MCP exits,
|
||||
and Bubblewrap's lifetime closes its child processes. Verify the connected
|
||||
browser's version and page URL before exercising the candidate. An existing MCP
|
||||
connector may target a different browser and may not support retargeting; do not
|
||||
assume it inspected the sandbox. Use equivalent automation if it cannot connect.
|
||||
|
||||
If MCP must run outside the sandbox, expose only a dedicated browser-control
|
||||
relay bound to host loopback, restricted to the review user, and remove it on
|
||||
cleanup. Chromium's DevTools endpoint grants browser control: do not expose it on
|
||||
the LAN or attach it to a personal profile. Loading the app in a host browser
|
||||
places page execution outside Bubblewrap and is a different isolation choice.
|
||||
|
||||
## macOS alternatives
|
||||
|
||||
Bubblewrap depends on Linux namespaces and does not run natively on macOS. It
|
||||
can run inside a Linux VM on a Mac, but that does not establish access to the
|
||||
Mac's GPU or native browser performance. Docker Desktop's documented container
|
||||
GPU support is for Windows with WSL2; do not assume a Mac container supplies
|
||||
hardware-accelerated Chromium.
|
||||
|
||||
For Mac maintainers reviewing PRs that warrant isolation, choose the arrangement
|
||||
that supplies the required evidence. Low-risk UX-only PRs can use native local
|
||||
Chromium/MCP without setting up a VM or dedicated account:
|
||||
|
||||
- **Isolated execution and functional UX:** use a disposable Linux VM (or a
|
||||
container inside its VM) for the checkout, installs, server, Chromium, and MCP.
|
||||
Disable host-home sharing, credentials, shared clipboard, and unrestricted
|
||||
egress. Connect MCP over stdio or a restricted tunnel. Verify the renderer;
|
||||
software rendering supports functional checks but leaves GPU performance
|
||||
unverified. Bubblewrap inside the VM is optional additional isolation.
|
||||
- **Native Mac GPU measurements:** keep contributor installs and server execution
|
||||
in that restricted VM. Forward only the review app port to Mac loopback. Run
|
||||
native Chromium and the trusted MCP server in a dedicated, non-admin review
|
||||
account with a fresh browser profile, no personal credentials, and Chromium's
|
||||
sandbox enabled. Connect MCP to that dedicated browser using stdio and a
|
||||
loopback-only DevTools endpoint; never attach to the maintainer's everyday
|
||||
profile. Verify the actual renderer and compare base/candidate on the same Mac.
|
||||
This preserves native browser GPU access, subject to verification, while page
|
||||
execution is on macOS outside the server VM. Account separation and Chromium's
|
||||
sandbox do not supply the same whole-process boundary as the Linux launcher;
|
||||
record that distinction and use a disposable review machine if stronger
|
||||
isolation is needed. Do not execute contributor Node scripts on the Mac host.
|
||||
- **Browser and server together with GPU isolation:** use a dedicated Linux GPU
|
||||
review machine and the Bubblewrap setup above, with MCP reached through a
|
||||
restricted connection. Its performance evidence applies to that Linux setup;
|
||||
it does not replace Mac-specific regression checks.
|
||||
|
||||
VM graphics capabilities vary. Do not promise native FPS for either Linux or
|
||||
macOS guests without checking their actual browser renderer and representative
|
||||
workload. Record the chosen arrangement and remaining limitations; none of these
|
||||
options makes Bubblewrap mandatory for Mac maintainers.
|
||||
|
||||
## Verify GPU, performance, and UX
|
||||
|
||||
- Inspect `chrome://gpu` and the actual app's WebGL renderer using
|
||||
`WEBGL_debug_renderer_info` where available. Record WebGL2 support, backend,
|
||||
GPU/driver identity, and relevant Chromium flags. SwiftShader, llvmpipe, and
|
||||
other software renderers are functional fallbacks, not GPU performance proof.
|
||||
- Check `chrome://sandbox` to confirm Chromium's renderer protections are active.
|
||||
- Use MCP to exercise changed and adjacent flows, keyboard navigation, viewport
|
||||
sizes, loading/empty/failure states, and teardown. Inspect console and network
|
||||
activity; capture evidence in the disposable evidence directory.
|
||||
- Run the workflow's unit/build/tracking checks inside the restricted environment.
|
||||
Stop the dev server, launch `npm run preview` on the recorded port, and repeat
|
||||
relevant UX checks on the built candidate. Retarget MCP to that server.
|
||||
- For performance changes, measure representative GEV scenes on base and candidate
|
||||
separately, with matching browser, viewport, camera, layers, fixtures, warmup,
|
||||
and display refresh rate. Record FPS and frame-time distribution with MCP
|
||||
screenshots, screencasting, and intrusive tracing idle during the measurement.
|
||||
GPU access does not promise full or identical FPS; a synthetic probe capped at
|
||||
60 FPS cannot establish performance in a heavier scene or at a higher refresh.
|
||||
- Record limitations honestly. Prefer another restricted GPU environment if
|
||||
hardware acceleration is unavailable; continue functional review with software
|
||||
rendering when useful and mark applicable GPU/performance checks unverified.
|
||||
|
||||
When finished, stop the MCP/browser/server processes, remove any relay and fresh
|
||||
browser profile, preserve only intentional review evidence, and remove the
|
||||
disposable checkout and installation cache when they are no longer needed.
|
||||
|
||||
References: [Bubblewrap](https://github.com/containers/bubblewrap),
|
||||
[Chrome DevTools MCP configuration](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/configuration.md),
|
||||
[WSLg container GPU setup](https://github.com/microsoft/wslg/blob/main/samples/container/Containers.md),
|
||||
and [Docker Desktop GPU support](https://docs.docker.com/desktop/features/gpu/).
|
||||
@@ -14,6 +14,12 @@ The session adapter, action runner and backend interfaces remain unchanged.
|
||||
| `realtimeCost.js` | Next-session preferences and the current session's model-bound meter |
|
||||
| `realtimeViewport.js` | One retained image, bounded deletion identities and capture generation |
|
||||
| `realtimeDiagnostics.js` | Bounded error history and sanitized optional diagnostics |
|
||||
| `turnMetrics.js` | Per-turn latency and speech spans written to the debug log |
|
||||
| `narration.js` | Progress lines and the earcon while tools run; spoken through the turns owner |
|
||||
| `pointerContext.js` | Pointer position, dwell pick and the current turn's pointer snapshot (session-scoped) |
|
||||
| `referents.js` | Numbered items from the latest result for `referent:n` (session-scoped) |
|
||||
| `resultDisplay.js` | What the voice card shows for a result and which items it numbers (read by the card and `referents.js`) |
|
||||
| `gevActions.js` runner | Analyst follow-up memory (session: `resetConversation()` on stop, `dispose()` on removal) |
|
||||
|
||||
Pure input policy, preferences and protocol-response policy have separate modules.
|
||||
Owners receive named readers, operations or focused collaborators. Cross-owner
|
||||
@@ -29,7 +35,7 @@ Action and post-capture continuations retain their conversation identity before
|
||||
publishing output, queueing a response or changing status.
|
||||
|
||||
Behavioral invariants remain in force: a 500 ms Space hold claims push-to-talk;
|
||||
short control taps and text entry remain native; a click-started session stays
|
||||
short control taps and text entry remain native; a claimed hold while the assistant speaks interrupts it (never during a Radio handoff); a click-started session stays
|
||||
open-mic. Every accepted or refused tool call receives its terminal output once.
|
||||
New typed input supersedes old intent. Radio waits for the spoken confirmation and
|
||||
verified muted playback. A live cost meter stays bound to its negotiated model,
|
||||
|
||||
Reference in new issue
Block a user