Cross-surface Actions framework

Findings are what Tier 2 agents write. Actions are what customers and dealers do with Findings. An owner approves a Finding on their iOS card → an Action is created → an executor dispatches to the target system → Action status propagates back to all surfaces.

Finding + Action schema (canonical)

Finding (Tier 2 output):

{
  "finding_id": "FIND-{uuid}",
  "finding_key": "sha256:{agent_id}:{scope_field}:{scope_value}:{finding_kind}[:{subject_key}]",
  "subject_key": null,
  "agent_id": "agent-1-energy | agent-2-vehicle-health | agent-3-ownership-cost | agent-4-concierge | agent-fi-cost | agent-fi-recall-warranty | agent-fi-fleet-health | agent-fi-rebalancing | agent-fi-quality",
  "agent_version": "agent-2-vehicle-health@v1.0.2",
  "scope": {
    "vin": "1MERIDIAN00A000001",
    "owner_id": null,
    "fleet_id": null,
    "dealership_id": null,
    "district_id": null,
    "population_id": null
  },
  "severity": "p0 | attention | soon | routine | informational",
  "finding_kind": "health.tires | health.brakes | health.battery | energy.range_context | coverage.warranty_gap | concierge.position | fleet.cost.anomaly | fleet.cost.sell_timing | fleet.recall.vehicle | fleet.warranty.claim_candidate | fleet.health.service | fleet.rebalance.move | fleet.rebalance.gap | quality.investigation | quality.issue | ...",
  "recommended_action": {
    "action_kind": "book_recall_service",
    "target_system": "dms",
    "parameters": {},
    "estimated_value_usd": null,
    "estimated_value_basis": null
  },
  "headline": "Left front tire: 8,000 km to threshold, slow leak indicated",
  "detail": "## Tire Health\n\n...",
  "evidence": [
    {
      "kind": "adp_tire_prediction",
      "source": "ADP",
      "source_ref": "adp://tire-health/vsa-staging/2026-10-01",
      "value": "remaining_km: 8000",
      "computed_at": "2026-10-01T02:00:00Z",
      "provenance": "live",
      "vin": "1MERIDIAN00A000001"
    }
  ],
  "computed_at": "2026-10-01T02:15:00Z",
  "expires_at": "2026-10-02T02:15:00Z",
  "confidence": "high",
  "inputs_hash": "sha256:...",
  "tokens_used": 8750,
  "cost_usd": 0.042,
  "disclosure_txt": null,
  "audit_trail": [
    {
      "at": "2026-10-01T02:15:00Z",
      "event": "finding_written",
      "agent_version": "agent-2-vehicle-health@v1.0.2",
      "inputs_hash": "sha256:..."
    }
  ]
}

finding_key is the persistent-condition identity. Two runs for the same VIN, component, and finding_kind produce the same key; an optional subject_key joins the hash when one scope needs several open Findings of one kind. recommended_action is optional and states what approving the Finding dispatches. A worsening condition updates the existing Finding in place rather than creating a second row.

Action (approval from customer or dealer):

{
  "action_id": "AVX-ACT-{uuid}",
  "finding_id": "FIND-...",
  "created_by": "owner-{id} | dealer-{id} | fleet-manager-{id} | engineer-{id}",
  "decided_by": {"kind": "operator | engineer | user | rule", "id": "{token sub} | {fleet_id}/{rule_id}"},
  "decision": "approved | overridden | auto_approved | declined",
  "created_at": "2026-10-01T14:32:00Z",
  "updated_at": "2026-10-01T14:35:00Z",
  "target_system": "dms | vehicle-command | retail | none | chat | ios-owner | cms | adp",
  "target_ref": "DMS-RO-12345",
  "status": "pending_execution | executed | in_progress | completed | cancelled | declined | dismissed | failed",
  "action_kind": "book_combined_visit | schedule_inspection | acknowledge_only | book_recall_service | ground_vehicle | submit_warranty_claim | book_fleet_service | move_vehicles | apply_cost_action | exempt_recall | complete_recall | record_engineering_decision | issue_recall | issue_software_campaign | lead_capture | configurator_recommend | ...",
  "parameters": {},
  "evidence": [],
  "audit_trail": [
    {
      "at": "2026-10-01T14:32:00Z",
      "by": "owner-{id}",
      "from_status": "pending_execution",
      "to_status": "in_progress",
      "note": "dms executor dispatched",
      "failure_kind": null,
      "retry_count": 0
    }
  ]
}

dismissed means the customer dismissed the Finding without acting. failed means the target could not be reached after the retry budget, or refused the request as malformed; it triggers dual escalation: an owner iOS card update and a vsa.avx.action.terminal_failure event with a CloudWatch metric. decided_by comes from the verified token for an operator, never from the request body. Approving with parameters that differ from recommended_action.parameters is recorded as overridden; AVX compares the two itself.

API

Endpoint	Purpose
GET /findings/me	Owner’s Findings across all agents, paginated, sorted by severity
GET /findings/vehicle/{vin}	Vehicle-scoped Findings — used by fleet manager and dealer personas
GET /findings/fleet/{fleet_id}	Fleet-scoped Findings, including the fleet’s VIN-scoped Findings
POST /findings/{id}/approve	Creates an Action and dispatches to the executor for the specified target_system. Refuses an action kind with no working executor before writing anything.
POST /findings/{id}/decline	Records the operator’s decision not to act, with an optional reason (status=declined, decision=declined)
GET, PUT, DELETE /approval-rules/fleet/{fleet_id}[/{rule_id}]	Per-fleet auto-approval rules; same fleet check as approve
POST /investigations	Queues a fleet-quality investigation of a fault pattern. CMS calls it with the product engineer’s token; AVX checks product-engineer membership again and takes requested_by from the token
POST /actions/{id}/dismiss	Sets status=dismissed; broker records the dismissal for demotion in the 30-day scoring window
GET /actions/{owner_id}	Owner’s Action feed — status ladder for iOS card rendering

Executor pattern — pluggable dispatch

Each target_system maps to an Executor class registered in agents/executors/registry.py. Executor modules are not importable from agent modules — this boundary is test-enforced. Agents write Findings through write_finding(); they do not dispatch Actions or call channel APIs. The boundary makes pull-only rollout safe: a new agent writes Findings that Tier 1 surfaces on request, with no delivery side effects until proactive delivery is enabled.

Executor	Target system	Dispatch behavior
dms	DMS repair-order API	Creates a repair order with avx_action_id in the RO metadata: an owner’s service visit, a fleet recall remedy, or a fleet service visit. Files fleet warranty claims through POST /api/dms/fleet/warranty-claims, where DMS validates the claim and computes the amount (201 submitted, 202 waiting for the dealer’s warranty administrator, 422 denied). Status updates feed back through dms.ro.status_changed EventBridge events to update the Action record. Refusal (4xx) → declined; client-error 4xx or exhausted retries on 5xx / timeout → failed + dual escalation (owner card + vsa.avx.action.terminal_failure event).
vehicle-command	CMS remote command API	Sends a remote command (charge schedule, lock, OTA trigger). Returns executed on acknowledgement. Status tracked through CMS command-status events.
retail	AVX Acquire lead_capture / configurator_recommend	Pre-fills a lead record and optionally selects a configurator target. Routes the owner to the Acquire checkout flow on approval.
none	No external call	Advisory Findings with no action path. The Action row is stored for audit; no downstream call is made. Used for Agent 1 range advisories and Agent 3 informational coverage items.
chat	Tier 1 drill-down conversation	Injects avx_finding_id into POST /assistant/chat, pre-seeding the Tier 1 session with the Finding’s evidence[]. The owner taps "Tell me more" and enters a conversation grounded in that specific Finding.
ios-owner	iOS owner inbox and push via broker	For dealer-proposed Findings: the executor writes to the owner’s Action feed table. The broker delivers push and in-app card. Direction: dealer → owner.
cms	CMS Fleet Intelligence API	Records cost actions, groundings (recall or fault) and vehicle moves. Forwards the operator’s token; a rule-approved move goes to an IAM-authorized CMS route signed with AWS SigV4 by the executor’s role.
adp	ADP digital-thread writer (adp-{stage}-digital-thread-writer, us-east-1)	Records a product engineer’s decision in the digital thread and creates the linked draft campaign; a second approval issues it. The writer is the only component that writes thread records.

One policy table (agents/executors/policy.py) holds a row per action_kind: its target system, whether it has a working executor, whether it needs an operator (or, for engineering kinds, a product engineer), whether a rule may auto-approve it, the name of its rule limit, and the parameters AVX sets from the recommendation rather than from the request body. The approve route, the rule API, the rule evaluator and dispatch() all read it, so they cannot disagree.

Guardrails in the dispatch path

Every Action passes through registry.dispatch(), whoever or whatever approved it. Five guardrails run there before any executor:

#	Guardrail	Check
G1	A safety recall is never auto-exempted	exempt_recall with decided_by.kind other than operator is refused
G2	Grounding a vehicle needs the operator	ground_vehicle with decided_by.kind other than operator is refused, for a recall grounding and a stop-driving fault grounding alike
G3	Sending a warranty claim needs the operator	submit_warranty_claim with decided_by.kind other than operator is refused
G4	A recall is never marked complete without a service record	complete_recall is refused, whoever decided, unless parameters.service_record_ref resolves to a completed DMS repair order (Ready, Delivered or Invoiced) for the vehicle
G5	An engineering decision needs a product engineer	record_engineering_decision, issue_recall and issue_software_campaign with decided_by.kind other than engineer are refused, with the sentence "Blocked: engineering decisions need a product engineer."

A missing or malformed decided_by counts as "not an operator" and "not an engineer". G1 to G4 compare against operator, so an engineer cannot pass them. A refused Action is recorded declined with the guardrail’s number in its audit entry; it never reaches an executor and never escalates. The tests name the guarded action kinds literally, and removing either the policy flag or the check makes a test fail.

A recall counts as complete only when a service record says so: a DMS repair order carrying the recall line, or a recall service record in ADP. Every fleet booking carries its campaign, so a booking DMS completes needs no extra step. complete_recall and exempt_recall have no executor; G1 and G4 still guard them in dispatch().

One more check sits in CMS rather than in dispatch(), because CMS records the groundings: the move route refuses any move that includes a grounded vehicle, whoever approved it, a rule included. The rebalancing agent never offers a grounded vehicle in the first place. A grounding also lifts only through a service record: CMS refuses Return to service while a do-not-drive or confirmed safety recall is open, or until a repair order dated after the fault’s latest sighting is recorded for each stop-driving code. A fault that clears by itself does not count.

Auto-approval rules

Rules live in vsa-{stage}-avx-approval-rules (partition key fleet_id, sort key rule_id): the action kind, its limit, enabled, created_by and updated_at. A fleet with no rules auto-approves nothing; a new rule is created disabled; limit defaults come from the auto_approval section of the policy defaults configuration. A rule for a guarded kind, or a kind the policy table marks not auto-approvable, is refused.

The rule evaluator is the second consumer of the findings stream, next to the broker. For a Finding with a recommended_action and a fleet, it loads the fleet’s enabled rules for that kind and checks the limit. On a match it writes an Action (decided_by.kind = rule, decision = auto_approved) with an action_id derived from the Finding, action kind and rule, so a replayed stream record adds nothing, then calls registry.dispatch().

move_vehicles is the auto-approvable fleet kind. The rule’s limit is the largest transfer cost it approves, bounded at $500 by the deployment configuration, and no rule approves more than 5 vehicles in one move. Cost actions, recall and service bookings, groundings, warranty claims and engineering decisions are never auto-approved.

A rule-approved move has no operator token to forward. CmsExecutor sends it to a second CMS route, POST /api/v1/fleet-intelligence/internal/moves, signed with AWS SigV4 by the AVX executor’s IAM role; the API Gateway method uses IAM authorization with a resource policy naming only that role. CMS does not take AVX’s word for it. Before acting, the route reads AVX’s tables to confirm the Action is auto_approved for move_vehicles in the same fleet, that the rule it names exists, is enabled and has a limit at or above the move’s transfer cost, and that the vehicle count is within the bound. Then it runs the same checks as the operator route, including the grounding refusal.

Adding an executor is one class, a policy-table row and an integration test. No supervisor redeploy is required.