Intent Spec — auto.book_breakdown_assist

FULL ID:       auto.book_breakdown_assist
VERSION:       v1.0.0
STATUS:        draft
LAST UPDATED:  2026-05-11
DOMAIN:        auto
PRIMARY AGENT: AutoServicesAgent
TTBS WEIGHTS:  time=0.50 taste=0.05 budget=0.15 safety=0.30

User's vehicle is currently non-functional — battery dead, tyre puncture, fuel empty, mechanical failure, accident, locked out. User needs immediate roadside assistance: jump-start, on-spot tyre change, towing to nearest workshop, fuel delivery, locksmith. This is an emergency intent with the highest TIME weight in the auto domain.

Partner exemplars: TVS Tow Truck, Allianz Roadside Assist, Bajaj Allianz RSA, ICICI Lombard RSA, Royal Sundaram RSA, AAA-style city services, GoMechanic SOS, Tow My Car.

SECTION 1 — INTENT IDENTITY

This intent fires when the vehicle is at-fault stationary or impaired and user needs help to either restore mobility on-spot or evacuate the vehicle. Distinct from:

• auto.book_general_service — scheduled, planned, vehicle is functional
• auto.book_battery_replacement — planned battery swap, not roadside
• auto.book_tyre_alignment — scheduled alignment, not puncture
• auto.book_major_service — workshop overhaul, not on-spot

Once towing is dispatched, the downstream auto.book_general_service or auto.book_major_service at the destination workshop is a separate intent if the user proceeds. Breakdown assist's contract terminates when the vehicle reaches the destination OR the on-spot fix succeeds OR user cancels.

SECTION 2 — NATURAL LANGUAGE COVERAGE

CLASSIFIES IN

• "My car broke down"
• "Need a tow truck right now"
• "Battery dead, can someone come jump-start"
• "Flat tyre on the highway"
• "Ran out of fuel, send petrol"
• "Locked out of my car"
• "Engine wouldn't start, please help"
• "Accident, need towing to nearest workshop"
• "Bike won't start, mechanic needed at my location"
• "SOS — car stuck on ORR"

CLASSIFIES OUT — BORDERLINE NO

• "Service my car" → auto.book_general_service
• "Schedule a battery replacement next week" → auto.book_battery_replacement
• "Tyre alignment due" → auto.book_tyre_alignment
• "Major engine repair needed at workshop" → auto.book_major_service (user planning, not stranded)
• "Insurance claim for accident" → auto.book_insurance_renewal (v1.1+ separate intent for claims)

MULTI-INTENT TRIGGERS

• "Car broke down, send help and book me a cab home" → auto.book_breakdown_assist + mobility.book_intracity_ride
• "Stranded with my family, send tow and an Uber" → same as above; ride dispatched in parallel
• "Battery dead, tow to nearest workshop and book service" → auto.book_breakdown_assist + auto.book_general_service (chained, breakdown destination = service start)

SECTION 3 — INPUT (TOMO → PROVIDER)

{
  "intent": "auto.book_breakdown_assist",
  "request_id": "req_01J9Z...",
  "user_locale": "en-IN",
  "user_currency": "INR",
  "user_location": {
    "lat": 17.4475,
    "lng": 78.3563,
    "max_radius_km": 30,                       // wider than other auto intents — partner may be far
    "city": "Hyderabad",
    "vehicle_position_description": "Shoulder of ORR near Gachibowli flyover, facing east"
  },
  "emergency_severity": "stranded",            // STRICT ENUM §6: critical | stranded | non_urgent
  "vehicle": {
    "type": "car",
    "make": "Maruti Suzuki",
    "model": "Swift",
    "fuel_type": "petrol",
    "year_of_manufacture": 2021,
    "registration_number_last4": "1234",
    "current_odometer_km": 42500
  },
  "issue": {
    "category": "battery_dead",                // STRICT ENUM §6
    "user_description": "Lights came on, then car wouldn't crank",
    "is_in_accident": false,
    "is_safe_location": true,                  // user-declared; partner may re-assess
    "passengers_with_user": 1,
    "minor_children_present": false
  },
  "preferred_outcome":
      "on_spot_fix",                            // STRICT ENUM §6: on_spot_fix | tow_to_workshop | tow_to_user_choice
  "destination_workshop_id": null,             // when preferred_outcome=tow_to_user_choice, user-picked workshop
  "contact_phone": "+91XXXXXXXXXX",
  "ttbs_user_band": {
    "time":   "fast",                           // typically fast — emergency
    "taste":  "balanced",
    "budget": "good",
    "safety": "great"                           // user prioritises safety in emergencies
  },
  "session_context": {
    "tomo_session_id": "ses_01J9Z...",
    "user_dna_hash":   "dna_v3_a7c9..."
  }
}

Anti-fabrication preamble: Provider may not delay dispatch based on commission rate, surge tier, or vehicle make/model bias. Severity-tagged requests must be routed at advertised SLA.

SECTION 4 — PROVIDER TOOLS

Tool 1: search_assist_providers

PURPOSE:      Return up to 10 providers who can reach user with ETA + scope
INPUT:        §3
OUTPUT:       array<AssistProvider> per §5
SLA:          p50 ≤ 400ms, p95 ≤ 1200ms, p99 ≤ 2500ms  // tightest SLA in auto domain
RATE LIMIT:   60 req/min
IDEMPOTENCY:  request_id; 30s cache (tight — situation may change)
RETRY:        1 on 429 (1s backoff) / 2 on 5xx (exp)

Tool 2: dispatch_assist

PURPOSE:      Confirm dispatch — partner sends crew/tow to user_location
INPUT:        { request_id, provider_id, contact_phone, issue.*, preferred_outcome, destination_workshop_id? }
OUTPUT:       AssistDispatch per §5
SLA:          p50 ≤ 1000ms, p95 ≤ 3000ms
RATE LIMIT:   30 req/min
IDEMPOTENCY:  request_id
RETRY:        TOMO does NOT retry dispatch (would cause double-crew)

Tool 3: track_assist

PURPOSE:      Live ETA / crew location update; called every 30-60s during active dispatch
INPUT:        { request_id, dispatch_id }
OUTPUT:       AssistStatus per §5
SLA:          p50 ≤ 300ms, p95 ≤ 800ms
RATE LIMIT:   240 req/min (polling-tolerant)
IDEMPOTENCY:  None — live data
RETRY:        2 on 5xx (1s, 2s)

Tool 4: cancel_assist

PURPOSE:      Cancel dispatch BEFORE crew arrives. After arrival, cancellation is partner-side workflow + may incur full fee.
INPUT:        { request_id, dispatch_id, reason_code }
OUTPUT:       CancellationResult per §5
SLA:          p50 ≤ 500ms, p95 ≤ 1500ms
RATE LIMIT:   30 req/min
RETRY:        1 on 5xx

SECTION 5 — RESPONSE SHAPE

AssistProvider

AssistProvider:
  provider_id: { type: string, constraint: REQUIRED }
  name: { type: string, constraint: REQUIRED }
  network_type:
    type: enum
    constraint: REQUIRED, STRICT ENUM §6
    values: [insurance_rsa, oem_rsa, independent_rsa, oem_authorised_workshop, app_aggregator]

  capabilities:
    can_jump_start: { type: boolean, constraint: REQUIRED }
    can_change_tyre: { type: boolean, constraint: REQUIRED }
    can_deliver_fuel: { type: boolean, constraint: REQUIRED }
    can_unlock_vehicle: { type: boolean, constraint: REQUIRED }
    can_tow_flatbed: { type: boolean, constraint: REQUIRED }
    can_tow_wheel_lift: { type: boolean, constraint: REQUIRED }
    can_handle_ev: { type: boolean, constraint: REQUIRED }
    can_handle_two_wheeler: { type: boolean, constraint: REQUIRED }
    max_tow_distance_km: { type: int, constraint: REQUIRED, ≥0 }

  current_dispatch:
    crew_location: { type: object, shape: { lat, lng }, constraint: REQUIRED }
    eta_minutes:
      type: int
      constraint: REQUIRED, 1-180
      semantics: live ETA from crew's current position to user_location
    crew_type:
      type: enum
      constraint: REQUIRED, STRICT ENUM §6
      values: [mobile_mechanic, tow_truck, both]
    has_capacity_now: { type: boolean, constraint: REQUIRED }

  estimated_cost:
    base_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0 }
    per_km_tow_inr: { type: int, constraint: REQUIRED nullable, INR_INTEGER, ≥0 }
    after_hours_surcharge_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0 }
    gst_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0 }
    total_estimate_inr: { type: int, constraint: REQUIRED, INR_INTEGER }
    covered_by_user_insurance: { type: boolean, constraint: REQUIRED }
    insurance_partner_name: { type: string, constraint: REQUIRED nullable, required when covered_by_user_insurance=true }

  safety_protocol:
    crew_id_verifiable: { type: boolean, constraint: REQUIRED, semantics: "user can see crew ID + photo before arrival" }
    background_checked: { type: boolean, constraint: REQUIRED }
    emergency_hotline_phone: { type: string, constraint: REQUIRED, E.164 }
    live_track_link_provided: { type: boolean, constraint: REQUIRED }

  ratings:
    avg_rating: { type: float, constraint: REQUIRED, 0-5 }
    review_count: { type: int, constraint: REQUIRED, ≥0 }
    on_time_arrival_pct_last_30d: { type: int, constraint: REQUIRED, 0-100 }

  partner_reference:
    source: { type: string, constraint: REQUIRED }
    deeplink: { type: string, constraint: REQUIRED, HTTPS URL }

AssistDispatch

AssistDispatch:
  dispatch_id: { type: string, constraint: REQUIRED, immutable }
  provider_id: { type: string, constraint: REQUIRED }
  dispatched_at: { type: string, constraint: REQUIRED, ISO_DATETIME }
  initial_eta_minutes: { type: int, constraint: REQUIRED, 1-180 }
  crew:
    crew_id: { type: string, constraint: REQUIRED, opaque }
    crew_name: { type: string, constraint: REQUIRED }
    crew_phone: { type: string, constraint: REQUIRED, E.164 }
    crew_photo_url: { type: string, constraint: REQUIRED, HTTPS URL }
    crew_vehicle_plate_last4: { type: string, constraint: REQUIRED, length 4 }
  live_track_url: { type: string, constraint: REQUIRED, HTTPS URL, signed token, ≤30min validity }
  service_scope_confirmed:
    type: array<string>
    constraint: REQUIRED, ≥1 entry
    example: ["jump_start", "if_jump_fails_tow_to_workshop"]
  destination:
    type: object
    constraint: REQUIRED nullable, required when preferred_outcome=tow_to_*
    shape:
      workshop_name: { type: string, constraint: REQUIRED }
      address: { type: string, constraint: REQUIRED }
      location: { type: object, shape: { lat, lng }, constraint: REQUIRED }
      eta_after_pickup_minutes: { type: int, constraint: REQUIRED, ≥0 }

AssistStatus (live polling)

AssistStatus:
  dispatch_id: { type: string, constraint: REQUIRED }
  status:
    type: enum
    constraint: REQUIRED, STRICT ENUM §6
    values: [crew_en_route, crew_arrived, on_spot_work, towing, at_destination, completed, aborted_by_crew, aborted_by_user]
  crew_current_location: { type: object, shape: { lat, lng }, constraint: REQUIRED }
  updated_eta_minutes: { type: int, constraint: REQUIRED, ≥0 }
  status_message: { type: string, constraint: REQUIRED, ≤200 chars, locale-aware }
  next_update_in_seconds: { type: int, constraint: REQUIRED, 15-120 }

CancellationResult

CancellationResult:
  dispatch_id: { type: string, constraint: REQUIRED }
  cancelled_at: { type: string, constraint: REQUIRED, ISO_DATETIME }
  cancellation_fee_inr:
    type: int
    constraint: REQUIRED, INR_INTEGER, ≥0
    semantics: 0 if before crew dispatched; partner policy otherwise
  refund_amount_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0 }
  refund_eta_days: { type: int, constraint: REQUIRED, 0-14 }

FORBIDDEN FIELDS

• paid_placement_score, ad_bid, sponsored_rank, promotion_priority
• kickback_amount, referral_fee_kickback, _partner_revenue_share
• artificial_urgency_text (note: in this emergency intent, ALL urgency is legitimate; partner may not embellish further)
• ai_generated_photo for crew imagery (real crew photos REQUIRED for safety)
• commission_padded_price
• surge_multiplier_hidden (any surge MUST be disclosed in estimated_cost.after_hours_surcharge_inr)

SECTION 6 — CONTROLLED VOCABULARIES

emergency_severity:
  values:
    critical: "Accident / safety risk / minor present / unsafe location"
    stranded: "Vehicle non-functional, user blocked but safe"
    non_urgent: "Vehicle non-functional, user has time (e.g. parked at home, won't start tomorrow)"

issue.category:
  values:
    battery_dead:       "Battery flat / won't crank"
    flat_tyre:          "Single tyre punctured / blown"
    multiple_tyres:     "Multiple tyres affected"
    fuel_empty:         "Out of fuel"
    locked_out:         "Keys locked inside vehicle"
    won_t_start_other:  "Won't start, cause unknown"
    overheating:        "Engine temperature warning / steam"
    transmission:       "Gear / clutch / transmission failure"
    brake_failure:      "Brake performance compromised"
    accident_minor:     "Accident — drivable but damaged"
    accident_major:     "Accident — non-drivable / injury"
    ev_battery_drained: "EV out of charge"
    other:              "Issue not in list (free-text in user_description)"

preferred_outcome:
  values:
    on_spot_fix:         "Try to fix at location (jump-start, tyre change, fuel delivery)"
    tow_to_workshop:     "Tow to nearest authorised workshop (partner picks)"
    tow_to_user_choice:  "Tow to a specific workshop (user provides destination_workshop_id)"

network_type:
  values:
    insurance_rsa:           "User's insurance company's RSA network"
    oem_rsa:                 "Vehicle manufacturer's roadside (e.g. Maruti On-Road Service)"
    independent_rsa:         "Third-party RSA (Allianz, etc.) under standalone subscription"
    oem_authorised_workshop: "Workshop offering tow service direct"
    app_aggregator:          "Aggregator network (GoMechanic SOS, TVS, etc.)"

crew_type:
  values:
    mobile_mechanic: "Crew with toolkit for on-spot repair"
    tow_truck:       "Flatbed or wheel-lift tow"
    both:            "Crew can attempt on-spot, tow if needed"

status:
  values:
    crew_en_route:      "Crew dispatched, moving toward user"
    crew_arrived:       "Crew at user_location"
    on_spot_work:       "Crew working on the vehicle"
    towing:             "Vehicle being towed"
    at_destination:     "Vehicle delivered to destination"
    completed:          "Service successfully closed"
    aborted_by_crew:    "Crew aborted (couldn't fix, vehicle un-towable, etc.)"
    aborted_by_user:    "User aborted (sorted themselves, friend showed up, etc.)"

SECTION 7 — TTBS DIMENSIONS

TIME (weight = 0.50):
  signals_used:
    - current_dispatch.eta_minutes
    - current_dispatch.has_capacity_now
    - ratings.on_time_arrival_pct_last_30d
  weighting:
    eta: 0.60      # lower ETA = much better
    capacity: 0.25
    on_time_history: 0.15
  user_band_handling:
    fast: maximize TIME weight even further; ignore minor cost differences
    balanced: standard
    flexible: not really applicable — emergency by definition; falls back to fast

TASTE (weight = 0.05):
  signals_used:
    - network_type vs user DNA (some users prefer their insurance RSA over third-party)
  weighting:
    network_match: 1.0
  user_band_handling: standard

BUDGET (weight = 0.15):
  signals_used:
    - estimated_cost.total_estimate_inr
    - estimated_cost.covered_by_user_insurance
  weighting:
    price: 0.50
    insurance_bonus: 0.50  # covered_by_user_insurance=true is a 50% rank boost
  user_band_handling:
    ok: prefer cheapest; insurance coverage matters more
    good: balance price vs ETA
    great: prefer best-rated crew even at premium

SAFETY (weight = 0.30):
  signals_used:
    - safety_protocol.crew_id_verifiable
    - safety_protocol.background_checked
    - safety_protocol.live_track_link_provided
    - ratings.avg_rating
    - issue.minor_children_present (boost safety weight even higher when true)
  weighting:
    crew_verifiable: 0.30
    background: 0.25
    live_track: 0.20
    rating: 0.25
  user_band_handling:
    fast: relax background_check threshold marginally
    balanced: standard
    flexible: prioritise safety even over ETA when minor_children_present=true

When emergency_severity=critical OR issue.minor_children_present=true, weights re-balance to time=0.40 safety=0.45 budget=0.10 taste=0.05 at runtime — safety becomes co-equal with time.

SECTION 8 — COMPLETION CONTRACT

POST /api/v1/cpc/mcp_provider/<your_partner_id>
Body:
{
  "intent":           "auto.book_breakdown_assist",
  "external_id":      "<dispatch_id>",
  "request_id":       "<request_id>",
  "amount_inr":       1200,       // NET (base + km-billing + after-hours, supplier-kept)
  "gst_inr":          216,        // government
  "tips_inr":         100,        // tip to crew, common in roadside
  "pass_through_inr": 0,          // any third-party (e.g. sub-contracted tow) NOT kept by partner
  "closed_at":        "2026-05-11T22:14:00+05:30",
  "status":           "completed",     // STRICT ENUM: completed | aborted_by_crew | aborted_by_user | no_charge
  "issue_resolved_on_spot":   false,
  "towed_to_destination":     true,
  "destination_workshop_id":  "ws_GoMechHydMadhapur",
  "actual_eta_minutes":       23,
  "promised_eta_minutes":     20    // for SLA tracking
}

HMAC, 5-min replay, NET-only commission base. Locked.

SECTION 9 — WIDGET

AssistDispatchWidget (planned). Live-track UI is a first-class widget here — most info-dense in the auto domain because user is mid-emergency.

Source: src/widgets/types.ts → AssistDispatchPayload
Field mapping:
  - AssistProvider.name → header
  - AssistProvider.current_dispatch.eta_minutes → giant ETA pill (largest visual element)
  - AssistProvider.capabilities → checklist of "what they'll do"
  - AssistProvider.safety_protocol.crew_id_verifiable → green safety badge
  - AssistProvider.estimated_cost.total_estimate_inr + covered_by_user_insurance → price row with insurance badge
  - AssistProvider.ratings.on_time_arrival_pct_last_30d → "X% on-time" pill
  - Post-dispatch: AssistStatus.status maps to progress dots + status_message
  - Post-dispatch: live_track_url renders inline map (when provided)

L2/L3 partners can embed their live-track UI directly; L1 fallback opens partner app.

SECTION 10 — CACHING POLICY

SECTION 11 — ERROR CODES

SECTION 12 — SANDBOX → PRODUCTION CHECKLIST

[ ] All four tools (search/dispatch/track/cancel) implemented
[ ] Live ETA on search_assist_providers is computed from real crew GPS positions, not flat estimate
[ ] All capabilities flags correctly reflect partner's actual service set (TOMO field-tests with synthetic dispatches)
[ ] Crew photo URL + crew_vehicle_plate_last4 returned on dispatch (mandatory for safety)
[ ] live_track_url returns a working signed-token live tracking page
[ ] HMAC signing verified on test CPC webhook
[ ] amount_inr is NET; tips_inr and pass_through_inr correctly differentiated
[ ] actual_eta_minutes recorded in CPC payload for SLA tracking
[ ] No forbidden fields anywhere
[ ] SLA p95 met: search ≤1200ms (tight — emergency), dispatch ≤3000ms, track ≤800ms
[ ] Idempotency tested
[ ] Test critical-severity dispatch: weights re-balance to safety=0.45 verified
[ ] Test minor_children_present dispatch: same re-balancing verified
[ ] Insurance partner integration verified (when covered_by_user_insurance=true returns valid insurance_partner_name)
[ ] Cancellation fee logic correct: 0 before crew dispatched, partner policy after
[ ] Emergency hotline phone reachable 24x7 (TOMO field-tests)
[ ] Compliance docs: GSTIN, RSA license (state-specific), privacy policy URL live, crew background-check policy disclosed

SECTION 13 — ANTI-FABRICATION RULES

RULE 1: No paid_placement / ad / kickback fields. Single occurrence rejects entire response.
        In an emergency intent, paid placement would be especially harmful.

RULE 2: eta_minutes must be live-computed from actual crew GPS. Partners providing
        flat 30-minute defaults regardless of distance face immediate suspension.
        TOMO cross-checks by recording dispatch coordinates + actual arrival
        timestamps and computing real travel time.

RULE 3: has_capacity_now=true MUST mean a crew can actually accept the dispatch
        right now. Partners returning has_capacity_now=true and then immediately
        declining the dispatch face suspension after 3 incidents.

RULE 4: crew_photo_url must be the actual crew member's photo. Stock photos,
        AI-generated photos, or "company logo as placeholder" are forbidden.
        Mandatory for user safety. TOMO compares photos against arrival
        check-in selfies on random spot-checks.

RULE 5: crew_vehicle_plate_last4 must match the actual vehicle dispatched.
        Mismatches discovered on arrival are immediate suspension triggers
        (user safety / impersonation risk).

RULE 6: safety_protocol.background_checked=true requires partner to maintain
        documented background-check records for each crew member. Subject
        to admin spot-check during compliance review.

RULE 7: after_hours_surcharge_inr must be a real surcharge tied to time-of-day,
        not a hidden surge multiplier. Surge cannot exceed 2.0x base rate.
        TOMO measures variance between off-peak and peak total_estimate_inr;
        sustained >2.0x ratio violates the policy.

RULE 8: covered_by_user_insurance=true must reflect actual policy verification.
        Partners cannot claim insurance coverage and then bill the user direct.
        TOMO cross-checks via the user's declared insurance partner.

RULE 9: ratings.on_time_arrival_pct_last_30d must be computed from real
        completed dispatches in the past 30 days. TOMO maintains its own
        on-time ratio per provider from CPC payloads (actual_eta vs promised_eta);
        deviation >10% flags review.

RULE 10: status updates in track_assist must reflect real crew state. Falsifying
         "crew_arrived" before actual arrival, or "completed" before actual
         completion, is grounds for immediate suspension. TOMO validates
         via the dispatch_id timeline vs the CPC closed_at timestamp.

RULE 11: No "Top Pick" / "TOMO Recommended" / "Featured" badges. TTBS ranks
         source-blind; in an emergency intent these badges would be especially
         dangerous (users in crisis trust badges disproportionately).

RULE 12: Severity-tagged requests (`emergency_severity=critical`) MUST be
         routed at advertised SLA. Partners who deprioritize critical requests
         in favour of higher-margin stranded/non_urgent requests face
         immediate suspension. TOMO tracks dispatch latency by severity tier.

VERSION HISTORY

v1.0.0 — 2026-05-11 — Initial spec. NET commission base. Time-dominant weights
                       (0.50) with safety co-equal under critical severity.