@agentunion/kite 1.0.7 → 1.2.0

package/extensions/services/web/vendor/task/manager.py

@@ -0,0 +1,864 @@
+"""Task manager — orchestrates the complete lifecycle of outgoing and incoming calls."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from .. import config as cfg
+from ..storage import store
+from ..storage import identity
+from .models import CallDirection, CallResult, EndedReason, TaskStatus
+from .webhook import WebhookClient
+
+logger = logging.getLogger(__name__)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class TaskManager:
+    """Central coordinator for call tasks.
+
+    Manages the lifecycle of both outgoing and incoming calls, bridging the
+    Bluetooth telephony layer, the AI conversation engine, and webhook
+    notifications.
+
+    Parameters
+    ----------
+    bt_manager:
+        An instance of :class:`bluetooth.manager.BluetoothManager` that
+        provides access to the telephony and audio sub-systems.
+    """
+
+    def __init__(self, bt_manager: Any) -> None:
+        self.bt_manager = bt_manager
+        self.webhook = WebhookClient()
+        self.active_tasks: dict[str, dict[str, Any]] = {}
+        self._engines: dict[str, Any] = {}  # task_id -> ConversationEngine
+        self._background_tasks: dict[str, asyncio.Task[None]] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def create_call_task(self, request: Any) -> dict[str, Any]:
+        """Create a new **outgoing** call task.
+
+        Workflow
+        --------
+        1. Generate ``task_id`` (UUID4) and persist the task record.
+        2. If ``phone_number`` is already provided, jump to step 4.
+        3. If only ``purpose`` is given:
+           a. Use LLM to search the contact list for the best match.
+           b. If ``require_confirmation`` is true, send a
+              ``contact_confirmation`` webhook, set status to *confirming*,
+              and return immediately so the caller can confirm.
+           c. Otherwise, use the best match directly.
+        4. Launch ``_run_call`` as a background coroutine.
+        5. Return ``{task_id, status}``.
+        """
+        # Accept both Pydantic model and plain dict
+        if hasattr(request, "model_dump"):
+            req = request.model_dump()
+        elif isinstance(request, dict):
+            req = request
+        else:
+            req = dict(request)
+        task_id = str(uuid.uuid4())
+
+        task: dict[str, Any] = {
+            "task_id": task_id,
+            "phone_number": req.get("phone_number"),
+            "contact_name": req.get("contact_name"),
+            "user_phone": identity.get_user_phone(),
+            "purpose": req.get("purpose", ""),
+            "system_prompt": req.get("system_prompt", ""),
+            "webhook_url": req.get("webhook_url", ""),
+            "max_duration_seconds": req.get(
+                "max_duration_seconds",
+                cfg.get("call.max_duration_seconds", 300),
+            ),
+            "language": req.get("language", "zh"),
+            "play_text": req.get("play_text"),
+            "require_confirmation": req.get("require_confirmation", False),
+            "direction": CallDirection.OUTGOING.value,
+            "status": TaskStatus.QUEUED.value,
+            "result": None,
+            "ended_reason": None,
+            "duration_seconds": 0,
+            "summary": "",
+            "has_recording": False,
+            "started_at": _now_iso(),
+            "ended_at": None,
+        }
+
+        # Persist initial record
+        await store.save_task(task)
+        self.active_tasks[task_id] = task
+
+        # --- Contact resolution (when phone_number is absent) -----------
+        if not task["phone_number"] and task["purpose"]:
+            matched = await self._find_contact_for_purpose(task["purpose"])
+            if matched:
+                task["contact_name"] = matched.get("name")
+                task["contact_info"] = {
+                    "id": matched.get("id"),
+                    "company": matched.get("company"),
+                    "phone": matched.get("phone"),
+                }
+
+                if task["require_confirmation"]:
+                    task["status"] = TaskStatus.CONFIRMING.value
+                    await store.update_task(task_id, {"status": task["status"]})
+                    # Fire-and-forget the webhook; the caller will confirm
+                    # through POST /api/call/{task_id}/confirm later.
+                    asyncio.create_task(
+                        self.webhook.request_contact_confirmation(task, matched)
+                    )
+                    return {"task_id": task_id, "status": task["status"]}
+
+                # No confirmation needed — use the match directly.
+                task["phone_number"] = matched.get("phone")
+                await store.update_task(task_id, {
+                    "phone_number": task["phone_number"],
+                    "contact_name": task["contact_name"],
+                })
+            else:
+                # Could not find a matching contact.
+                task["status"] = TaskStatus.FAILED.value
+                task["result"] = CallResult.ERROR.value
+                task["ended_reason"] = EndedReason.ERROR.value
+                task["ended_at"] = _now_iso()
+                await store.update_task(task_id, {
+                    "status": task["status"],
+                    "result": task["result"],
+                    "ended_reason": task["ended_reason"],
+                    "ended_at": task["ended_at"],
+                })
+                self.active_tasks.pop(task_id, None)
+                return {"task_id": task_id, "status": task["status"]}
+
+        if not task["phone_number"]:
+            task["status"] = TaskStatus.FAILED.value
+            task["result"] = CallResult.ERROR.value
+            task["ended_reason"] = EndedReason.ERROR.value
+            task["ended_at"] = _now_iso()
+            await store.update_task(task_id, {
+                "status": task["status"],
+                "result": task["result"],
+                "ended_reason": task["ended_reason"],
+                "ended_at": task["ended_at"],
+            })
+            self.active_tasks.pop(task_id, None)
+            return {"task_id": task_id, "status": task["status"]}
+
+        # --- Start the call in the background --------------------------
+        bg = asyncio.create_task(self._run_call(task_id))
+        self._background_tasks[task_id] = bg
+        bg.add_done_callback(lambda _t: self._background_tasks.pop(task_id, None))
+
+        return {"task_id": task_id, "status": task["status"]}
+
+    async def confirm_task(self, task_id: str, request: Any) -> dict[str, Any]:
+        """Handle a confirmation response for a task.
+
+        Two flavours:
+        - **Contact confirmation** — ``action="confirm"`` with an optional
+          ``phone_number`` override.  Triggers the outgoing call.
+        - **Incoming-call answer** — ``action="answer"`` or ``"reject"``.
+        """
+        # Accept both Pydantic model and plain dict
+        if hasattr(request, "model_dump"):
+            req = request.model_dump()
+        elif isinstance(request, dict):
+            req = request
+        else:
+            req = dict(request)
+
+        task = self.active_tasks.get(task_id)
+        if not task:
+            task = await store.get_task(task_id)
+        if not task:
+            return {"error": "task_not_found"}
+
+        action = req.get("action", "confirm")
+
+        # --- Contact confirmation (outgoing) ---------------------------
+        if action == "confirm":
+            phone_number = req.get("phone_number") or task.get("phone_number")
+            if not phone_number:
+                # Try from contact_info
+                phone_number = (task.get("contact_info") or {}).get("phone")
+            if not phone_number:
+                return {"error": "phone_number_required"}
+
+            task["phone_number"] = phone_number
+            task["status"] = TaskStatus.QUEUED.value
+            if req.get("system_prompt"):
+                task["system_prompt"] = req["system_prompt"]
+            if req.get("purpose"):
+                task["purpose"] = req["purpose"]
+
+            await store.update_task(task_id, {
+                "phone_number": phone_number,
+                "status": task["status"],
+                "system_prompt": task.get("system_prompt", ""),
+                "purpose": task.get("purpose", ""),
+            })
+            self.active_tasks[task_id] = task
+
+            # Resolve any pending webhook future
+            self.webhook.resolve_confirmation(task_id, "confirmed")
+
+            # Launch the call
+            bg = asyncio.create_task(self._run_call(task_id))
+            self._background_tasks[task_id] = bg
+            bg.add_done_callback(lambda _t: self._background_tasks.pop(task_id, None))
+
+            return {"task_id": task_id, "status": task["status"]}
+
+        # --- Incoming-call answer / reject -----------------------------
+        if action == "answer":
+            if req.get("system_prompt"):
+                task["system_prompt"] = req["system_prompt"]
+            if req.get("purpose"):
+                task["purpose"] = req["purpose"]
+
+            task["status"] = TaskStatus.ACTIVE.value
+            await store.update_task(task_id, {"status": task["status"]})
+            self.active_tasks[task_id] = task
+
+            # Resolve the pending incoming-call confirmation future
+            self.webhook.resolve_confirmation(task_id, "answer")
+
+            return {"task_id": task_id, "status": task["status"]}
+
+        if action == "reject":
+            task["status"] = TaskStatus.CANCELLED.value
+            task["result"] = CallResult.REJECTED.value
+            task["ended_reason"] = EndedReason.CANCELLED.value
+            task["ended_at"] = _now_iso()
+            await store.update_task(task_id, {
+                "status": task["status"],
+                "result": task["result"],
+                "ended_reason": task["ended_reason"],
+                "ended_at": task["ended_at"],
+            })
+            self.active_tasks.pop(task_id, None)
+
+            # Resolve the pending incoming-call confirmation future
+            self.webhook.resolve_confirmation(task_id, "reject")
+
+            return {"task_id": task_id, "status": task["status"]}
+
+        return {"error": f"unknown_action: {action}"}
+
+    async def hangup_task(self, task_id: str) -> dict[str, Any]:
+        """Force-hangup a task that is currently in progress."""
+        task = self.active_tasks.get(task_id)
+        if not task:
+            task = await store.get_task(task_id)
+        if not task:
+            return {"error": "task_not_found"}
+
+        # Stop the conversation engine if running
+        engine = self._engines.pop(task_id, None)
+        if engine is not None:
+            try:
+                await engine.stop()
+            except Exception:
+                logger.exception("Error stopping conversation engine for %s", task_id)
+
+        # Instruct telephony to hang up
+        try:
+            if hasattr(self.bt_manager, "telephony") and self.bt_manager.telephony:
+                await self.bt_manager.telephony.hangup()
+        except Exception:
+            logger.exception("Error sending HFP hangup for %s", task_id)
+
+        # Cancel background task
+        bg = self._background_tasks.pop(task_id, None)
+        if bg and not bg.done():
+            bg.cancel()
+
+        task["status"] = TaskStatus.COMPLETED.value
+        task["result"] = CallResult.SUCCESS.value
+        task["ended_reason"] = EndedReason.AI_HANGUP.value
+        task["ended_at"] = _now_iso()
+
+        if task.get("started_at"):
+            try:
+                start = datetime.fromisoformat(task["started_at"])
+                end = datetime.fromisoformat(task["ended_at"])
+                task["duration_seconds"] = int((end - start).total_seconds())
+            except (ValueError, TypeError):
+                pass
+
+        await store.update_task(task_id, {
+            "status": task["status"],
+            "result": task["result"],
+            "ended_reason": task["ended_reason"],
+            "ended_at": task["ended_at"],
+            "duration_seconds": task.get("duration_seconds", 0),
+        })
+        self.active_tasks.pop(task_id, None)
+
+        # Notify via webhook
+        asyncio.create_task(self.webhook.notify_call_completed(task))
+
+        return {"task_id": task_id, "status": task["status"]}
+
+    async def send_message(self, task_id: str, message: str) -> dict[str, Any]:
+        """Inject a caller message into an active conversation.
+
+        This also resolves any pending ``in_call_confirmation`` webhook
+        future so that the conversation engine can resume.
+        """
+        task = self.active_tasks.get(task_id)
+        if not task:
+            return {"error": "task_not_found"}
+
+        # Resolve pending webhook confirmation (if any)
+        self.webhook.resolve_confirmation(task_id, message)
+
+        # Forward to the conversation engine
+        engine = self._engines.get(task_id)
+        if engine is not None:
+            try:
+                await engine.inject_message(message)
+            except Exception:
+                logger.exception("Error injecting message into engine for %s", task_id)
+
+        # Persist the message as a call event
+        call_dir_path = task.get("call_dir")
+        if call_dir_path:
+            from pathlib import Path
+            await identity.save_call_message(Path(call_dir_path), {
+                "role": "caller",
+                "text": message,
+                "timestamp": _now_iso(),
+            })
+
+        return {"task_id": task_id, "status": "message_sent"}
+
+    # ------------------------------------------------------------------
+    # Incoming call handling
+    # ------------------------------------------------------------------
+
+    async def handle_incoming_call(self, phone_number: str) -> None:
+        """Called by the telephony layer when an incoming call is detected.
+
+        Workflow
+        --------
+        1. Look up the caller in the contact list.
+        2. Create a task record with ``direction=incoming``.
+        3. Send an ``incoming_call`` webhook notification.
+        4. Wait for the caller to confirm (answer/reject) or timeout.
+        5. Answer or reject the call based on the response / default policy.
+        """
+        # 1. Contact lookup
+        contact = await store.find_contact_by_phone(phone_number)
+        contact_name = contact["name"] if contact else None
+        contact_info: dict[str, Any] | None = None
+        if contact:
+            contact_info = {
+                "company": contact.get("company"),
+                "title": contact.get("title"),
+                "notes": contact.get("notes"),
+            }
+
+        # 2. Create task
+        task_id = str(uuid.uuid4())
+        task: dict[str, Any] = {
+            "task_id": task_id,
+            "phone_number": phone_number,
+            "contact_name": contact_name,
+            "contact_info": contact_info,
+            "user_phone": identity.get_user_phone(),
+            "purpose": "",
+            "system_prompt": "",
+            "webhook_url": cfg.get("webhook.default_url", ""),
+            "direction": CallDirection.INCOMING.value,
+            "status": TaskStatus.ALERTING.value,
+            "result": None,
+            "ended_reason": None,
+            "duration_seconds": 0,
+            "summary": "",
+            "has_recording": False,
+            "started_at": _now_iso(),
+            "ended_at": None,
+        }
+        await store.save_task(task)
+        self.active_tasks[task_id] = task
+
+        # 3. Webhook notification
+        confirmation = await self.webhook.notify_incoming_call(task)
+
+        # 4. Decide whether to answer
+        default_action = cfg.get("call.incoming_default_action", "reject")
+        action = "reject"
+        if confirmation and confirmation.get("response") == "answer":
+            action = "answer"
+        elif confirmation is None:
+            action = default_action
+
+        # 5. Answer or reject
+        if action == "answer":
+            task["status"] = TaskStatus.ACTIVE.value
+            await store.update_task(task_id, {"status": task["status"]})
+
+            try:
+                if hasattr(self.bt_manager, "telephony") and self.bt_manager.telephony:
+                    await self.bt_manager.telephony.answer()
+            except Exception:
+                logger.exception("Error answering incoming call %s", task_id)
+                task["status"] = TaskStatus.FAILED.value
+                task["result"] = CallResult.ERROR.value
+                task["ended_reason"] = EndedReason.ERROR.value
+                task["ended_at"] = _now_iso()
+                await store.update_task(task_id, {
+                    "status": task["status"],
+                    "result": task["result"],
+                    "ended_reason": task["ended_reason"],
+                    "ended_at": task["ended_at"],
+                })
+                self.active_tasks.pop(task_id, None)
+                return
+
+            # Start the call pipeline in the background
+            bg = asyncio.create_task(self._run_active_call(task_id))
+            self._background_tasks[task_id] = bg
+            bg.add_done_callback(lambda _t: self._background_tasks.pop(task_id, None))
+        else:
+            # Reject the call
+            try:
+                if hasattr(self.bt_manager, "telephony") and self.bt_manager.telephony:
+                    await self.bt_manager.telephony.hangup()
+            except Exception:
+                logger.exception("Error rejecting incoming call %s", task_id)
+
+            task["status"] = TaskStatus.CANCELLED.value
+            task["result"] = CallResult.REJECTED.value
+            task["ended_reason"] = EndedReason.CANCELLED.value
+            task["ended_at"] = _now_iso()
+            await store.update_task(task_id, {
+                "status": task["status"],
+                "result": task["result"],
+                "ended_reason": task["ended_reason"],
+                "ended_at": task["ended_at"],
+            })
+            self.active_tasks.pop(task_id, None)
+
+    # ------------------------------------------------------------------
+    # Internal — run a complete outgoing call
+    # ------------------------------------------------------------------
+
+    async def _run_call(self, task_id: str) -> None:
+        """Background coroutine that runs a complete **outgoing** call.
+
+        Steps
+        -----
+        1. Verify Bluetooth is connected.
+        2. Dial the number via telephony.
+        3. Wait for the remote party to answer (poll call state).
+        4. Start the audio pipeline.
+        5. Create and start the ``ConversationEngine``.
+        6. Wait for completion (or max duration).
+        7. Generate a call summary via LLM.
+        8. Persist all records.
+        9. Send ``call_completed`` webhook.
+        """
+        task = self.active_tasks.get(task_id)
+        if not task:
+            logger.error("_run_call: task %s not found", task_id)
+            return
+
+        try:
+            # 1. Bluetooth readiness check
+            task["status"] = TaskStatus.CONNECTING.value
+            await store.update_task(task_id, {"status": task["status"]})
+
+            if not self._is_bluetooth_connected():
+                logger.warning("Bluetooth not connected for task %s", task_id)
+                await self._fail_task(task_id, CallResult.ERROR, EndedReason.ERROR)
+                return
+
+            # 2. Dial the number
+            task["status"] = TaskStatus.DIALING.value
+            await store.update_task(task_id, {"status": task["status"]})
+
+            try:
+                if hasattr(self.bt_manager, "telephony") and self.bt_manager.telephony:
+                    await self.bt_manager.telephony.dial(task["phone_number"])
+                else:
+                    logger.error("Telephony subsystem unavailable for task %s", task_id)
+                    await self._fail_task(task_id, CallResult.ERROR, EndedReason.ERROR)
+                    return
+            except Exception:
+                logger.exception("Dial failed for task %s", task_id)
+                await self._fail_task(task_id, CallResult.ERROR, EndedReason.ERROR)
+                return
+
+            # 3. Wait for the remote party to answer
+            task["status"] = TaskStatus.ALERTING.value
+            await store.update_task(task_id, {"status": task["status"]})
+
+            call_answered = await self._wait_for_answer(task_id)
+            if not call_answered:
+                # _wait_for_answer already updated the task status
+                return
+
+            # 4–6. Run the active call phase
+            await self._run_active_call(task_id)
+
+        except asyncio.CancelledError:
+            logger.info("Call task %s was cancelled", task_id)
+            await self._fail_task(task_id, CallResult.ERROR, EndedReason.CANCELLED)
+        except Exception:
+            logger.exception("Unexpected error in _run_call for %s", task_id)
+            await self._fail_task(task_id, CallResult.ERROR, EndedReason.ERROR)
+
+    async def _run_active_call(self, task_id: str) -> None:
+        """Run the audio + AI pipeline once a call is connected (active).
+
+        Shared between outgoing and incoming call flows.
+        """
+        task = self.active_tasks.get(task_id)
+        if not task:
+            return
+
+        task["status"] = TaskStatus.ACTIVE.value
+        await store.update_task(task_id, {"status": task["status"]})
+
+        # Create identity-based call directory
+        user_phone = task.get("user_phone", "")
+        contact_phone = task.get("phone_number", "")
+        started_at = task.get("started_at", _now_iso())
+        if user_phone and contact_phone:
+            # Ensure contact profile.yaml exists (auto-creates on first call,
+            # pulls owner name from config user.owners if available)
+            identity.ensure_contact_profile(
+                user_phone, contact_phone,
+                contact_name=task.get("contact_name"),
+            )
+            call_path = identity.ensure_call_dir(user_phone, contact_phone, started_at)
+            task["call_dir"] = str(call_path)
+            await store.update_task(task_id, {"call_dir": str(call_path)})
+        else:
+            task["call_dir"] = None
+
+        engine = None
+        try:
+            # 4. Start audio pipeline
+            audio_stream = None
+            if hasattr(self.bt_manager, "audio") and self.bt_manager.audio:
+                audio_stream = await self.bt_manager.audio.start()
+
+            # 5. Create conversation engine
+            try:
+                from conversation.engine import ConversationEngine
+                engine = ConversationEngine(
+                    audio_pipeline=audio_stream,
+                    task_info=task,
+                    webhook_client=self.webhook,
+                )
+                self._engines[task_id] = engine
+                await engine.start()  # blocks until conversation ends
+            except ImportError:
+                logger.warning(
+                    "ConversationEngine not available; call %s will run "
+                    "without AI (telephony only)",
+                    task_id,
+                )
+            except Exception:
+                logger.exception("Failed to start ConversationEngine for %s", task_id)
+
+            ended_reason = EndedReason.NORMAL
+
+        except asyncio.CancelledError:
+            ended_reason = EndedReason.CANCELLED
+        except Exception:
+            logger.exception("Error during active call %s", task_id)
+            ended_reason = EndedReason.ERROR
+        finally:
+            # Clean up engine
+            if engine:
+                try:
+                    await engine.stop()
+                except Exception:
+                    pass
+            self._engines.pop(task_id, None)
+
+            # Stop audio pipeline
+            if hasattr(self.bt_manager, "audio") and self.bt_manager.audio:
+                try:
+                    await self.bt_manager.audio.stop()
+                except Exception:
+                    pass
+
+        # 7. Generate summary
+        summary = ""
+        try:
+            call_dir_str = task.get("call_dir")
+            transcript = []
+            if call_dir_str:
+                from pathlib import Path
+                transcript = await identity.load_call_messages(Path(call_dir_str))
+            if transcript:
+                summary = await self._generate_summary(task, transcript)
+        except Exception:
+            logger.exception("Failed to generate summary for %s", task_id)
+
+        # 8. Persist final records
+        task["status"] = TaskStatus.COMPLETED.value
+        task["result"] = CallResult.SUCCESS.value
+        task["ended_reason"] = ended_reason.value if isinstance(ended_reason, EndedReason) else ended_reason
+        task["ended_at"] = _now_iso()
+        task["summary"] = summary
+        task["has_recording"] = cfg.get("audio.record_calls", True)
+
+        if task.get("started_at"):
+            try:
+                start = datetime.fromisoformat(task["started_at"])
+                end = datetime.fromisoformat(task["ended_at"])
+                task["duration_seconds"] = int((end - start).total_seconds())
+            except (ValueError, TypeError):
+                pass
+
+        # Save session.json and summary.md to identity directory
+        call_dir_path = task.get("call_dir")
+        if call_dir_path:
+            from pathlib import Path
+            cd = Path(call_dir_path)
+            try:
+                session_info = {
+                    "task_id": task_id,
+                    "direction": task.get("direction", ""),
+                    "phone_number": task.get("phone_number", ""),
+                    "contact_name": task.get("contact_name", ""),
+                    "started_at": task.get("started_at", ""),
+                    "ended_at": task.get("ended_at", ""),
+                    "duration_seconds": task.get("duration_seconds", 0),
+                    "result": task.get("result", ""),
+                    "llm_provider": cfg.get("llm.active_provider", ""),
+                    "llm_model": cfg.get(f"llm.providers.{cfg.get('llm.active_provider', 'openai')}.model", ""),
+                    "asr_provider": cfg.get("asr.provider", ""),
+                    "tts_provider": cfg.get("tts.provider", ""),
+                    "system_prompt": task.get("system_prompt", ""),
+                }
+                await identity.save_session_info(cd, session_info)
+            except Exception:
+                logger.exception("Failed to save session info for %s", task_id)
+
+            if summary:
+                try:
+                    await identity.save_call_summary(cd, summary)
+                except Exception:
+                    logger.exception("Failed to save identity summary for %s", task_id)
+
+        await store.update_task(task_id, {
+            "status": task["status"],
+            "result": task["result"],
+            "ended_reason": task["ended_reason"],
+            "ended_at": task["ended_at"],
+            "duration_seconds": task.get("duration_seconds", 0),
+            "summary": summary,
+            "has_recording": task["has_recording"],
+        })
+
+        self.active_tasks.pop(task_id, None)
+
+        # 9. Webhook notification
+        call_dir_str = task.get("call_dir")
+        if call_dir_str:
+            from pathlib import Path
+            task["transcript"] = await identity.load_call_messages(Path(call_dir_str))
+        else:
+            task["transcript"] = []
+        await self.webhook.notify_call_completed(task)
+
+    # ------------------------------------------------------------------
+    # Internal — helpers
+    # ------------------------------------------------------------------
+
+    def _is_bluetooth_connected(self) -> bool:
+        """Check whether the Bluetooth HFP connection is up."""
+        if hasattr(self.bt_manager, "connected"):
+            return bool(self.bt_manager.connected)
+        return True  # assume connected if we cannot check
+
+    async def _wait_for_answer(self, task_id: str, poll_interval: float = 0.5) -> bool:
+        """Poll the telephony layer until the call is answered or fails.
+
+        Updates the task status on failure and returns ``False`` in that case.
+        """
+        max_ring_seconds = 60
+        elapsed = 0.0
+
+        while elapsed < max_ring_seconds:
+            if not hasattr(self.bt_manager, "telephony") or not self.bt_manager.telephony:
+                await asyncio.sleep(poll_interval)
+                elapsed += poll_interval
+                continue
+
+            state = None
+            try:
+                state = await self.bt_manager.telephony.get_call_state()
+            except Exception:
+                pass
+
+            if state == "active":
+                return True
+            if state in ("disconnected", "idle", None) and elapsed > 2:
+                # Call ended before being answered
+                await self._fail_task(task_id, CallResult.NO_ANSWER, EndedReason.REMOTE_HANGUP)
+                return False
+            if state == "busy":
+                await self._fail_task(task_id, CallResult.BUSY, EndedReason.REMOTE_HANGUP)
+                return False
+
+            await asyncio.sleep(poll_interval)
+            elapsed += poll_interval
+
+        # Timed out — no answer
+        await self._fail_task(task_id, CallResult.NO_ANSWER, EndedReason.TIMEOUT)
+        return False
+
+    async def _fail_task(
+        self,
+        task_id: str,
+        result: CallResult,
+        ended_reason: EndedReason,
+    ) -> None:
+        """Mark a task as failed and persist the update."""
+        task = self.active_tasks.get(task_id)
+        if not task:
+            task = await store.get_task(task_id) or {}
+
+        task["status"] = TaskStatus.FAILED.value
+        task["result"] = result.value
+        task["ended_reason"] = ended_reason.value
+        task["ended_at"] = _now_iso()
+
+        await store.update_task(task_id, {
+            "status": task["status"],
+            "result": task["result"],
+            "ended_reason": task["ended_reason"],
+            "ended_at": task["ended_at"],
+        })
+
+        self.active_tasks.pop(task_id, None)
+
+        # Notify webhook
+        asyncio.create_task(self.webhook.notify_call_completed(task))
+
+    async def _find_contact_for_purpose(self, purpose: str) -> dict[str, Any] | None:
+        """Use the configured LLM to find the best contact match for *purpose*.
+
+        Loads all contacts, builds a prompt asking the LLM to pick the best
+        match, and returns the selected contact dict (with an extra
+        ``confidence`` key) or ``None`` if no reasonable match is found.
+        """
+        import json
+
+        contacts, _ = await store.list_contacts(page=1, page_size=500)
+        if not contacts:
+            logger.info("No contacts in address book; cannot match for purpose")
+            return None
+
+        # Build a compact contact list for the LLM
+        contacts_text = "\n".join(
+            f"- id={c.get('id')} name={c.get('name')} phone={c.get('phone')} "
+            f"company={c.get('company', '')} title={c.get('title', '')} "
+            f"notes={c.get('notes', '')} tags={c.get('tags', [])}"
+            for c in contacts
+        )
+
+        prompt = (
+            "You are a contact-matching assistant. Given the following purpose "
+            "and a list of contacts, select the single best matching contact.\n\n"
+            f"Purpose: {purpose}\n\n"
+            f"Contacts:\n{contacts_text}\n\n"
+            "Respond with ONLY a JSON object: "
+            '{"id": "<contact_id>", "confidence": <0.0-1.0>}\n'
+            "If no contact is a reasonable match, respond: "
+            '{"id": null, "confidence": 0}'
+        )
+
+        try:
+            from conversation.llm import create_llm_provider
+
+            provider = create_llm_provider()
+            result = await provider.generate(
+                messages=[{"role": "user", "content": prompt}],
+            )
+            response_text = result.get("content", "")
+
+            result_json = json.loads(response_text)
+            contact_id = result_json.get("id")
+            confidence = result_json.get("confidence", 0)
+
+            if not contact_id or confidence < 0.3:
+                logger.info("LLM contact match confidence too low (%.2f)", confidence)
+                return None
+
+            matched = await store.get_contact(contact_id)
+            if matched:
+                matched["confidence"] = confidence
+                return matched
+
+        except ImportError:
+            logger.warning("LLM module not available; falling back to text search")
+            # Fallback: simple keyword search
+            results = await store.search_contacts(purpose)
+            if results:
+                results[0]["confidence"] = 0.5
+                return results[0]
+        except (json.JSONDecodeError, KeyError, TypeError):
+            logger.exception("Failed to parse LLM contact match response")
+        except Exception:
+            logger.exception("Error during LLM contact matching")
+
+        return None
+
+    async def _generate_summary(
+        self,
+        task: dict[str, Any],
+        transcript: list[dict[str, Any]],
+    ) -> str:
+        """Use the LLM to generate a concise call summary in Markdown."""
+        transcript_text = "\n".join(
+            f"[{entry.get('role', '?')}] {entry.get('text', '')}"
+            for entry in transcript
+        )
+
+        prompt = (
+            "Summarize the following phone call transcript concisely. "
+            "Include: key topics discussed, decisions made, action items, "
+            "and the overall outcome.\n\n"
+            f"Call purpose: {task.get('purpose', 'N/A')}\n"
+            f"Contact: {task.get('contact_name', 'Unknown')}\n"
+            f"Direction: {task.get('direction', 'unknown')}\n\n"
+            f"Transcript:\n{transcript_text}\n\n"
+            "Respond in the same language as the transcript."
+        )
+
+        try:
+            from conversation.llm import create_llm_provider
+
+            provider = create_llm_provider()
+            result = await provider.generate(
+                messages=[{"role": "user", "content": prompt}],
+            )
+            return result.get("content", "")
+        except ImportError:
+            logger.warning("LLM module not available; cannot generate summary")
+            return ""
+        except Exception:
+            logger.exception("Failed to generate call summary")
+            return ""