# Human Handoff / Fallback

TZ-11 adds a safe Human Handoff and fallback layer. The default behavior is intentionally non-transferring.

## Purpose

Human handoff gives the AI operator a controlled way to react when the caller asks for a live operator or when automated service cannot safely continue.

## Default Behavior

Default configuration:

```env
HANDOFF_MODE=disabled_stub
HANDOFF_ENABLED=false
HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY=true
```

With these defaults:

- no real transfer is attempted;
- `request_human_handoff` creates a structured request;
- conversation state moves to `HANDOFF`;
- the caller receives a safe message that direct transfer is not connected yet.

## Handoff Modes

- `disabled_stub`: records the request and returns a safe message. No ARI transfer.
- `ari_redirect`: uses ARI channel redirect when explicitly enabled and configured.
- `dialplan_continue`: returns the channel to dialplan when explicitly enabled and configured.
- `hangup_after_message`: returns a final message and moves toward closing without transfer.

Real transfer modes require `HANDOFF_ENABLED=true` and valid target fields. Production routes remain protected.

## Config Variables

- `HANDOFF_MODE`
- `HANDOFF_ENABLED`
- `HANDOFF_TARGET_ENDPOINT`
- `HANDOFF_DIALPLAN_CONTEXT`
- `HANDOFF_DIALPLAN_EXTENSION`
- `HANDOFF_DIALPLAN_PRIORITY`
- `HANDOFF_QUEUE_NAME`
- `HANDOFF_TIMEOUT`
- `HANDOFF_MAX_ATTEMPTS`
- `HANDOFF_PLAY_MESSAGE_BEFORE_TRANSFER`
- `HANDOFF_HANGUP_AFTER_STUB`
- `HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY`
- `HANDOFF_MAX_SUMMARY_CHARS`

Fallback thresholds:

- `FALLBACK_MAX_LANGUAGE_FAILURES`
- `FALLBACK_MAX_REGION_FAILURES`
- `FALLBACK_MAX_NO_ANSWER`
- `FALLBACK_MAX_KB_UNAVAILABLE`
- `FALLBACK_MAX_AI_ERRORS`
- `FALLBACK_MAX_MEDIA_ERRORS`
- `FALLBACK_MAX_TOOL_ERRORS`
- `FALLBACK_CALL_TIMEOUT`

## Detector Phrases

The handoff detector supports Russian, Kazakh, and mixed/Latin phrases such as:

- `оператор`
- `соедините с оператором`
- `хочу поговорить с человеком`
- `операторға қосыңыз`
- `маман керек`
- `live agent`
- `speak to human`

Ambiguous business phrases such as `оператор связи` are not treated as confident handoff requests.

## Fallback Scenarios

Fallback manager can offer handoff or safe closing for:

- KB unavailable;
- repeated no-answer;
- repeated language failures;
- repeated region failures;
- AI provider error;
- media error;
- tool error;
- call timeout.

## ARI Redirect Mode

`ari_redirect` calls:

```text
POST /ari/channels/{channelId}/redirect?endpoint={endpoint}
```

It is only used when enabled and configured. Required tests use fake/httptest clients.

## Dialplan Continue Mode

`dialplan_continue` calls:

```text
POST /ari/channels/{channelId}/continue?context={context}&extension={extension}&priority={priority}
```

It is only used when enabled and configured.

## Production Route

Production routes remain disabled. `HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY=true` prevents real transfer outside the test route.

## Safe Tests

```bash
./bin/ai-operator doctor --env /etc/ai-operator/ai-operator.env --check-handoff
./bin/ai-operator handoff-self-test --env /etc/ai-operator/ai-operator.env
./bin/ai-operator fallback-self-test --env /etc/ai-operator/ai-operator.env
```

These commands do not perform real transfer.

## Not Implemented Yet

- real operator queue/extension;
- production handoff enablement;
- call transcript persistence;
- CRM ticket creation;
- operator schedule/availability checks.


## Audit Integration

Handoff requests write `ai_handoff_audit` records with redacted summaries and transfer status. Default `disabled_stub` does not attempt real transfer.