@tencent-rtc/trtc-agent-skills 0.1.3 → 0.1.4

package/skills/trtc-ai-service/capabilities/human-handoff/manifest.yaml

@@ -0,0 +1,227 @@
+# human-handoff capability self-describing manifest
+# Type: capability (optional install)
+
+name: "human-handoff"
+version: "1.1.0"
+type: "capability"
+description: "Semantic trigger for human handoff + ticket lifecycle (Phase 3 refactored to ports/adapters/core three-layer architecture)"
+
+dependencies:
+  - name: "conversation-core"
+    version: ">=1.0.0,<2.0.0"
+
+# ---------------------------------------------------------------------------
+# Injection points (maintains full Phase 2 compatibility; trigger.py / queue.py are now facades)
+# ---------------------------------------------------------------------------
+extensions:
+  # Detect whether to trigger "handoff" before text injection; if matched, route to human channel
+  - inject_at: "agent.before_push_text"
+    inline_code: |
+      # [human-handoff] semantic trigger detection
+      from ._capability_loader import try_load_capability
+      _hh_trigger = try_load_capability("human-handoff", "src/trigger.py")
+      if _hh_trigger is not None:
+          _hand = _hh_trigger.maybe_handoff(session_id, text)
+          if _hand is not None:
+              text = _hand   # Replace original text with queue/connect messaging to prevent LLM self-answering
+  # Release queue slot after agent stops
+  - inject_at: "agent.after_start"
+    inline_code: |
+      # [human-handoff] register session for handoff state machine
+      from ._capability_loader import try_load_capability
+      _hh_queue = try_load_capability("human-handoff", "src/queue.py")
+      if _hh_queue is not None:
+          _hh_queue.attach_session(session_id, info=info if 'info' in locals() else None)
+  - inject_at: "server.router_extension"
+    inline_code: |
+      # [human-handoff] mount sub-router
+      from ._capability_loader import try_load_capability as _try_load_capability
+      _hh_router_mod = _try_load_capability("human-handoff", "src/router.py")
+      if _hh_router_mod is not None and hasattr(_hh_router_mod, "router"):
+          app.include_router(
+              _hh_router_mod.router, prefix="/api/v1/handoff", tags=["human-handoff"]
+          )
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+config:
+  triggers:
+    description: "Strong trigger keyword list (exact match / case-insensitive)"
+    default:
+      - "talk to agent"
+      - "human support"
+      - "real person"
+      - "talk to agent"
+      - "speak to a human"
+  intent_keywords:
+    description: "Weak trigger keywords (subtracted from negative context)"
+    default:
+      - "complain"
+      - "manager"
+      - "supervisor"
+      - "not working"
+  queue_capacity:
+    description: "Local queue capacity (effective only for local_queue / mock adapter)"
+    default: 50
+  agent_pool_size:
+    description: "Number of available agents (auto-connect when >0)"
+    default: 1
+  estimated_wait_seconds_per_slot:
+    default: 30
+  retention_seconds:
+    description: "Retention duration for completed sessions (used for summary queries)"
+    default: 600
+  adapter:
+    description: "Which HandoffClient implementation to use: local_queue | mock | default_rest | user_custom"
+    default: "local_queue"
+    env: "HH_ADAPTER"
+
+# ---------------------------------------------------------------------------
+# API endpoints
+# ---------------------------------------------------------------------------
+endpoints:
+  - method: GET
+    path: /api/v1/handoff/status
+    description: Query overall queue status
+  - method: GET
+    path: /api/v1/handoff/{session_id}
+    description: Query handoff status for a single session (legacy field format, backward compatible)
+  - method: POST
+    path: /api/v1/handoff/request
+    description: "Explicit handoff request submission (body shape: {session_id, reason?})"
+  - method: POST
+    path: /api/v1/handoff/connect
+    description: "Simulate agent connection (body shape: {session_id, agent_id})"
+  - method: POST
+    path: /api/v1/handoff/cancel
+    description: "Cancel queue (body shape: {session_id})"
+  # ----- Phase 3 new: Ticket agent dashboard endpoints -----
+  - method: GET
+    path: /api/v1/handoff/admin/tickets
+    description: "Ticket list (supports ?status=&limit= filtering)"
+  - method: GET
+    path: /api/v1/handoff/admin/tickets/{ticket_id}
+    description: "Ticket details"
+  - method: POST
+    path: /api/v1/handoff/admin/tickets/{ticket_id}/status
+    description: "Agent manually switches ticket status (pending|processing|closed|canceled|timeout)"
+
+# ---------------------------------------------------------------------------
+# Business contract (Phase 3 new; follows references/business-contract-spec.md v1.0)
+# ---------------------------------------------------------------------------
+business_contract:
+  port_class: "src.ports.handoff_client.HandoffClient"
+  default_adapter: "src.adapters.local_queue.LocalQueueHandoffClient"
+  mock_adapter: "src.adapters.mock.MockHandoffClient"
+  customization_sop: "INTERFACE_ADAPT.md"
+  external_apis:
+    - name: ticket.create
+      direction: outbound
+      method: POST
+      path: /tickets
+      description: "Create a new ticket in the ticketing system when user triggers handoff"
+      request_schema:
+        user_id: string
+        subject: string
+        description: string
+        priority: enum[low, normal, high, urgent]
+        transcript: string[]
+      response_schema:
+        ticket_id: string
+        queue_position: int
+        eta_seconds: int
+      adapter_slots:
+        - request.subject
+        - request.priority
+        - response.ticket_id
+        - response.queue_position
+        - response.eta_seconds
+      auth:
+        type: bearer
+        location: header
+        name: Authorization
+      timeout_ms: 5000
+
+    - name: ticket.status_query
+      direction: outbound
+      method: GET
+      path: /tickets/{ticket_id}
+      description: "Poll ticket status for queue progress updates"
+      request_schema:
+        ticket_id: string
+      response_schema:
+        ticket_id: string
+        status: enum[pending, processing, closed, canceled]
+        agent_id: string
+        updated_at: int
+      adapter_slots:
+        - response.status
+        - response.agent_id
+      timeout_ms: 3000
+
+    - name: ticket.cancel
+      direction: outbound
+      method: POST
+      path: /tickets/{ticket_id}/cancel
+      description: "Notify ticketing system when user cancels handoff"
+      request_schema:
+        ticket_id: string
+        reason: string
+      response_schema:
+        ticket_id: string
+        canceled: bool
+      adapter_slots:
+        - request.reason
+      timeout_ms: 3000
+
+    - name: ticket.status_callback
+      direction: inbound
+      method: POST
+      path: /api/v1/handoff/callback/ticket-status
+      description: "Callback from ticketing system to notify status changes (optional; when disabled, status_query polling is used instead)"
+      request_schema:
+        ticket_id: string
+        status: enum[pending, processing, closed, canceled]
+        agent_id: string
+      response_schema:
+        code: int
+        message: string
+      adapter_slots:
+        - request.status
+        - request.agent_id
+
+# ---------------------------------------------------------------------------
+# Integration
+# ---------------------------------------------------------------------------
+integration:
+  mode: "auto"
+  auto_adapters:
+    - tech_stack: ["react", "vue", "angular"]
+      adapter: "frontend-spa"
+      description: "Append queue status indicator component to SPA"
+    - tech_stack: ["express", "koa", "fastify", "next"]
+      adapter: "node-backend"
+    - tech_stack: ["flask", "fastapi", "django"]
+      adapter: "python-backend"
+    - tech_stack: ["spring-boot", "quarkus"]
+      adapter: "java-backend"
+  fallback:
+    guided_templates:
+      - "../../auto_adapters/integration_templates/generic-frontend.md"
+    manual_api:
+      rest_endpoint: "/api/v1/handoff"
+
+security:
+  log_redaction:
+    enabled: true
+    patterns: ["phone", "mobile", "user_id", "credential", "authorization"]
+  network:
+    enforce_https: true        # default_rest adapter enforces HTTPS for non-localhost
+
+acceptance:
+  - "Keyword match immediately enters ticket flow, status pollable by frontend"
+  - "Connects instantly when agent pool > 0; returns estimated wait time when = 0"
+  - "Correctly releases slot when session is canceled / connected"
+  - "Switching HH_ADAPTER requires no business code changes (local_queue / mock / default_rest / user_custom)"
+  - "default_rest adapter rejects private network addresses (except localhost)"

package/skills/trtc-ai-service/capabilities/human-handoff/src/__init__.py

@@ -0,0 +1,2 @@
+"""human-handoff capability: semantic-triggered handoff + queue status sync."""
+__version__ = "1.0.0"

package/skills/trtc-ai-service/capabilities/human-handoff/src/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""human-handoff adapter implementations."""
+from .factory import build_default, get_client, reset_client, set_client
+
+__all__ = [
+    "build_default",
+    "get_client",
+    "reset_client",
+    "set_client",
+]

package/skills/trtc-ai-service/capabilities/human-handoff/src/adapters/default_rest.py

@@ -0,0 +1,242 @@
+"""DefaultRestHandoffClient — call external ticketing system per business_contract default contract.
+
+Corresponding contracts:
+- POST   /tickets               ticket.create
+- GET    /tickets/{ticket_id}   ticket.status_query
+- POST   /tickets/{ticket_id}/cancel    ticket.cancel
+
+Environment variables:
+- HH_REST_BASE_URL    Ticketing system base URL (required; must not point to private network, see §Security)
+- HH_REST_TOKEN       Bearer Token (optional)
+- HH_REST_TIMEOUT_MS  Timeout (default 5000)
+
+Security constraints (aligned with project security_rules):
+- Only allow https:// or http://localhost / 127.0.0.1
+- Default reject common private network ranges (9.* / 10.* / 11.* / 21.* / 30.* / 169.254.* / 172.16-31.* / 192.168.*)
+- Log redaction auto-masks Authorization
+
+Dependency: only requests (already in conversation-core/requirements.txt), no new deps.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import List, Optional
+from urllib.parse import urlparse
+
+try:
+    import requests  # type: ignore
+except ImportError:  # pragma: no cover
+    requests = None  # type: ignore
+
+from ..core.models import (
+    OverallStatus,
+    Ticket,
+    TicketStatus,
+    TicketStatusEnum,
+    now_ts,
+)
+from ..ports.handoff_client import HandoffClient
+
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Security: private network and loopback check
+# ---------------------------------------------------------------------------
+_PRIVATE_PATTERNS = [
+    re.compile(r"^9\."),
+    re.compile(r"^10\."),
+    re.compile(r"^11\."),
+    re.compile(r"^21\."),
+    re.compile(r"^30\."),
+    re.compile(r"^169\.254\."),
+    re.compile(r"^172\.(1[6-9]|2[0-9]|3[01])\."),
+    re.compile(r"^192\.168\."),
+]
+
+
+def _is_localhost(host: str) -> bool:
+    return host in {"localhost", "127.0.0.1", "::1"}
+
+
+def _is_private(host: str) -> bool:
+    return any(p.match(host) for p in _PRIVATE_PATTERNS)
+
+
+def _validate_base_url(url: str) -> str:
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError(f"unsupported scheme: {parsed.scheme}")
+    host = parsed.hostname or ""
+    if not host:
+        raise ValueError("empty host in HH_REST_BASE_URL")
+    # Non-HTTPS only allowed for localhost
+    if parsed.scheme == "http" and not _is_localhost(host):
+        raise ValueError(
+            "non-HTTPS HH_REST_BASE_URL only allowed for localhost"
+        )
+    # Reject private network ranges (prevent SSRF)
+    if _is_private(host):
+        raise ValueError(
+            f"access to private network host '{host}' is denied; "
+            "set HH_REST_ALLOW_PRIVATE=1 to override (not recommended)"
+        )
+    return url.rstrip("/")
+
+
+# ---------------------------------------------------------------------------
+# Client implementation
+# ---------------------------------------------------------------------------
+class DefaultRestHandoffClient(HandoffClient):
+    """Call external ticketing system per default REST contract."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: Optional[str] = None,
+        timeout_ms: int = 5000,
+    ) -> None:
+        if requests is None:
+            raise RuntimeError(
+                "requests library is required for DefaultRestHandoffClient"
+            )
+        self._base = _validate_base_url(base_url)
+        self._token = token
+        self._timeout = max(0.5, timeout_ms / 1000.0)
+        self._session = requests.Session()
+
+    # ------------------------------------------------------------------
+    # HandoffClient required implementations
+    # ------------------------------------------------------------------
+    def create_ticket(
+        self,
+        *,
+        user_id: str,
+        subject: str = "",
+        description: str = "",
+        priority: str = "normal",
+        transcript: Optional[List[str]] = None,
+    ) -> Ticket:
+        payload = {
+            "user_id": user_id,
+            "subject": subject,
+            "description": description,
+            "priority": priority or "normal",
+            "transcript": list(transcript or []),
+        }
+        data = self._post("/tickets", payload)
+        ticket_id = str(data.get("ticket_id") or "").strip()
+        if not ticket_id:
+            raise RuntimeError("remote ticket service did not return ticket_id")
+        return Ticket(
+            ticket_id=ticket_id,
+            user_id=user_id,
+            subject=subject,
+            description=description,
+            priority=priority or "normal",
+            status=TicketStatusEnum.PENDING.value,
+            queue_position=int(data.get("queue_position") or 0),
+            eta_seconds=int(data.get("eta_seconds") or 0),
+            transcript=list(transcript or []),
+            reason=description[:128] if description else "",
+            created_at=now_ts(),
+            updated_at=now_ts(),
+        )
+
+    def query_status(self, ticket_id: str) -> Optional[TicketStatus]:
+        data = self._get(f"/tickets/{ticket_id}", optional=True)
+        if data is None:
+            return None
+        return TicketStatus(
+            ticket_id=str(data.get("ticket_id") or ticket_id),
+            status=str(data.get("status") or TicketStatusEnum.PENDING.value),
+            agent_id=data.get("agent_id"),
+            updated_at=float(data.get("updated_at") or 0.0) or None,
+        )
+
+    def cancel_ticket(self, ticket_id: str, reason: str = "") -> Optional[Ticket]:
+        data = self._post(
+            f"/tickets/{ticket_id}/cancel",
+            {"ticket_id": ticket_id, "reason": reason},
+            optional=True,
+        )
+        if data is None:
+            return None
+        return Ticket(
+            ticket_id=ticket_id,
+            user_id="",  # remote may not return user_id
+            status=TicketStatusEnum.CANCELED.value,
+            reason=reason,
+            updated_at=now_ts(),
+            closed_at=now_ts(),
+        )
+
+    def overall_status(self) -> OverallStatus:
+        # Remote backend does not expose overall status; return placeholder (for /api/v1/handoff/status compatibility)
+        return OverallStatus(
+            agent_pool_size=-1,
+            available_agents=-1,
+            waiting=-1,
+            connected=-1,
+            capacity=-1,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal：HTTP
+    # ------------------------------------------------------------------
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        return h
+
+    def _get(self, path: str, *, optional: bool = False):
+        url = self._base + path
+        resp = self._session.get(url, headers=self._headers(), timeout=self._timeout)
+        return self._handle(resp, optional=optional)
+
+    def _post(self, path: str, payload: dict, *, optional: bool = False):
+        url = self._base + path
+        resp = self._session.post(
+            url,
+            json=payload,
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        return self._handle(resp, optional=optional)
+
+    @staticmethod
+    def _handle(resp, *, optional: bool):
+        if resp.status_code == 404 and optional:
+            return None
+        if resp.status_code >= 400:
+            # Do not print response body (may contain sensitive info)
+            raise RuntimeError(
+                f"remote ticket service returned HTTP {resp.status_code}"
+            )
+        try:
+            data = resp.json()
+        except ValueError as exc:
+            raise RuntimeError("remote ticket service returned non-JSON") from exc
+        # Response may be {"data": {...}} or flat {...}
+        if isinstance(data, dict) and "data" in data and isinstance(data["data"], dict):
+            return data["data"]
+        return data
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+def from_env() -> Optional[DefaultRestHandoffClient]:
+    base = os.getenv("HH_REST_BASE_URL")
+    if not base:
+        return None
+    return DefaultRestHandoffClient(
+        base_url=base,
+        token=os.getenv("HH_REST_TOKEN"),
+        timeout_ms=int(os.getenv("HH_REST_TIMEOUT_MS", "5000")),
+    )

package/skills/trtc-ai-service/capabilities/human-handoff/src/adapters/factory.py

@@ -0,0 +1,89 @@
+"""adapter factory: selects HandoffClient implementation based on environment variable.
+
+Environment variable `HH_ADAPTER`:
+    local_queue   Default local in-memory queue (production-ready, zero dependencies)
+    mock          Demo data (includes several preset tickets for video recording)
+    default_rest  Call remote ticketing system per business_contract default contract
+    user_custom   User integration wizard (contract-adapt.py) generated implementation
+
+When not set or invalid, fall back to local_queue (keeps behavior compatibility with Phase 2).
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+from ..ports.handoff_client import HandoffClient
+
+
+logger = logging.getLogger(__name__)
+
+
+_VALID = ("local_queue", "mock", "default_rest", "user_custom")
+
+
+def _build(name: str) -> Optional[HandoffClient]:
+    if name == "local_queue":
+        from .local_queue import from_env as build_local
+        return build_local()
+    if name == "mock":
+        from .mock import from_env as build_mock
+        return build_mock()
+    if name == "default_rest":
+        from .default_rest import from_env as build_rest
+        c = build_rest()
+        if c is None:
+            logger.warning(
+                "HH_ADAPTER=default_rest but HH_REST_BASE_URL is empty; "
+                "falling back to local_queue"
+            )
+        return c
+    if name == "user_custom":
+        try:
+            from .user_custom import from_env as build_custom  # type: ignore
+        except ImportError:
+            logger.warning(
+                "HH_ADAPTER=user_custom but src/adapters/user_custom.py is missing; "
+                "run scripts/contract-adapt.py human-handoff to generate it"
+            )
+            return None
+        return build_custom()
+    return None
+
+
+def build_default() -> HandoffClient:
+    """Build default client from environment variables; invalid config falls back to local_queue."""
+    name = (os.getenv("HH_ADAPTER") or "local_queue").strip().lower()
+    if name not in _VALID:
+        logger.warning("HH_ADAPTER=%s is not recognised; using local_queue", name)
+        name = "local_queue"
+    client = _build(name)
+    if client is None:
+        from .local_queue import from_env as build_local
+        client = build_local()
+    return client
+
+
+# ---------------------------------------------------------------------------
+# Global singleton
+# ---------------------------------------------------------------------------
+_singleton: Optional[HandoffClient] = None
+
+
+def get_client() -> HandoffClient:
+    global _singleton
+    if _singleton is None:
+        _singleton = build_default()
+    return _singleton
+
+
+def set_client(client: HandoffClient) -> None:
+    """For testing only: inject a custom client."""
+    global _singleton
+    _singleton = client
+
+
+def reset_client() -> None:
+    global _singleton
+    _singleton = None