@agentunion/kite 1.0.6 → 1.2.0

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

@@ -0,0 +1,45 @@
+"""Task data models — enumerations for call lifecycle states."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class TaskStatus(str, Enum):
+    """Lifecycle status of a call task."""
+    QUEUED = "queued"
+    CONFIRMING = "confirming"      # waiting for contact confirmation
+    CONNECTING = "connecting"
+    DIALING = "dialing"
+    ALERTING = "alerting"
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class CallDirection(str, Enum):
+    """Direction of a phone call."""
+    OUTGOING = "outgoing"
+    INCOMING = "incoming"
+
+
+class CallResult(str, Enum):
+    """Outcome of a completed call."""
+    SUCCESS = "success"
+    NO_ANSWER = "no_answer"
+    BUSY = "busy"
+    REJECTED = "rejected"
+    ERROR = "error"
+    TIMEOUT = "timeout"
+
+
+class EndedReason(str, Enum):
+    """Reason the call ended."""
+    NORMAL = "normal"
+    AI_HANGUP = "ai_hangup"
+    REMOTE_HANGUP = "remote_hangup"
+    TIMEOUT = "timeout"
+    MAX_DURATION = "max_duration"
+    ERROR = "error"
+    CANCELLED = "cancelled"

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

@@ -0,0 +1,263 @@
+"""Webhook client — sends callbacks to the task caller with retry logic."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+import httpx
+
+from .. import config as cfg
+
+logger = logging.getLogger(__name__)
+
+
+class WebhookClient:
+    """Sends webhook notifications and manages pending confirmation futures.
+
+    Confirmations that require a response from the caller (e.g.
+    ``in_call_confirmation``) are tracked as :class:`asyncio.Future` objects
+    keyed by *task_id*.  The matching API route calls
+    :meth:`resolve_confirmation` when the caller replies via
+    ``POST /api/call/{task_id}/message``.
+    """
+
+    def __init__(self) -> None:
+        timeout = cfg.get("webhook.timeout", 10)
+        self._client = httpx.AsyncClient(timeout=timeout)
+        self._pending_confirmations: dict[str, asyncio.Future[str]] = {}
+
+    # ------------------------------------------------------------------
+    # Low-level send with retry
+    # ------------------------------------------------------------------
+
+    async def send(self, url: str, payload: dict[str, Any]) -> bool:
+        """Send a webhook POST with configurable retry.
+
+        Retries up to ``webhook.retry_count`` times (default 3) with delays
+        taken from ``webhook.retry_delays`` (default ``[1, 5, 30]``).
+
+        Returns ``True`` if **any** attempt receives a 2xx response.
+        """
+        retry_count: int = cfg.get("webhook.retry_count", 3)
+        retry_delays: list[int] = cfg.get("webhook.retry_delays", [1, 5, 30])
+
+        for attempt in range(retry_count):
+            try:
+                resp = await self._client.post(url, json=payload)
+                if 200 <= resp.status_code < 300:
+                    logger.info(
+                        "Webhook delivered to %s (attempt %d, status %d)",
+                        url, attempt + 1, resp.status_code,
+                    )
+                    return True
+                logger.warning(
+                    "Webhook to %s returned %d (attempt %d/%d)",
+                    url, resp.status_code, attempt + 1, retry_count,
+                )
+            except httpx.HTTPError as exc:
+                logger.warning(
+                    "Webhook to %s failed (attempt %d/%d): %s",
+                    url, attempt + 1, retry_count, exc,
+                )
+
+            # Wait before next retry (if not the last attempt)
+            if attempt < retry_count - 1:
+                delay = retry_delays[attempt] if attempt < len(retry_delays) else retry_delays[-1]
+                await asyncio.sleep(delay)
+
+        logger.error("Webhook to %s exhausted all %d retries", url, retry_count)
+        return False
+
+    # ------------------------------------------------------------------
+    # High-level notification helpers
+    # ------------------------------------------------------------------
+
+    async def notify_call_completed(self, task: dict[str, Any]) -> None:
+        """Send a ``call_completed`` webhook after a call finishes."""
+        webhook_url = task.get("webhook_url") or cfg.get("webhook.default_url")
+        if not webhook_url:
+            logger.debug("No webhook URL configured; skipping call_completed notification")
+            return
+
+        payload: dict[str, Any] = {
+            "task_id": task["task_id"],
+            "type": "call_completed",
+            "status": task.get("status", "completed"),
+            "phone_number": task.get("phone_number"),
+            "contact_name": task.get("contact_name"),
+            "direction": task.get("direction"),
+            "duration_seconds": task.get("duration_seconds", 0),
+            "transcript": task.get("transcript", []),
+            "summary": task.get("summary", ""),
+            "result": task.get("result"),
+            "ended_reason": task.get("ended_reason"),
+            "recording_url": f"/api/calls/{task['task_id']}/recording" if task.get("has_recording") else None,
+            "timestamp": task.get("ended_at"),
+        }
+
+        await self.send(webhook_url, payload)
+
+    async def notify_incoming_call(self, task: dict[str, Any]) -> dict[str, Any] | None:
+        """Send an ``incoming_call`` webhook and wait for the caller to confirm.
+
+        Returns the confirmation response dict received through the API, or
+        ``None`` if the configured timeout elapses.
+        """
+        webhook_url = task.get("webhook_url") or cfg.get("webhook.default_url")
+        if not webhook_url:
+            logger.debug("No webhook URL configured; skipping incoming_call notification")
+            return None
+
+        payload: dict[str, Any] = {
+            "task_id": task["task_id"],
+            "type": "incoming_call",
+            "phone_number": task.get("phone_number"),
+            "contact_name": task.get("contact_name"),
+            "contact_info": task.get("contact_info"),
+            "timestamp": task.get("started_at"),
+        }
+
+        sent = await self.send(webhook_url, payload)
+        if not sent:
+            return None
+
+        # Wait for the caller to respond via POST /api/call/{task_id}/confirm
+        timeout = cfg.get("call.incoming_confirm_timeout", 15)
+        future: asyncio.Future[str] = asyncio.get_running_loop().create_future()
+        self._pending_confirmations[task["task_id"]] = future
+
+        try:
+            result = await asyncio.wait_for(future, timeout=timeout)
+            # result is a JSON-encoded string; the API layer is responsible for
+            # providing a meaningful dict — we simply return what we got.
+            return {"response": result}
+        except asyncio.TimeoutError:
+            logger.info("Incoming-call confirmation timed out for task %s", task["task_id"])
+            return None
+        finally:
+            self._pending_confirmations.pop(task["task_id"], None)
+
+    async def request_contact_confirmation(
+        self,
+        task: dict[str, Any],
+        matched_contact: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        """Send a ``contact_confirmation`` webhook and wait for the caller to confirm.
+
+        Returns the confirmation response or ``None`` on timeout.
+        """
+        webhook_url = task.get("webhook_url") or cfg.get("webhook.default_url")
+        if not webhook_url:
+            logger.debug("No webhook URL configured; skipping contact_confirmation")
+            return None
+
+        payload: dict[str, Any] = {
+            "task_id": task["task_id"],
+            "type": "contact_confirmation",
+            "matched_contact": {
+                "name": matched_contact.get("name"),
+                "phone": matched_contact.get("phone"),
+                "company": matched_contact.get("company"),
+            },
+            "confidence": matched_contact.get("confidence", 0),
+            "alternatives": matched_contact.get("alternatives", []),
+        }
+
+        sent = await self.send(webhook_url, payload)
+        if not sent:
+            return None
+
+        # Wait for POST /api/call/{task_id}/confirm
+        timeout = cfg.get("call.incoming_confirm_timeout", 15)
+        future: asyncio.Future[str] = asyncio.get_running_loop().create_future()
+        self._pending_confirmations[task["task_id"]] = future
+
+        try:
+            result = await asyncio.wait_for(future, timeout=timeout)
+            return {"response": result}
+        except asyncio.TimeoutError:
+            logger.info("Contact confirmation timed out for task %s", task["task_id"])
+            return None
+        finally:
+            self._pending_confirmations.pop(task["task_id"], None)
+
+    async def request_in_call_confirmation(
+        self,
+        task_id: str,
+        question: str,
+        options: list[str] | None = None,
+    ) -> str | None:
+        """Send an ``in_call_confirmation`` webhook and wait for a response.
+
+        The response arrives asynchronously when the caller sends a message
+        through ``POST /api/call/{task_id}/message``, which triggers
+        :meth:`resolve_confirmation`.
+
+        Returns the caller's text response, or ``None`` on timeout.
+        """
+        # Look up webhook URL from the persisted task record
+        from storage import get_task
+        task = await get_task(task_id)
+        webhook_url = (task or {}).get("webhook_url") or cfg.get("webhook.default_url")
+        if not webhook_url:
+            logger.debug("No webhook URL; skipping in_call_confirmation for %s", task_id)
+            return None
+
+        payload: dict[str, Any] = {
+            "task_id": task_id,
+            "type": "in_call_confirmation",
+            "question": question,
+            "options": options,
+        }
+
+        sent = await self.send(webhook_url, payload)
+        if not sent:
+            return None
+
+        # Wait for the caller's reply
+        timeout = cfg.get("call.no_response_timeout", 15)
+        future: asyncio.Future[str] = asyncio.get_running_loop().create_future()
+        self._pending_confirmations[task_id] = future
+
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError:
+            logger.info("In-call confirmation timed out for task %s", task_id)
+            return None
+        finally:
+            self._pending_confirmations.pop(task_id, None)
+
+    # ------------------------------------------------------------------
+    # Confirmation resolution (called by API routes)
+    # ------------------------------------------------------------------
+
+    def resolve_confirmation(self, task_id: str, response: str) -> None:
+        """Resolve a pending confirmation future for *task_id*.
+
+        Called by the API route handler when the caller responds via
+        ``POST /api/call/{task_id}/message`` or
+        ``POST /api/call/{task_id}/confirm``.
+        """
+        future = self._pending_confirmations.get(task_id)
+        if future is not None and not future.done():
+            future.set_result(response)
+            logger.info("Resolved pending confirmation for task %s", task_id)
+        else:
+            logger.debug("No pending confirmation for task %s (or already resolved)", task_id)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def close(self) -> None:
+        """Shut down the underlying HTTP client."""
+        await self._client.aclose()
+
+        # Cancel any dangling futures
+        for task_id, future in self._pending_confirmations.items():
+            if not future.done():
+                future.cancel()
+                logger.debug("Cancelled pending confirmation for task %s on shutdown", task_id)
+        self._pending_confirmations.clear()

package/extensions/services/web/vendor/tools/registry.py

@@ -0,0 +1,321 @@
+"""Tool registry — discovers, loads and manages tools installed under data/tools/."""
+
+from __future__ import annotations
+
+import copy
+import importlib.util
+import logging
+from pathlib import Path
+from typing import Any, Callable, Awaitable
+
+import yaml
+
+from .. import config as cfg
+
+logger = logging.getLogger(__name__)
+
+ToolHandler = Callable[[dict[str, Any], dict[str, Any]], Awaitable[str]]
+
+
+class ToolRegistry:
+    """Central registry that discovers tool.yaml + handler.py pairs under a tools directory.
+
+    Parameters
+    ----------
+    tools_dir:
+        Path to the ``data/tools/`` directory.
+    """
+
+    def __init__(self, tools_dir: Path) -> None:
+        self.tools_dir = tools_dir
+        # name -> parsed tool.yaml content
+        self._definitions: dict[str, dict[str, Any]] = {}
+        # name -> async execute(args, context) callable
+        self._handlers: dict[str, ToolHandler] = {}
+
+    # ------------------------------------------------------------------
+    # Loading
+    # ------------------------------------------------------------------
+
+    def load_all(self) -> None:
+        """Scan *tools_dir* and load every tool that has a valid ``tool.yaml``."""
+        if not self.tools_dir.exists():
+            logger.warning("Tools directory does not exist: %s", self.tools_dir)
+            return
+
+        for child in sorted(self.tools_dir.iterdir()):
+            if not child.is_dir():
+                continue
+            tool_yaml = child / "tool.yaml"
+            handler_py = child / "handler.py"
+            if not tool_yaml.exists():
+                continue
+
+            try:
+                with open(tool_yaml, "r", encoding="utf-8") as f:
+                    definition = yaml.safe_load(f) or {}
+                name = definition.get("name", child.name)
+                self._definitions[name] = definition
+
+                if handler_py.exists():
+                    handler = self._load_handler(handler_py)
+                    if handler:
+                        self._handlers[name] = handler
+
+                logger.info("Loaded tool: %s", name)
+            except Exception:
+                logger.exception("Failed to load tool from %s", child)
+
+    def _load_handler(self, handler_path: Path) -> ToolHandler | None:
+        """Dynamically import a handler.py and return its ``execute`` function."""
+        try:
+            spec = importlib.util.spec_from_file_location(
+                f"tool_handler_{handler_path.parent.name}", str(handler_path)
+            )
+            if spec is None or spec.loader is None:
+                return None
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            fn = getattr(module, "execute", None)
+            if fn is None:
+                logger.warning("handler.py in %s has no execute() function", handler_path.parent.name)
+                return None
+            return fn
+        except Exception:
+            logger.exception("Failed to import handler: %s", handler_path)
+            return None
+
+    # ------------------------------------------------------------------
+    # Accessors
+    # ------------------------------------------------------------------
+
+    def get_definition(self, name: str) -> dict[str, Any] | None:
+        return self._definitions.get(name)
+
+    def get_handler(self, name: str) -> ToolHandler | None:
+        return self._handlers.get(name)
+
+    def get_readme(self, name: str) -> str | None:
+        """Return the README.md content for a tool, or None."""
+        readme = self.tools_dir / name / "README.md"
+        if readme.exists():
+            return readme.read_text(encoding="utf-8")
+        return None
+
+    def list_tools(self) -> list[str]:
+        """Return all loaded tool names."""
+        return list(self._definitions.keys())
+
+    # ------------------------------------------------------------------
+    # Permission resolution
+    # ------------------------------------------------------------------
+
+    def resolve_enabled(
+        self,
+        global_cfg: dict[str, Any] | None,
+        user_cfg: dict[str, Any] | None,
+        contact_cfg: dict[str, Any] | None,
+        call_cfg: dict[str, Any] | None,
+        is_owner: bool,
+    ) -> list[str]:
+        """Resolve the final list of enabled tool names through the 4-level hierarchy.
+
+        Resolution order:
+        1. Global ``data/tools.yaml`` — base enabled/disabled
+        2. User ``data/users/{phone}/tools.yaml`` — overlay
+        3. Contact ``data/users/{phone}/contacts/{phone}/tools.yaml`` — overlay
+           (defaults depend on ``is_owner``)
+        4. Call-level ``call_cfg`` — final overlay
+
+        Returns the list of tool names that are enabled after all layers.
+        """
+        all_tools = set(self._definitions.keys())
+
+        # Layer 1: Global
+        enabled = set(self._apply_layer(all_tools, set(), global_cfg))
+
+        # Layer 2: User
+        enabled = set(self._apply_layer(enabled, all_tools - enabled, user_cfg))
+
+        # Layer 3: Contact (with owner defaults)
+        if is_owner:
+            # Owners keep everything enabled from above, then apply contact overrides
+            if contact_cfg is not None:
+                enabled = set(self._apply_layer(enabled, all_tools - enabled, contact_cfg))
+        else:
+            # Non-owners start with nothing, then apply contact overrides
+            enabled = set()
+            if contact_cfg is not None:
+                enabled = set(self._apply_layer(enabled, all_tools, contact_cfg))
+
+        # Layer 4: Call-level overrides
+        enabled = set(self._apply_layer(enabled, all_tools - enabled, call_cfg))
+
+        return sorted(enabled)
+
+    @staticmethod
+    def _apply_layer(
+        current_enabled: set[str],
+        current_disabled: set[str],
+        layer_cfg: dict[str, Any] | None,
+    ) -> set[str]:
+        """Apply a single tools.yaml layer to the current enabled set."""
+        if layer_cfg is None:
+            return current_enabled
+
+        to_enable = set(layer_cfg.get("enabled", []))
+        to_disable = set(layer_cfg.get("disabled", []))
+
+        result = set(current_enabled)
+        result |= to_enable
+        result -= to_disable
+        return result
+
+    # ------------------------------------------------------------------
+    # Provider format conversion
+    # ------------------------------------------------------------------
+
+    def get_tools_for_provider(
+        self, provider: str, enabled_names: list[str]
+    ) -> list[dict[str, Any]]:
+        """Convert enabled tools into the schema expected by each LLM provider.
+
+        Parameters
+        ----------
+        provider:
+            One of ``"openai"``, ``"claude"``, ``"gemini"``.
+        enabled_names:
+            List of tool names to include.
+        """
+        definitions = [
+            self._definitions[n] for n in enabled_names if n in self._definitions
+        ]
+
+        if provider == "openai":
+            return self._to_openai(definitions)
+        elif provider == "claude":
+            return self._to_claude(definitions)
+        elif provider == "gemini":
+            return self._to_gemini(definitions)
+        else:
+            raise ValueError(f"Unknown LLM provider: {provider}")
+
+    @staticmethod
+    def _to_openai(definitions: list[dict]) -> list[dict]:
+        tools = []
+        for d in definitions:
+            tools.append({
+                "type": "function",
+                "function": {
+                    "name": d["name"],
+                    "description": d.get("description", ""),
+                    "parameters": copy.deepcopy(d.get("parameters", {})),
+                },
+            })
+        return tools
+
+    @staticmethod
+    def _to_claude(definitions: list[dict]) -> list[dict]:
+        tools = []
+        for d in definitions:
+            tools.append({
+                "name": d["name"],
+                "description": d.get("description", ""),
+                "input_schema": copy.deepcopy(d.get("parameters", {})),
+            })
+        return tools
+
+    @staticmethod
+    def _to_gemini(definitions: list[dict]) -> list[dict]:
+        declarations = []
+        for d in definitions:
+            declarations.append({
+                "name": d["name"],
+                "description": d.get("description", ""),
+                "parameters": copy.deepcopy(d.get("parameters", {})),
+            })
+        return [{"function_declarations": declarations}]
+
+    # ------------------------------------------------------------------
+    # Context / summary helpers
+    # ------------------------------------------------------------------
+
+    def build_tools_summary(self, enabled_names: list[str]) -> str:
+        """Build a human-readable summary of enabled tools for the LLM system prompt."""
+        lines: list[str] = []
+        for name in enabled_names:
+            defn = self._definitions.get(name)
+            if not defn:
+                continue
+            desc = defn.get("description", "")
+            skill = defn.get("skill", {})
+            summary = skill.get("summary", desc)
+            lines.append(f"- **{name}**: {summary}")
+        if not lines:
+            return ""
+        return "## 可用工具\n\n" + "\n".join(lines)
+
+    def get_permission_files(
+        self, tool_name: str, user_phone: str, contact_phone: str
+    ) -> list[Path]:
+        """Return the list of permission file paths (user-level, contact-level) for a tool.
+
+        Files may or may not exist — the handler decides the semantics.
+        """
+        from storage.identity import user_dir, contact_dir
+
+        files: list[Path] = []
+        u_perm = user_dir(user_phone) / "permissions" / f"{tool_name}.yaml"
+        files.append(u_perm)
+        c_perm = contact_dir(user_phone, contact_phone) / "permissions" / f"{tool_name}.yaml"
+        files.append(c_perm)
+        return files
+
+    def build_context(
+        self,
+        tool_name: str,
+        engine: Any,
+        is_owner: bool,
+    ) -> dict[str, Any]:
+        """Build the context dict passed to a tool handler's ``execute()``."""
+        user_phone = engine.task_info.get("user_phone", "")
+        contact_phone = engine.task_info.get("phone_number", "")
+
+        return {
+            "task_info": engine.task_info,
+            "webhook": engine.webhook,
+            "store": None,  # lazy-imported by handler if needed
+            "identity": None,  # lazy-imported by handler if needed
+            "engine": engine,
+            "data_dir": cfg.data_dir(),
+            "root_dir": cfg.root_dir(),
+            "is_owner": is_owner,
+            "permission_files": self.get_permission_files(
+                tool_name, user_phone, contact_phone
+            ),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+_registry: ToolRegistry | None = None
+
+
+def get_registry() -> ToolRegistry:
+    """Return the global ToolRegistry singleton, initializing if needed."""
+    global _registry
+    if _registry is None:
+        _registry = ToolRegistry(cfg.data_dir() / "tools")
+        _registry.load_all()
+    return _registry
+
+
+def init_registry() -> ToolRegistry:
+    """Explicitly (re-)initialize the global registry. Called at startup."""
+    global _registry
+    _registry = ToolRegistry(cfg.data_dir() / "tools")
+    _registry.load_all()
+    logger.info("ToolRegistry initialized with %d tools", len(_registry.list_tools()))
+    return _registry