Files
gods-eye-view/src/tools/queries/aviation.js
T
Sameh Khamis 61974848fe fix: keep aircraft search results when one feed is down
find_aircraft failed whenever either feed failed. It now answers from the
feeds that responded, names the ones that did not, and searches only the
military feed for registrations, the only feed that reports them.
2026-10-02 15:21:36 -07:00

329 lines
11 KiB
JavaScript

/** Aviation queries over the live aircraft sources (src/sources/live). */
import { defineTool, ToolError } from '../catalog.js';
import {
AREA_SCHEMA,
areaCenter,
areaContains,
distanceKm,
resolveArea,
} from '../area.js';
import {
LIMIT_SCHEMA,
capRows,
countNoun,
isoTime,
thinEvenly,
} from '../results.js';
const ICAO24_SCHEMA = Object.freeze({
type: 'string',
pattern: '^[0-9a-fA-F]{6}$',
description: 'ICAO 24-bit address as six hex characters, such as "a1b2c3".',
});
const CALLSIGN_SCHEMA = Object.freeze({
type: 'string',
pattern: '^[A-Za-z0-9]{2,8}$',
description: 'Flight callsign, such as "UAL123".',
});
const MILITARY_SCHEMA = Object.freeze({
type: 'boolean',
description: 'Use the military aircraft feed instead of the general feed.',
});
const MAX_TRACK_POINTS = 200;
const round = (value, digits) =>
Number.isFinite(value) ? Number(value.toFixed(digits)) : null;
/** The common row for an aircraft record from any live aircraft source. */
function aircraftRow(record, from) {
const point = { lat: record.latitude, lon: record.longitude };
return {
id: record.id,
callsign: record.callsign || null,
lat: round(record.latitude, 5),
lon: round(record.longitude, 5),
altitude_m: round(record.baroAltitudeM ?? record.ellipsoidAltitudeM, 0),
on_ground: record.onGround === true,
speed_mps: round(record.speedMps, 1),
course_deg: round(record.courseDeg, 0),
vertical_rate_mps: round(record.verticalRateMps, 1),
type_code: record.typeCode || null,
registration: record.registration || null,
operator: record.operator || null,
origin_country: record.originCountry || null,
last_contact: isoTime(record.contactTimeMs ?? record.positionTimeMs),
...(from ? { distance_km: round(distanceKm(from, point), 1) } : {}),
};
}
function snapshotInfo(snapshot) {
return {
source: snapshot.source ?? null,
coverage: snapshot.coverage ?? null,
observed_at: isoTime(snapshot.observedAtMs),
freshness: snapshot.freshness ?? 'unknown',
};
}
function feedFor(services, military) {
if (!military) return services.aircraft;
if (!services.military)
throw new ToolError(
'unsupported',
'The military aircraft feed is not available here',
);
return services.military;
}
export const aircraftInArea = defineTool({
name: 'aircraft_in_area',
title: 'Aircraft in an area',
description:
'Aircraft currently reported inside an area, nearest the center first. ' +
'Optionally military aircraft only, airborne only, or within an altitude band.',
inputSchema: {
type: 'object',
properties: {
area: AREA_SCHEMA,
military: MILITARY_SCHEMA,
airborne_only: { type: 'boolean' },
min_altitude_m: { type: 'number', minimum: -500, maximum: 30000 },
max_altitude_m: { type: 'number', minimum: -500, maximum: 30000 },
limit: LIMIT_SCHEMA,
},
required: ['area'],
additionalProperties: false,
},
requires: ['aircraft'],
async run(args, { services, signal }) {
const area = await resolveArea(args.area, { services, signal });
const center = areaCenter(area);
const snapshot = await feedFor(services, args.military).getSnapshot(
{ latitude: center.lat, longitude: center.lon },
{ signal },
);
const altitude = (record) =>
record.baroAltitudeM ?? record.ellipsoidAltitudeM;
const rows = snapshot.records
.filter(
(record) =>
areaContains(area, { lat: record.latitude, lon: record.longitude }) &&
!(args.airborne_only && record.onGround) &&
(args.min_altitude_m == null ||
altitude(record) >= args.min_altitude_m) &&
(args.max_altitude_m == null ||
altitude(record) <= args.max_altitude_m),
)
.map((record) => aircraftRow(record, center))
.sort((a, b) => a.distance_km - b.distance_km);
const kind = args.military ? 'military aircraft' : 'aircraft';
return {
summary:
`${rows.length} ${kind} in ${area.label}` +
(snapshot.freshness === 'stale' ? ' (data may be stale).' : '.'),
data: { ...capRows(rows, args.limit), ...snapshotInfo(snapshot) },
};
},
});
export const findAircraft = defineTool({
name: 'find_aircraft',
title: 'Find an aircraft',
description:
'Find aircraft currently reported anywhere by callsign, ICAO 24-bit ' +
'address or registration. Registrations are known only for aircraft in ' +
'the military feed.',
inputSchema: {
type: 'object',
properties: {
callsign: CALLSIGN_SCHEMA,
icao24: ICAO24_SCHEMA,
registration: { type: 'string', minLength: 2, maxLength: 12 },
limit: LIMIT_SCHEMA,
},
additionalProperties: false,
},
requires: ['aircraft'],
async run(args, { services, signal }) {
const given = ['callsign', 'icao24', 'registration'].filter(
(key) => args[key] != null,
);
if (given.length !== 1)
throw new ToolError(
'invalid_arguments',
'Give exactly one of callsign, icao24 or registration',
);
const [key] = given;
const wanted = args[key].trim().toUpperCase();
const field = {
callsign: 'callsign',
icao24: 'id',
registration: 'registration',
}[key];
// Only the military feed reports registrations.
const feeds = [
...(key === 'registration'
? []
: [{ name: 'civil', feed: services.aircraft }]),
{ name: 'military', feed: services.military },
].filter(({ feed }) => feed);
if (!feeds.length)
throw new ToolError(
'unavailable',
'The military aircraft feed is not available here',
);
const settled = await Promise.allSettled(
feeds.map(({ feed }) => feed.getSnapshot({}, { signal })),
);
signal?.throwIfAborted();
// A search succeeds when any feed answers; missing feeds are named.
const unavailable = feeds
.filter((_, index) => settled[index].status === 'rejected')
.map(({ name }) => name);
if (unavailable.length === feeds.length) throw settled[0].reason;
const seen = new Set();
const rows = settled
.filter((result) => result.status === 'fulfilled')
.flatMap((result) => result.value.records)
.filter(
(record) =>
String(record[field] || '')
.trim()
.toUpperCase() === wanted,
)
.filter((record) => !seen.has(record.id) && seen.add(record.id))
.map((record) => aircraftRow(record));
return {
summary:
(rows.length
? `Found ${countNoun(rows.length, 'aircraft', 'aircraft')} with ${key} ${wanted}.`
: `No aircraft with ${key} ${wanted} is currently reported.`) +
(unavailable.length
? ` The ${unavailable.join(' and ')} feed did not answer.`
: ''),
data: { ...capRows(rows, args.limit), unavailable_feeds: unavailable },
};
},
});
export const getAircraftTrack = defineTool({
name: 'get_aircraft_track',
title: 'Aircraft track',
description:
'Recent positions of one aircraft by ICAO 24-bit address, oldest first. ' +
`Long tracks are evenly thinned to at most ${MAX_TRACK_POINTS} points.`,
inputSchema: {
type: 'object',
properties: { icao24: ICAO24_SCHEMA, military: MILITARY_SCHEMA },
required: ['icao24'],
additionalProperties: false,
},
requires: ['aircraft'],
async run(args, { services, signal }) {
const icao24 = args.icao24.toLowerCase();
// A track server answers 404 for an aircraft it has no positions for.
const track = await feedFor(services, args.military)
.getTrack(icao24, { signal })
.catch((error) => {
if (error?.status === 404) return { records: [] };
throw error;
});
const points = [...track.records].sort(
(a, b) => a.observedAtMs - b.observedAtMs,
);
const kept = thinEvenly(points, MAX_TRACK_POINTS);
const first = points[0];
const last = points.at(-1);
return {
summary: points.length
? `${countNoun(points.length, 'position')} for ${icao24} from ${isoTime(first.observedAtMs)} to ${isoTime(last.observedAtMs)}.`
: `No recent track is available for ${icao24}.`,
data: {
icao24,
total: points.length,
returned: kept.length,
thinned: kept.length < points.length,
points: kept.map((point) => ({
time: isoTime(point.observedAtMs),
lat: round(point.latitude, 5),
lon: round(point.longitude, 5),
altitude_m: round(point.baroAltitudeM, 0),
on_ground: point.onGround === true,
})),
},
};
},
});
export const getAircraftInfo = defineTool({
name: 'get_aircraft_info',
title: 'Aircraft type and route',
description:
'Look up an aircraft type and registration by ICAO 24-bit address, and ' +
'a flight route by callsign, from adsbdb. Give either or both.',
inputSchema: {
type: 'object',
properties: { icao24: ICAO24_SCHEMA, callsign: CALLSIGN_SCHEMA },
additionalProperties: false,
},
requires: ['aircraft'],
async run(args, { services, signal }) {
if (args.icao24 == null && args.callsign == null)
throw new ToolError('invalid_arguments', 'Give icao24, callsign or both');
const lookup = (kind, id) =>
id == null
? null
: services.aircraft.getEnrichment({ kind, id }, { signal });
const icao24 = args.icao24?.toLowerCase();
const callsign = args.callsign?.toUpperCase();
const [type, route] = await Promise.all([
lookup('type', icao24),
lookup('route', callsign),
]);
const aircraft = type?.found
? {
icao24,
type_code: type.typeCode ?? null,
type_name: type.typeName ?? null,
registration: type.registration ?? null,
}
: null;
const airport = (value) =>
value
? {
code: value.code || null,
name: value.name || null,
lat: value.lat ?? null,
lon: value.lon ?? null,
}
: null;
const flight = route?.found
? {
callsign,
airline: route.airline ?? null,
origin: airport(route.origin),
destination: airport(route.destination),
}
: null;
const parts = [];
if (icao24)
parts.push(
aircraft
? `aircraft ${icao24} is ${aircraft.type_name || aircraft.type_code || 'an aircraft of unknown type'}${aircraft.registration ? ` (${aircraft.registration})` : ''}`
: `no type is known for ${icao24}`,
);
if (callsign)
parts.push(
flight
? `flight ${callsign} flies ${flight.origin?.code || flight.origin?.name} to ${flight.destination?.code || flight.destination?.name}${flight.airline ? ` (${flight.airline})` : ''}`
: `no route is known for ${callsign}`,
);
const summary = parts.join('; ');
return {
summary: `${summary.charAt(0).toUpperCase()}${summary.slice(1)}.`,
data: { aircraft, route: flight },
};
},
});