Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,7 @@ charting or document tools to create figures and analysis. Custom chart renderin
in the agent's tools. The API supplies comparisons, scenario calculations, provenance and JSON.
Configuration/model-year data and VIN-specific facts retain their distinct scopes.

VIN recall repair status: Tesla and Ford open/completed statuses, GM open/completed or administratively closed records, Honda and Acura active safety recalls, Subaru completed/incomplete safety recalls, Volkswagen, Audi, Land Rover and Jaguar recalls as reported by each maker, positive Nissan open safety recalls, and Mopar VIN-matched open recall/campaign records are included in reports and comparisons, with `vin_recall_status`, `GET /api/vin/{vin}/recall-status` and `VinClient.recallStatus(vin)`. Mopar safety-recall count and completed history remain unknown because its feed mixes campaign types. GM repair dates are shown only when explicitly supplied; administrative closing dates remain separate. Ford customer-satisfaction and GM non-recall programs stay separate from recall counts. Honda covers active safety recalls from the past 15 calendar years and does not supply completed history. Nissan requires matching full VINs and verified safety classifications; empty results remain unknown. Toyota/Lexus/Scion, Hyundai and Kia require interactive official verification. Other makes remain unknown. See the [source and coverage notes](docs/data-sources.md#vin-specific-recall-repair-status).
VIN recall repair status: Tesla and Ford open/completed statuses, GM open/completed or administratively closed records, Honda and Acura active safety recalls, Subaru completed/incomplete safety recalls, Volkswagen, Audi, Land Rover and Jaguar recalls as reported by each maker, positive Nissan open safety recalls, and Mopar VIN-matched open recall/campaign records are included in reports and comparisons, with `vin_recall_status`, `GET /api/vin/{vin}/recall-status` and `VinClient.recallStatus(vin)`. Mopar safety-recall count and completed history remain unknown because its feed mixes campaign types. GM repair dates are shown only when explicitly supplied; administrative closing dates remain separate. Ford customer-satisfaction and GM non-recall programs stay separate from recall counts. Honda covers active safety recalls from the past 15 calendar years and does not supply completed history. Nissan requires matching full VINs and verified safety classifications; empty results remain unknown. Toyota/Lexus/Scion, Hyundai and Kia require interactive official verification. Other makes remain unknown. A report waits up to 2 s for the maker's lookup (MCP `decode_vin`: 6 s); a slower maker (Ford's lookup usually takes about 10 s) gives `recall_status.pending: true`, unknown rather than zero, with `status_url` to fetch the complete status from the same running lookup, or ask with `?recall_wait=full` (`VinClient.decode(vin, {recallWait: 'full'})`). NHTSA's complaint list (5-17 s for a common model) arrives the same way: `complaints.pending: true` with `status_url` `/api/vin/{vin}/complaints`. See the [source and coverage notes](docs/data-sources.md#vin-specific-recall-repair-status).

Deployment caching: HTML must revalidate, API responses must not be stored by shared caches, and changed JavaScript/PDF links use a content-hash query version generated by `node scripts/version-assets.mjs`. API clients also bypass stored browser responses. Preserve these policies in any reverse proxy so updated recall records are rendered by the matching client code.

Expand Down
26 changes: 25 additions & 1 deletion docs/data-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,29 @@ Tesla Service's [official VIN recall search](https://service.tesla.com/en-US/vin

`GET /api/vin/{vin}/recall-status`, `VinClient.recallStatus(vin)` and MCP `vin_recall_status` expose this data. VIN reports and printable comparisons include the summary. Tesla and Ford supply open/completed states. Subaru supplies completed and incomplete safety recalls, with emissions campaigns listed separately. Volkswagen, Audi and Land Rover report open recalls, and completed ones only where their lookup returns them. Acura is covered through the Honda lookup. (Added 2026-11-16 in `lib/more-manufacturer-recalls.mjs`; open records have been seen live for Volkswagen and Audi; completed records for those two, and any Land Rover or Jaguar record, have only been read from the makers' page code. Jaguar shares Land Rover's lookup. BMW's lookup did not answer plain requests and is not used.) GM supplies open/completed or administratively closed records, and explicit repair dates where supplied. Honda supplies active safety recalls; Nissan supplies positive open safety recalls and Mopar supplies VIN-matched open recall/campaign records, with the limitations below. Toyota, Lexus, Scion, Hyundai and Kia require interactive verification; other manufacturers return unknown with an official lookup link. Unknown response statuses never count as zero open recalls; recall dates never become repair completion dates. Results are not a complete service history or a guarantee of safety. Successful results are cached for up to 15 minutes; failures are retried. Public manufacturer interfaces are undocumented for third-party integration and can change.

#### When the maker answers slowly: `pending`

A report does not wait the whole time for a slow maker. The lookup starts as soon as the VIN is decoded, beside NHTSA's calls, and the report waits for it up to a budget counted from that start: 2 s for the website and `GET /api/vin/{vin}` (`RECALL_WAIT_MS.report` in `lib/reports.mjs`), 6 s for MCP `decode_vin` (`RECALL_WAIT_MS.mcp`). Comparisons wait for the full answer (they are printed and exported). A maker still answering after the budget gives:

```json
"recall_status": {"vin": "1FMCU0G61LUA27504", "scope": "vin", "vin_specific": true, "available": false,
"pending": true, "reason": "lookup_in_progress", "maker": "Ford", "waited_ms": 2000,
"open_count": null, "completed_count": null, "recalls": [],
"source": {"provider": "Ford Owner Support VIN Recalls", "reference_url": "https://www.ford.com/support/recalls-details/..."},
"verification_url": "https://www.ford.com/support/recalls-details/...",
"status_url": "/api/vin/1FMCU0G61LUA27504/recall-status", "note": "..."}
```

Pending is unknown, never "no open recalls" (`available: false`, counts null). The lookup keeps running in the background and fills the 15-minute cache; one lookup per VIN runs at a time and every request for that VIN shares it (`createRecallStatusLookup`). `GET status_url`, MCP `vin_recall_status` and `GET /api/vin/{vin}?recall_wait=full` (MCP: `recall_wait: "full"`) wait for that same lookup. A background lookup that fails is caught: nothing is cached and the next request asks the maker again. In MCP output a pending status also carries `next_step: {tool: "vin_recall_status", arguments: {vin}}`. `decode_checks.sources.manufacturer_record.status` is `pending` meanwhile; the checks that use the maker's description of the VIN run when the status arrives.

The website shows "Checking with Ford…" in the recall card, the car sheet's recall row and the decode-checks source line, then requests the report again with `?recall_wait=full` and redraws only the blocks that changed (the status block, the car sheet's recall section and footer, and the decode checks, fuel economy and test-vehicle blocks only if the maker's record changed a checked value), keeping typed text, open forms, focus, the transmission choice and the scroll position (`public/keep-state.js`). Printed while pending, the car sheet's row reads "Unknown: Ford had not answered when this sheet was printed" and the recall card "Not loaded: Ford had not answered when this page was printed"; printing does not wait. If the second request fails twice, the status reads as not loaded (unknown).

Why Ford is slow (measured 2026-11-18 from the web server, 4 requests): Ford's CDN (Akamai) holds each request about 9-10 s before answering (`server-timing` edge duration 9,000-10,002 ms; origin about 120 ms), even for a no-VIN page, a cached redirect and a reused connection, so the delay is per request and a client cannot shorten it. The VIN page is also about 1.3 MB, with the recall data about 81% of the way through. Reports for other makes took 0.4-2 s in all before this change.

#### NHTSA's complaint list: `pending` the same way

NHTSA's `complaintsByVehicle` sends a model year's whole list at once: 1-2 MB of JSON for a common model, which took 17.3 s for a 2020 Ford Escape, 5.0 s for a 2017 Honda CR-V and 6.4 s for a 2003 Honda Accord (from the web server, 2026-11-18; time to first byte, so NHTSA's own time). It used to be awaited with the rest under a 10 s timeout, so the Escape's list always failed and its report was never cached. Now (`modelYearComplaints` in `lib/reports.mjs`) one request per make, model and year runs at a time, shared by every report and `GET /api/vin/{vin}/complaints`, for up to 30 s; successful lists are cached 6 hours. The report is assembled without waiting for it and waits up to the same budgets (2 s website and REST, 6 s MCP; comparisons wait). Still arriving, `complaints` is `{"available": false, "pending": true, "reason": "lookup_in_progress", "count": null, "complaints": [], "summary": null, "status_url": "/api/vin/{vin}/complaints", "note": ...}`: unknown, never zero. When the list arrives the complete report is built and cached for the next request. The server-rendered VIN page (`/{vin}`) no longer waits for the list (it leaves the complaint count out of its description while pending). The website shows "Loading NHTSA's owner complaints…" and fills the card and the car sheet's row in place from `status_url`; printed while pending they say the list had not arrived. In MCP output a pending list says to call `decode_vin` again (there is no complaints tool).

### Ford: open/completed recalls and separate programs

The [official Ford VIN page](https://www.ford.com/support/recalls/) serves its VIN-specific status in the same public page used by the browser. The adapter parses the serialized data as JSON; it never executes downloaded JavaScript. Both the page VIN and the returned vehicle VIN must match. The success flag, validation flag, arrays and declared record counts must agree. `O` means open and `C` means completed; other values remain unknown. Safety/environmental recall records and customer-satisfaction programs are separate. Coverage begins January 1, 2004. No repair date is supplied, so `repair_completed_at` remains null. The same official checker accepts Ford, Lincoln and Mercury; upstream confirmation still controls availability.
Expand Down Expand Up @@ -674,7 +697,8 @@ tires and capacities) use the checked values. Code: `lib/decode-checks.mjs`, `li
disagree leave the field unset; "e-tron", "PZEV", "FED", a lone "A" and Subaru's "2.5X" are never read as
powertrain, transmission or drive. The VIN page is drawn before the maker replies and never waits for it
(`sources.manufacturer_record.status: "not_checked"`); the REST report, MCP `decode_vin` and comparisons
re-run the checks with it (`used`, `not_available` or `not_supported`). In a gentle sample of 16 NHTSA test
re-run the checks with it (`used`, `not_available` or `not_supported`), or say `pending` when the maker had not
answered within the report's wait (see "When the maker answers slowly" above; the website then fills them in). In a gentle sample of 16 NHTSA test
vehicles the description agreed with vPIC on every stated field except drive on both 2018 Atlases (vPIC AWD,
Volkswagen "FWD", both test reports FWD), and named "MULTITRONIC" (a CVT) where vPIC said "Automatic".
- **NHTSA test-vehicle evidence.** `data-src/decode-evidence.jsonl` (built offline by the audit, imported with
Expand Down
1 change: 1 addition & 0 deletions lib/cache.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,4 @@ export const vinCache = new LRUCache(1000, 60 * 60 * 1000); // 1hr for full
export const recallCache = new LRUCache(500, 6 * 60 * 60 * 1000); // 6hr for recalls (change less often)
export const ratingCache = new LRUCache(500, 24 * 60 * 60 * 1000); // 24hr for safety ratings (static)
export const fuelCache = new LRUCache(500, 24 * 60 * 60 * 1000); // 24hr for fuel economy (static)
export const complaintCache = new LRUCache(200, 6 * 60 * 60 * 1000); // 6hr for NHTSA complaints (1-2 MB for a common model)
4 changes: 2 additions & 2 deletions lib/mcp/research-tools.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import { rateBenchmarks } from '../rate-benchmarks.mjs';
import { scenario } from '../scenario.mjs';
import { communications } from '../communications.mjs';
import { capabilities } from '../capabilities.mjs';
import { vinRecallStatus } from '../recall-status.mjs';
import { vinRecallStatusFor } from '../reports.mjs';
import { compareVehicles } from '../reports.mjs';

export function researchTools(add) {
Expand All @@ -15,7 +15,7 @@ export function researchTools(add) {
});
const vehicleQuery={year:z.number().int(),make:z.string().min(1).max(100),model:z.string().min(1).max(100)};
researchTool('explore_capabilities','Discover supported features and explicit coverage gaps.',{},()=>capabilities);
researchTool('vin_recall_status','VIN-specific manufacturer-reported open and completed recall status. Tesla and Ford open/completed states; GM completed/closed states with explicit repair dates where supplied; Honda and Acura active safety recalls; Subaru completed/incomplete safety recalls; Volkswagen, Audi, Land Rover and Jaguar recalls as reported by each maker; Nissan positive open safety recalls; Mopar positive open records matched to the full VIN. Service programs are separate. Toyota, Hyundai and Kia require interactive official verification. Unknowns are never zero. Not a complete service history. Where the maker\'s reply describes the VIN (Volkswagen, Audi, Land Rover, Jaguar, Subaru, Honda/Acura), manufacturer_description gives the raw text and only the fields it states.',{vin:z.string()},({vin})=>vinRecallStatus(vin));
researchTool('vin_recall_status','VIN-specific manufacturer-reported open and completed recall status. Tesla and Ford open/completed states; GM completed/closed states with explicit repair dates where supplied; Honda and Acura active safety recalls; Subaru completed/incomplete safety recalls; Volkswagen, Audi, Land Rover and Jaguar recalls as reported by each maker; Nissan positive open safety recalls; Mopar positive open records matched to the full VIN. Service programs are separate. Toyota, Hyundai and Kia require interactive official verification. Unknowns are never zero. Not a complete service history. Where the maker\'s reply describes the VIN (Volkswagen, Audi, Land Rover, Jaguar, Subaru, Honda/Acura), manufacturer_description gives the raw text and only the fields it states. When a decode_vin report has recall_status.pending, this waits for that same lookup (up to about 15 s).',{vin:z.string()},({vin})=>vinRecallStatusFor(vin));
researchTool('vehicle_catalog','Browse EPA year, make, model and configuration menus. Not sale listings.',{level:z.enum(['year','make','model','options']),year:z.number().int().optional(),make:z.string().optional(),model:z.string().optional()},({level,...query})=>catalog(level,query));
researchTool('epa_vehicle','Get an explicitly selected EPA test configuration; not an exact VIN match.',{id:z.string()},({id})=>epaRecord(id));
researchTool('vehicle_emissions','Get EPA emissions for an explicit EPA vehicle ID.',{id:z.string()},({id})=>emissions(id));
Expand Down
11 changes: 6 additions & 5 deletions lib/mcp/vehicle-tools.mjs
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
import * as z from 'zod/v4';
import { validateVin, normalizeVin } from '../validate.mjs';
import { decodeVin as nhtsaDecode, batchDecode } from '../nhtsa.mjs';
import { fullReport, mcpReport, modelYearRecalls } from '../reports.mjs';
import { fullReport, mcpReport, modelYearRecalls, RECALL_WAIT_MS } from '../reports.mjs';
import { applyOwnerDetails } from '../transmission-choice.mjs';

export function vehicleTools(add) {
add('decode_vin',
'Decode a VIN and return a vehicle report: specs, recalls (with manufacturer build-date ranges), a complaint summary with the most recent complaints, safety ratings, fuel economy, EPA test-vehicle data, parts content and origin (MY2020+), historical production and theft (MY1998-2012), and photo URLs. decode_checks checks the official decode field by field (drive, engine, electrification, transmission, speeds, seats, GVWR) against the manufacturer\'s description of this VIN, NHTSA test vehicles with the same VIN pattern and EPA\'s configurations: confirmed, corrected, doubtful or filled, with vPIC\'s original value kept.',
'Decode a VIN and return a vehicle report: specs, recalls (with manufacturer build-date ranges), a complaint summary with the most recent complaints, safety ratings, fuel economy, EPA test-vehicle data, parts content and origin (MY2020+), historical production and theft (MY1998-2012), and photo URLs. decode_checks checks the official decode field by field (drive, engine, electrification, transmission, speeds, seats, GVWR) against the manufacturer\'s description of this VIN, NHTSA test vehicles with the same VIN pattern and EPA\'s configurations: confirmed, corrected, doubtful or filled, with vPIC\'s original value kept. recall_status is the manufacturer\'s VIN-specific recall status; a maker that has not answered within about 6 s (Ford\'s lookup takes 10 s or more) gives recall_status.pending true: unknown, not "no open recalls"; call vin_recall_status with the VIN for the complete answer, or pass recall_wait "full". NHTSA\'s complaint list for a common model can take 15 s or more: complaints.pending true is unknown, not zero; call decode_vin again in a minute (cached once it arrives).',
{ vin: z.string().describe('17-character Vehicle Identification Number'),
transmission: z.optional(z.enum(['automatic', 'manual'])).describe('Transmission, when the owner knows it and the VIN does not say. Applies to fuel economy only when EPA lists the model with both; without it an automatic is assumed and marked (fuel_economy.assumed, alternatives).') },
async ({ vin, transmission }) => {
const report = mcpReport(applyOwnerDetails(await fullReport(vin), { transmission }, { by: 'request' }));
transmission: z.optional(z.enum(['automatic', 'manual'])).describe('Transmission, when the owner knows it and the VIN does not say. Applies to fuel economy only when EPA lists the model with both; without it an automatic is assumed and marked (fuel_economy.assumed, alternatives).'),
recall_wait: z.optional(z.enum(['full'])).describe('"full": wait for the manufacturer\'s VIN recall lookup (up to about 15 s) instead of returning recall_status.pending after about 6 s.') },
async ({ vin, transmission, recall_wait }) => {
const report = mcpReport(applyOwnerDetails(await fullReport(vin, { recallWaitMs: recall_wait === 'full' ? Infinity : RECALL_WAIT_MS.mcp, complaintsWaitMs: RECALL_WAIT_MS.mcp }), { transmission }, { by: 'request' }));
return { content: [{ type: 'text', text: JSON.stringify(report, null, 2) }] };
}
);
Expand Down
Loading
Loading