Autopilot

Deterministic state machine. The orchestrator that decides when to run the other agents, what the entry's next legal action is, and when the broker must take the wheel. Single source of truth for entry state.

What it does

Walks every entry through its lifecycle: draft → ai_review → ready → filed → cleared (or → exam, → hold, → released). At each transition it decides:

1. Which agents to run at this state (classifier? screener? duty calc?)
2. Whether the entry can advance autonomously or needs broker review
3. What the next legal action is (classify / approve / transmit / respond_to_exam …)
4. What gets logged to the activity stream for the audit trail

The "Autopilot on / auto ≥ 92%" toggle in the top bar is just the confidence threshold this state machine uses to decide whether to auto- approve a line in ai_review or hold it for broker review.

This is not an LLM agent. State transitions in customs work must be deterministic, reproducible, and challenge-able in a CBP audit. Every state change is logged with the action that caused it, the agent (system / broker / state-machine / autopilot), and a timestamp.

Inputs

{
  shipmentId: string,
  action: 'classify' | 'screen' | 'approve' | 'override' | 'transmit'
        | 'respond_to_exam' | 'release' | 'clear',
  byAgent: 'broker' | 'autopilot' | 'system' | 'state-machine',
  context?: {                       // varies by action
    confidence?: number,
    overrideReason?: string,
    dismissalReason?: string,
    transmittedAt?: string,
  },
}

Outputs

{
  ok: true,
  prevStatus: 'ai_review',
  status: 'ready',
  legalActions: ['transmit'],       // what can come next
  reason: 'Autopilot approved — confidence 94% ≥ threshold 92%',
  loggedActivityId: 'act_...',
}

Or, on a blocked transition:

{
  ok: false,
  reason: 'Cannot advance ai_review → ready: 1 blocking screening hit (UFLPA)',
  blockers: [{ kind: 'screening', hitId: '...', mustResolve: 'dismiss-with-reason' }],
}

For the canonical reference of every status (what it means, what moves it forward, how Dashboard filters map to it), see Entry statuses, explained. The visual workflow this state machine implements is the visual workflow.

State diagram

                    ┌──────────────────────────┐
                    │       draft              │   created from a doc / PO / manual
                    └─────────────┬────────────┘
                                  │ classify + screen (auto)
                                  ▼
                    ┌──────────────────────────┐
                    │      ai_review           │   agents have run, broker assessing
                    └──────┬───────────────────┘
                           │
                ┌──────────┴──────────┐
                ▼                     ▼
  Autopilot auto-approve    Broker approves / overrides
   (conf ≥ threshold,         (always allowed)
    no blocking screening)
                │                     │
                └──────────┬──────────┘
                           ▼
                    ┌──────────────────────────┐
                    │       ready              │   ready to file (transmit ABI)
                    └─────────────┬────────────┘
                                  │ transmit
                                  ▼
                    ┌──────────────────────────┐
                    │       filed              │   CBP has the entry summary
                    └────┬────────────────┬────┘
                         │                │
                         ▼                ▼
                ┌────────────┐    ┌────────────┐
                │   exam     │    │   hold     │   CBP escalation
                └────┬───────┘    └────┬───────┘
                     │ respond_to_exam │ release
                     ▼                 ▼
                ┌──────────────────────────────┐
                │       cleared / released     │   terminal
                └──────────────────────────────┘

When it runs

• On every action taken against an entry — by a broker (drawer button), by a service (extractor finishes), by a scheduler (timeout escalation), or by an upstream event (CBP CSMS message — planned).
• At ingest time — when a new shipment is ingested via the shipments/ingest endpoint or the document inbox.

Autopilot threshold logic

The top-bar "Autopilot on / auto ≥ 92%" surfaces the org-level auto-approval threshold. The state machine reads this when deciding whether ai_review → ready is autonomous:

auto-approve ai_review → ready  IFF
  every line.confidence ≥ threshold
  AND no blocking screening hits exist
  AND no pending PGA filings (FDA / FCC / CPSC / USDA)
  AND duty stack effective rate ≤ org's "auto-approve cap" (e.g. 50%)

If any condition fails, the entry stays in ai_review and is surfaced in "Needs review" on the dashboard.

Dependencies

• All other agents — Autopilot calls the Classifier, Screener, Duty Calculator, and Risk Modeler at the right transition.

What success looks like

What it does NOT do

• Does NOT decide what to classify or how to screen — it just calls the right agents at the right transition.
• Does NOT transmit to CBP today. The transmit action moves the entry to filed and produces the ACE message envelope, but doesn't yet POST to CBP's network. Planned.
• Does NOT auto-respond to CBP exams or holds — those always require a broker. The state machine surfaces the legal next action; the broker takes it.
• Does NOT roll back transitions. Once filed, the way out is forward (cleared / released / exam / hold) — undo would require a Post Entry Amendment, which is a separate workflow.

Roadmap

• Planned — Wire transmit to actually POST the ACE message envelope to CBP's network. Requires bond + carrier code.
• Q4 2026 — CBP CSMS message ingestion → automatic state transition when a hold is released or an exam is scheduled.
• Q4 2026 — Org-level Autopilot policy (different thresholds for different importers, different duty caps, different chapter rules).
• Q1 2027 — Org-level auto-approve caps by duty exposure (e.g. "auto-approve only when total duty ≤ $50K"); already designed in the state machine, just not surfaced in the UI yet.