The STAR Booking Contract

Every booking-shaped artifact AVX produces — service request tickets, appointment proposals, warranty pre-checks — is emitted as STAR-shaped JSON. The structure maps 1:1 to the Standards for Technology in Automotive Retail (STAR) XML message types, so tenants already consuming STAR XML can receive a JSON equivalent and enable an optional XML converter via the booking.starXmlConversion tenant config flag.

Message envelope

Every STAR-JSON message shares a common outer envelope:

{
  "schemaVersion": "1.0.0",
  "messageType": "ServiceRequestAdd",
  "messageId": "msg-<uuid>",
  "sessionId": "vsa-sess-<id>",
  "tenantId": "<tenant-slug>",
  "createdAt": "<ISO 8601 UTC>",
  "createdBy": "vsa-supervisor-v1",
  "correlation": {
    "triageDecisionId": "<triage-uuid>",
    "vin": "<vin>",
    "customerId": "<customer-id or null>"
  },
  "payload": {},
  "signature": {
    "algo": "HMAC-SHA256",
    "keyId": "<signing-key-id>",
    "value": "<base64>"
  }
}

The three message types and their scope are:

messageType	Scope	Triggered by
ServiceRequestAdd	Implemented — emitted by every book() call	P0 (automatic) or P1/P2/P3 on customer confirmation via book() tool
AppointmentAdd	Extension point — not emitted by the current book() implementation	book() when extended to read a calendar feed (slot proposal) or call a DMS API (confirmed booking)
WarrantyClaimPreCheck	Extension point — not emitted by the current book() implementation	book() or a dedicated warranty-lookup tool when triage surfaces a component likely under warranty

Booking behavior and extension points

The book() tool creates a ServiceRequestAdd envelope with the triage classification, recommended action, and session context. When the CMS write is enabled (VSA_BOOK_WRITE_CMS=true), the booking is persisted as a scheduled row in the CMS service-history table so the iOS app and the CMS Fleet Intelligence portal can surface it alongside completed service records. The envelope is returned to the caller with status: "sink-accepted" (CMS write succeeded) or "draft-created" (CMS write skipped or unavailable).

AppointmentAdd and WarrantyClaimPreCheck message types are defined in the STAR schema but are not emitted by the current book() implementation. To extend:

To add calendar slot proposal: extend book() to read a tenant calendar-availability feed and propose concrete slots. Emit an AppointmentAdd message with status: "proposed" and populated proposedSlots. Transition to "confirmed" when the customer accepts a slot. Gate this path on features.calendarSlotProposal: true in the tenant config.

To add DMS booking: extend book() to call a tenant DMS API and receive a confirmed booking number. Emit AppointmentAdd with status: "confirmed" from the live DMS response. Gate this path on features.dmsBooking: true in the tenant config.

Consuming STAR-JSON messages

STAR-JSON messages are delivered to the tenant’s configured sink. Tenants that process STAR XML can enable the converter:

{
  "booking": {
    "starXmlConversion": true,
    "starVersion": "5.6.4"
  }
}

When enabled, a thin Lambda (vsa-star-xml-converter) converts the JSON envelope to STAR 5.x XML. To add the converter, implement a Lambda that:

• Maps the ServiceRequestAdd JSON envelope to STAR 5.x XML.

• Validates output against the STAR XSD and fails hard on any mapping error — never silently emits invalid XML.

• Is invoked after every book() call when booking.starXmlConversion: true is set in the tenant configuration.

Fields not present in the STAR schema are emitted inside a STAR UserArea extension block to preserve round-trip integrity. XML conversion is opt-in; the default behavior emits JSON only.

The full field reference for all three message types, including the ServiceRequestAdd, AppointmentAdd, and WarrantyClaimPreCheck payloads, enumerations, and STAR XML mapping principles, is defined in docs/VSA_STAR_JSON_SCHEMA.md in the AVX repository.

Emitting a booking artifact from a custom tool

If a custom tool needs to produce a STAR message — for example, a partner DMS tool that generates a repair order — it should call the book() tool rather than constructing the envelope directly. Pass the structured service request data and let book() assign the messageId, sessionId, and signature:

# Inside a custom partner-DMS tool
from agents.supervisor.tools.book import make_book_tool

# The supervisor registers book() normally; the custom tool delegates
# to it rather than constructing the STAR envelope itself.
# This preserves the HMAC signature and sink delivery logic.

Custom message types not in the STAR set should be emitted inside the payload._extensions field to preserve round-trip integrity if a STAR XML converter is added later.