sync: migrate ai-operator to Gitea (2026-08-10)

2026-08-10 15:26:52 +00:00
commit 53652b95ad
173 changed files with 16676 additions and 0 deletions
@@ -0,0 +1,134 @@
+# 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.