# AI caller pilot — routing controls

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md).
Built 2026-10-25. This is the routing portion of T9, not the remaining provider setup UI.

## What it does

The Settings tab of a Retell control profile now has **Pilot split** and **Redial**
controls in both the CRM and Appointment Engine. Saving uses the existing repository's
routing-only path, preserving published content, knowledge, sync stamps, settings hash
and version. It never calls Retell sync or any Yunke API.

No runtime Yunke gate was enabled. A configured split does not make an unavailable
provider ready. The UI says that an unavailable variant's assigned leads are refused,
not silently moved to the other arm. Existing assignments keep their arm through
retries and callbacks. Removing a split does not cancel already submitted phone tasks.

## How it works

The same `RoutingForm.vue` is reused by both Settings tabs. Its complete payload is:

| Field | Meaning |
| --- | --- |
| `split_profile_id` | Second local profile ID, or null to turn the split off |
| `split_pct` | Whole percentage 0–100 when a second profile is selected |
| `redial_attempts` | Total attempts including the first, 2–5, or null |
| `redial_gap` | 30–1440 minutes; both redial fields must be set or both null |

CRM writes to `PUT /manage/calls/ai-profiles/{uuid}/routing`; the Appointment Engine
uses `PUT /manage/appointment-engine/calls/ai-profiles/{uuid}/routing`. Both require
`manage-calls`, in addition to their existing portal/suite permissions. The agency
controller inherits the same action with its existing scoped `profiles()` query.

The controller resolves the control and variant through that query and requires the
same `group_id`. Self, missing, deleted, invisible, cross-agency and already-split
variants are rejected. Candidate page props contain only ID, name, readiness and
whether a split exists. They contain no provider settings, token, Cookie or task ID.
An unavailable candidate may be prepared for a future pilot, with an explicit warning.
A saved target missing from the picker stays in the draft and is shown as an issue;
it cannot be silently cleared by saving a redial edit.

`RoutingRequest` validates the full four-field form. The controller explicitly maps
only `ab_split` and `redial_policy` into the nested repository input. Extra content,
provider, knowledge or credential fields cannot alter the profile through this action.
There is no Save & Sync call. The existing control-policy rule for both pilot arms,
confirmed-miss guards, assignment retention and reporting remain unchanged.

The [paused provisioning/read-only profile view](/docs/modules_handbook/shared/voice-agent/yunke-profiles.md)
now supplies provider-specific configuration/readiness and Retell-only action guards.
Call-list provider and held/queue presentation remains T9 work in the
[PDF ledger](/docs/modules_handbook/shared/voice-agent/yunke-pdf-progress.md). No live pilot is claimed.

## Reference usage

On a control profile's Settings tab, select the second profile and a percentage,
optionally choose total attempts and a gap, then **Save routing**. Select **Off** and
**No redial** to clear both settings. Percent 0 assigns no new leads to the variant;
it does not move leads already assigned. This task exercised that flow only through
synthetic component/HTTP tests, with all runtime gates unchanged.

`AiCallRoutingUiTest` tests both endpoint families, permission/agency boundaries,
validation, explicit mapping and preservation of sync/hash/knowledge with no HTTP or
publishing. `RoutingForm.test.js` checks the exact four-field payload, unavailable and
chained candidates, missing saved targets, clearing redial, saved-prop updates and
read-only permissions. Existing split/redial regressions also pass.

## Related files

- [RoutingRequest](/app/Http/Requests/Manage/Calls/AiProfile/RoutingRequest.php), [AiProfilesController](/app/Http/Controllers/Manage/Calls/AiProfilesController.php), [routes](/routes/web.php) — scoped local writes and validation.
- [RoutingForm.vue](/resources/js/Pages/Manage/Calls/AiProfiles/Partials/RoutingForm.vue) — shared controls, consumed by both suites' SettingsTab/Show/ProfileDetail components.
- [AiCallProfileRepository](/src/VoiceAgent/Repositories/AiCallProfileRepository.php) — unchanged routing-only transactional update.
- [AiCallRoutingUiTest](/tests/Feature/VoiceAgent/AiCallRoutingUiTest.php), [RoutingForm.test.js](/resources/js/Pages/Manage/Calls/AiProfiles/Partials/RoutingForm.test.js) — fake backend and frontend verification.
- [Pilot contracts](/docs/modules_handbook/shared/voice-agent/pilot-routing.md) — existing split, redial, intent alert and report behavior.
