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

package/skills/trtc-ai-service/scripts/lib/credential_validators.py

@@ -0,0 +1,253 @@
+"""Three-key validation function module (Phase 3 Stage 5).
+
+Design purpose:
+- Share the same validation functions between ``scripts/setup-credentials.py``
+  (developer interactive fallback) and ``scripts/verify-credentials.py``
+  (AI-driven credential-less validation).
+- The validation logic itself comes from ``capabilities/conversation-core/src/health.py``;
+  this module only handles "credential loading + result normalization to JSON."
+
+Core API:
+- ``validate_tencent(env)`` / ``validate_trtc(env, deep=True)`` / ``validate_llm(env)``
+  → All return a ``ValidationResult`` dataclass that can be serialized via ``to_dict()``
+    to ``{ok, type, error, message, latency_ms}``.
+
+Security constraints (must follow):
+- The entire process **only reads credentials from .env / process env**, never accepts keys via CLI arguments.
+- Output JSON **does not contain** credential plaintext; the error field only holds error codes / brief messages.
+- The caller (CLI / AI) should treat stdout as parseable JSON and not echo keys in the terminal.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional
+
+# ---------------------------------------------------------------------------
+# 1) Load conversation-core credential / health check modules
+# ---------------------------------------------------------------------------
+_HERE = Path(__file__).resolve().parent
+_ROOT = _HERE.parent.parent
+_CORE_DIR = _ROOT / "capabilities" / "conversation-core"
+
+if str(_CORE_DIR) not in sys.path:
+    sys.path.insert(0, str(_CORE_DIR))
+
+# Lazy imports: for verify-credentials.py to call after .env is loaded
+def _imports():
+    from src.credentials import (  # type: ignore  # noqa: WPS433
+        LlmCredential,
+        TencentCloudCredential,
+        TrtcCredential,
+        load_from_env,
+    )
+    from src.health import (  # type: ignore  # noqa: WPS433
+        check_llm,
+        check_tencent_cloud,
+        check_trtc,
+    )
+
+    return {
+        "LlmCredential": LlmCredential,
+        "TencentCloudCredential": TencentCloudCredential,
+        "TrtcCredential": TrtcCredential,
+        "load_from_env": load_from_env,
+        "check_llm": check_llm,
+        "check_tencent_cloud": check_tencent_cloud,
+        "check_trtc": check_trtc,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 2) Error codes → AI response hints (aligned with SKILL.md §5.5 lookup table)
+# ---------------------------------------------------------------------------
+_ERROR_HINTS: Dict[str, str] = {
+    "E001": "Tencent Cloud SecretId/SecretKey verification failed (AuthFailure / STS not enabled on account).",
+    "E002": "TRTC app credentials verification failed (SDKAppID does not belong to this account / SDKSecretKey mismatch).",
+    "E003": "LLM verification failed (auth 401/403 or non-200 response).",
+    "E004": "Network unreachable / timeout (check proxy / firewall).",
+    "E000": "Credential not configured or empty.",
+}
+
+
+# ---------------------------------------------------------------------------
+# 3) Unified return structures
+# ---------------------------------------------------------------------------
+@dataclass
+class ValidationResult:
+    """Validation result for a single key, serialized as verify-credentials.py stdout JSON."""
+
+    ok: bool
+    type: str  # "tencent" | "trtc" | "llm" | "all"
+    error: str = ""           # Error code (E000~E004 or empty)
+    message: str = ""         # Human-readable description (no key plaintext)
+    latency_ms: int = 0
+
+    def to_dict(self) -> Dict:
+        return {
+            "ok": self.ok,
+            "type": self.type,
+            "error": self.error,
+            "message": self.message,
+            "latency_ms": self.latency_ms,
+        }
+
+
+@dataclass
+class BatchResult:
+    """Aggregate validation result (used when type=all)."""
+
+    ok: bool
+    items: List[ValidationResult] = field(default_factory=list)
+
+    def to_dict(self) -> Dict:
+        return {
+            "ok": self.ok,
+            "type": "all",
+            "items": [r.to_dict() for r in self.items],
+        }
+
+
+# ---------------------------------------------------------------------------
+# 4) .env loading (independent of dotenv, avoids extra dependencies)
+# ---------------------------------------------------------------------------
+def load_dotenv(env_path: Optional[Path] = None) -> Dict[str, str]:
+    """Read ``.env`` into ``os.environ``; returns newly added/overwritten key-value pairs.
+
+    Path priority: parameter > capabilities/conversation-core/.env > repo root .env.
+    Does not raise; returns empty dict if no file found.
+    """
+    candidates: List[Path] = []
+    if env_path is not None:
+        candidates.append(Path(env_path))
+    candidates.append(_CORE_DIR / ".env")
+    candidates.append(_ROOT / ".env")
+
+    seen: Dict[str, str] = {}
+    for c in candidates:
+        if not c.exists() or not c.is_file():
+            continue
+        try:
+            text = c.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            k = k.strip()
+            v = v.strip().strip('"').strip("'")
+            if k and k not in seen:
+                seen[k] = v
+                # 不覆盖已存在的进程级环境变量（CI / 容器优先）
+                os.environ.setdefault(k, v)
+        # 找到第一个就够；不再往下找以避免覆盖
+        if seen:
+            break
+    return seen
+
+
+# ---------------------------------------------------------------------------
+# 5) Single-key validation functions
+# ---------------------------------------------------------------------------
+def validate_tencent() -> ValidationResult:
+    """Validate Tencent Cloud API SecretId/SecretKey."""
+    mods = _imports()
+    creds = mods["load_from_env"]()
+    tc = creds.tencent_cloud
+    if not tc.configured:
+        return ValidationResult(
+            ok=False,
+            type="tencent",
+            error="E000",
+            message="TENCENT_CLOUD_SECRET_ID / TENCENT_CLOUD_SECRET_KEY not configured",
+        )
+    r = mods["check_tencent_cloud"](tc)
+    return ValidationResult(
+        ok=r.ok,
+        type="tencent",
+        error="" if r.ok else (r.error_code or "E001"),
+        message=r.detail if not r.ok else f"sts/GetFederationToken ok (region={tc.region})",
+        latency_ms=r.latency_ms,
+    )
+
+
+def validate_trtc(deep: bool = True) -> ValidationResult:
+    """Validate TRTC SDKAppId / SDKSecretKey.
+
+    When deep=True and Tencent Cloud API credentials are configured, calls
+    ``DescribeTRTCRealTimeQualityData`` for ownership verification;
+    otherwise only does local UserSig self-consistency check.
+    """
+    mods = _imports()
+    creds = mods["load_from_env"]()
+    trtc = creds.trtc
+    tc = creds.tencent_cloud if deep else None
+    if not trtc.configured:
+        return ValidationResult(
+            ok=False,
+            type="trtc",
+            error="E000",
+            message="TRTC_SDK_APP_ID / TRTC_SDK_SECRET_KEY not configured",
+        )
+    r = mods["check_trtc"](trtc, tencent=tc if (tc and tc.configured) else None)
+    return ValidationResult(
+        ok=r.ok,
+        type="trtc",
+        error="" if r.ok else (r.error_code or "E002"),
+        message=r.detail or ("usersig/openapi ok" if r.ok else "trtc check failed"),
+        latency_ms=r.latency_ms,
+    )
+
+
+def validate_llm() -> ValidationResult:
+    """Validate LLM API Key (OpenAI-compatible protocol)."""
+    mods = _imports()
+    creds = mods["load_from_env"]()
+    llm = creds.llm
+    if not llm.configured:
+        return ValidationResult(
+            ok=False,
+            type="llm",
+            error="E000",
+            message="LLM_API_KEY / LLM_API_URL / LLM_MODEL not configured",
+        )
+    r = mods["check_llm"](llm)
+    return ValidationResult(
+        ok=r.ok,
+        type="llm",
+        error="" if r.ok else (r.error_code or "E003"),
+        message=r.detail or (f"chat/completions 200 ok (model={llm.model})" if r.ok else "llm failed"),
+        latency_ms=r.latency_ms,
+    )
+
+
+def validate_all() -> BatchResult:
+    """Validate all three keys sequentially; any failure → ok=False."""
+    items = [validate_tencent(), validate_trtc(deep=True), validate_llm()]
+    return BatchResult(ok=all(i.ok for i in items), items=items)
+
+
+# ---------------------------------------------------------------------------
+# 6) Error code → hint (for CLI non-JSON mode; AI does not read this)
+# ---------------------------------------------------------------------------
+def hint(error_code: str) -> str:
+    return _ERROR_HINTS.get(error_code, "")
+
+
+# ---------------------------------------------------------------------------
+# 7) Self-test: allows `python -m scripts.lib.credential_validators` to run independently
+# ---------------------------------------------------------------------------
+def _self_test() -> int:
+    load_dotenv()
+    out = validate_all()
+    print(json.dumps(out.to_dict(), ensure_ascii=False, indent=2))
+    return 0 if out.ok else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(_self_test())

package/skills/trtc-ai-service/scripts/lib/curl_parser.py

@@ -0,0 +1,303 @@
+"""curl command parser (Phase 3 Stage 4).
+
+Parses curl commands pasted by users in the chat into unified ``ParsedApi`` data structures,
+consumed by ``contract_resolver`` and ``adapter_codegen``.
+
+Supported:
+- Multi-line (trailing ``\\``) / single-line
+- ``-X / --request <METHOD>``
+- ``-H / --header 'k: v'`` (accumulates on repeated appearances)
+- ``-d / --data / --data-raw / --data-binary '<body>'``
+- ``--url <url>`` or URL as a positional argument
+- Single-quoted / double-quoted strings (including escapes)
+- Auto-detect Authorization → ``bearer``; custom ``X-*-Token`` → ``api_key``
+- Auto-detect if body is JSON and extract ``request_schema`` fields accordingly
+
+Not supported (when protocol_mismatch=True, contract_resolver triggers L3 fallback):
+- multipart / form-data uploads
+- ``--cookie``
+- Non-JSON body (XML / GraphQL string body)
+"""
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse, urlsplit
+
+
+# ---------------------------------------------------------------------------
+# 数据结构
+# ---------------------------------------------------------------------------
+@dataclass
+class AuthSpec:
+    type: str = "none"          # bearer | api_key | basic | none
+    location: str = "header"    # header | query
+    name: str = ""              # header 名 / query 键名
+
+    def to_dict(self) -> Dict:
+        return {"type": self.type, "location": self.location, "name": self.name}
+
+
+@dataclass
+class ParsedApi:
+    """curl / OpenAPI 解析后的统一表示。"""
+
+    method: str = "GET"
+    base_url: str = ""              # https://crm.example.com
+    path: str = "/"                 # /api/v2/work_orders（不带 query）
+    query: Dict[str, str] = field(default_factory=dict)
+    headers: Dict[str, str] = field(default_factory=dict)
+    auth: AuthSpec = field(default_factory=AuthSpec)
+    request_schema: Dict[str, Any] = field(default_factory=dict)
+    response_schema: Dict[str, Any] = field(default_factory=dict)
+    body_format: str = "none"       # json | form | raw | none
+    body_sample: Any = None         # 原始 body（已解析为 dict / str）
+    source: str = "curl"            # curl | openapi
+    raw: str = ""                   # 原始输入（供 codegen 调试）
+
+    def to_dict(self) -> Dict:
+        return {
+            "method": self.method,
+            "base_url": self.base_url,
+            "path": self.path,
+            "query": dict(self.query),
+            "auth": self.auth.to_dict(),
+            # 注意：schema 已经在 parse 阶段标准化过；这里**不再**重复 normalize，
+            # 否则像 "string[]" 这类已 normalized 的字面量会被二次降级为 "string"
+            "request_schema": dict(self.request_schema),
+            "response_schema": dict(self.response_schema),
+            "body_format": self.body_format,
+            "source": self.source,
+        }
+
+
+# ---------------------------------------------------------------------------
+# 工具函数
+# ---------------------------------------------------------------------------
+def _normalize_schema(node: Any) -> Any:
+    """把任意 dict / list 标准化为"字段 → 类型字符串"递归视图。"""
+    if isinstance(node, dict):
+        out: Dict[str, Any] = {}
+        for k, v in node.items():
+            out[k] = _normalize_schema(v)
+        return out
+    if isinstance(node, list):
+        if not node:
+            return "array<any>"
+        # 同质数组取第一个递归
+        first = _normalize_schema(node[0])
+        if isinstance(first, str):
+            return f"{first}[]"
+        return [first]
+    if isinstance(node, str):
+        return "string"
+    if isinstance(node, bool):  # bool 必须在 int 之前判断
+        return "bool"
+    if isinstance(node, int):
+        return "int"
+    if isinstance(node, float):
+        return "float"
+    if node is None:
+        return "null"
+    return type(node).__name__
+
+
+def _split_url(url: str) -> Tuple[str, str, Dict[str, str]]:
+    """``https://a.com/b?c=1`` → (``https://a.com``, ``/b``, {c:'1'})"""
+    parts = urlsplit(url)
+    if not parts.scheme:
+        # 用户可能贴了相对路径 /tickets
+        return ("", url.split("?", 1)[0], _parse_query(url.split("?", 1)[1] if "?" in url else ""))
+    base = f"{parts.scheme}://{parts.netloc}"
+    path = parts.path or "/"
+    return (base, path, _parse_query(parts.query))
+
+
+def _parse_query(qs: str) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for pair in qs.split("&"):
+        if not pair:
+            continue
+        if "=" in pair:
+            k, _, v = pair.partition("=")
+            out[k] = v
+        else:
+            out[pair] = ""
+    return out
+
+
+_BEARER_RE = re.compile(r"^\s*Bearer\s+\S+\s*$", re.IGNORECASE)
+_BASIC_RE = re.compile(r"^\s*Basic\s+\S+\s*$", re.IGNORECASE)
+
+
+def _detect_auth(headers: Dict[str, str]) -> AuthSpec:
+    for k, v in headers.items():
+        if k.lower() == "authorization":
+            if _BEARER_RE.match(v):
+                return AuthSpec(type="bearer", location="header", name=k)
+            if _BASIC_RE.match(v):
+                return AuthSpec(type="basic", location="header", name=k)
+            return AuthSpec(type="bearer", location="header", name=k)
+        # 常见自定义鉴权头
+        if k.lower() in {"x-auth-token", "x-api-key", "x-access-token", "x-token"}:
+            return AuthSpec(type="api_key", location="header", name=k)
+    return AuthSpec(type="none", location="header", name="")
+
+
+# ---------------------------------------------------------------------------
+# 主解析逻辑
+# ---------------------------------------------------------------------------
+class CurlParseError(ValueError):
+    """curl 解析失败。"""
+
+
+def parse_curl(raw: str) -> ParsedApi:
+    """主入口：解析任意 curl 字符串。
+
+    Raises
+    ------
+    CurlParseError
+        当输入不是 curl 命令、缺少 URL、或无法 tokenize。
+    """
+    if not raw or not raw.strip():
+        raise CurlParseError("empty input")
+
+    # 1) 行尾 \ 拼接 + 去掉首个 curl 命令名
+    text = re.sub(r"\\\s*\n", " ", raw.strip())
+    # 替换非 ASCII 全角空格
+    text = text.replace("\u3000", " ")
+    try:
+        tokens = shlex.split(text, posix=True)
+    except ValueError as exc:  # 不闭合引号
+        raise CurlParseError(f"shell tokenize failed: {exc}") from exc
+    if not tokens:
+        raise CurlParseError("no tokens after split")
+
+    # 跳过 curl 命令头（兼容用户漏贴的情况）
+    if tokens[0].lower().endswith("curl"):
+        tokens = tokens[1:]
+
+    method: Optional[str] = None
+    url: Optional[str] = None
+    headers: Dict[str, str] = {}
+    body_raw: Optional[str] = None
+    body_format = "none"
+
+    i = 0
+    while i < len(tokens):
+        t = tokens[i]
+        if t in ("-X", "--request"):
+            method = tokens[i + 1].upper()
+            i += 2
+            continue
+        if t in ("-H", "--header"):
+            kv = tokens[i + 1]
+            if ":" in kv:
+                k, _, v = kv.partition(":")
+                headers[k.strip()] = v.strip()
+            i += 2
+            continue
+        if t in ("-d", "--data", "--data-raw", "--data-binary", "--data-ascii", "--json"):
+            body_raw = tokens[i + 1]
+            body_format = "json" if t == "--json" else "raw"
+            i += 2
+            continue
+        if t == "--url":
+            url = tokens[i + 1]
+            i += 2
+            continue
+        if t in ("-G", "--get"):
+            method = method or "GET"
+            i += 1
+            continue
+        if t in ("-u", "--user"):
+            # basic auth: user:pass → 仅识别为 basic，不存原值
+            headers.setdefault("Authorization", "Basic <redacted>")
+            i += 2
+            continue
+        if t in ("-X", "--include", "-i", "-I", "--head", "-v", "--verbose",
+                 "-s", "--silent", "-L", "--location", "-k", "--insecure",
+                 "--compressed", "-f", "--fail"):
+            # 控制类参数，跳过
+            i += 1
+            continue
+        if t.startswith("--") or t.startswith("-"):
+            # 不认识的选项，吃掉它（防御性：可能带值）
+            if i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
+                i += 2
+            else:
+                i += 1
+            continue
+        # 位置参数：第一个非选项 token 当作 URL
+        if url is None:
+            url = t
+        i += 1
+
+    if not url:
+        raise CurlParseError("no URL found in curl command")
+
+    # 推断 method
+    if method is None:
+        method = "POST" if body_raw is not None else "GET"
+
+    base_url, path, query = _split_url(url)
+
+    # 解析 body 为 JSON（best effort）
+    request_schema: Dict[str, Any] = {}
+    body_sample: Any = body_raw
+    if body_raw:
+        stripped = body_raw.strip()
+        if stripped.startswith("{") or stripped.startswith("["):
+            try:
+                parsed = json.loads(stripped)
+                body_sample = parsed
+                body_format = "json"
+                if isinstance(parsed, dict):
+                    request_schema = _normalize_schema(parsed)  # type: ignore[assignment]
+            except json.JSONDecodeError:
+                body_format = "raw"
+        elif "&" in stripped and "=" in stripped:
+            # 简易 form-urlencoded
+            body_format = "form"
+            request_schema = {k: "string" for k in _parse_query(stripped).keys()}
+
+    auth = _detect_auth(headers)
+
+    return ParsedApi(
+        method=method,
+        base_url=base_url,
+        path=path,
+        query=query,
+        headers=headers,
+        auth=auth,
+        request_schema=request_schema,
+        response_schema={},   # curl 命令本身没有响应；用户可在第 2 步贴响应
+        body_format=body_format,
+        body_sample=body_sample,
+        source="curl",
+        raw=raw,
+    )
+
+
+# ---------------------------------------------------------------------------
+# 可选：从 curl 注释或额外的"# response: {...}"块中提取响应样例
+# ---------------------------------------------------------------------------
+_RESPONSE_HINT_RE = re.compile(
+    r"#\s*(?:resp|response)\s*[:=]\s*(\{.*?\}|\[.*?\])",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def parse_curl_with_response(raw: str) -> ParsedApi:
+    """额外尝试从注释行中提取 ``# response: {...}`` 作为 response_schema。"""
+    api = parse_curl(raw)
+    m = _RESPONSE_HINT_RE.search(raw)
+    if m:
+        try:
+            api.response_schema = _normalize_schema(json.loads(m.group(1)))  # type: ignore[assignment]
+        except json.JSONDecodeError:
+            pass
+    return api

package/skills/trtc-ai-service/scripts/lib/degrader.py

@@ -0,0 +1,140 @@
+"""Three-tier fallback decision engine.
+
+Input: tech stack detection result + adapter execution result.
+Output: fallback level (L1 / L2 / L3) + user guidance content path.
+
+| Level | Trigger Condition                           | Agent Behavior                              |
+|:-----:|:--------------------------------------------|:--------------------------------------------|
+| L1    | tech_stack matches adapter + codegen OK     | Write directly into user project            |
+| L2    | tech_stack matches but codegen failed/conflict | Output INTEGRATION_GUIDE.md template + template code |
+| L3    | tech_stack not recognized or not supported  | Output generic REST API docs + SDK install commands |
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+class DegradeLevel(str, Enum):
+    L1_AUTO = "L1"
+    L2_GUIDED = "L2"
+    L3_MANUAL = "L3"
+
+
+@dataclass
+class DegradeDecision:
+    level: DegradeLevel
+    reason: str
+    adapter: Optional[str] = None
+    tech_stack: Optional[str] = None
+    artifacts: List[str] = None        # type: ignore[assignment]
+    remediation: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "level": self.level.value,
+            "reason": self.reason,
+            "tech_stack": self.tech_stack,
+            "adapter": self.adapter,
+            "artifacts": self.artifacts or [],
+            "remediation": self.remediation,
+        }
+
+
+def decide(
+    tech_stack: Optional[str],
+    adapter: Optional[str],
+    code_gen_ok: bool,
+    *,
+    fallback: Optional[Dict] = None,
+    code_gen_error: str = "",
+) -> DegradeDecision:
+    """根据上游信号产出降级决策。
+
+    Parameters
+    ----------
+    tech_stack
+        stack_detector.detect() 的 ``primary`` 字段。
+    adapter
+        manifest.integration.auto_adapters 中匹配到的适配器名。None 表示不支持。
+    code_gen_ok
+        L1 阶段实际尝试生成代码后的成功标志。
+    fallback
+        manifest.integration.fallback 节点内容（提供 guided_templates / manual_api）。
+    code_gen_error
+        L1 失败时的错误描述（写入 reason）。
+    """
+    fb = fallback or {}
+    if tech_stack and adapter and code_gen_ok:
+        return DegradeDecision(
+            level=DegradeLevel.L1_AUTO,
+            reason="tech stack matched and code generation succeeded",
+            tech_stack=tech_stack,
+            adapter=adapter,
+            artifacts=[],
+            remediation="",
+        )
+    if tech_stack and adapter and not code_gen_ok:
+        templates = list(fb.get("guided_templates") or [])
+        return DegradeDecision(
+            level=DegradeLevel.L2_GUIDED,
+            reason=code_gen_error
+            or "tech stack matched but code generation failed; provide manual guide",
+            tech_stack=tech_stack,
+            adapter=adapter,
+            artifacts=templates,
+            remediation=(
+                "Agent outputs INTEGRATION_GUIDE.md: includes template code + injection position notes; "
+                "user completes integration manually following the docs"
+            ),
+        )
+    # L3：未识别或无适配器
+    manual = fb.get("manual_api") or {}
+    artifacts = []
+    if manual.get("rest_endpoint"):
+        artifacts.append(f"rest_endpoint:{manual['rest_endpoint']}")
+    for sdk in manual.get("sdk_packages") or []:
+        for ecos, pkg in sdk.items():
+            artifacts.append(f"sdk:{ecos}:{pkg}")
+    return DegradeDecision(
+        level=DegradeLevel.L3_MANUAL,
+        reason=(
+            "tech stack not recognised or not in supported list"
+            if not tech_stack
+            else f"no adapter for tech_stack={tech_stack}"
+        ),
+        tech_stack=tech_stack,
+        adapter=None,
+        artifacts=artifacts,
+        remediation=(
+            "Agent outputs generic REST API integration docs (base URL /api/v1)"
+            " + SDK package install commands; integrator connects manually."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# I/O modality fallback matrix: 4 independent channel toggles → 16 combinations, ensuring a viable path for each
+# ---------------------------------------------------------------------------
+def channel_combinations_matrix() -> List[Dict]:
+    """Return the fallback paths for all 16 channel combinations (used for docs & testing)."""
+    rows: List[Dict] = []
+    channels = ["voice_input", "text_input", "voice_output", "text_output"]
+    for mask in range(16):
+        state = {c: bool(mask & (1 << i)) for i, c in enumerate(channels)}
+        usable_in = state["voice_input"] or state["text_input"]
+        usable_out = state["voice_output"] or state["text_output"]
+        if not usable_in and not usable_out:
+            verdict = "silent_wait"  # upper layer enters silent wait
+        elif not usable_in:
+            verdict = "output_only_broadcast"
+        elif not usable_out:
+            verdict = "input_only_logging"
+        else:
+            primary_in = "voice_input" if state["voice_input"] else "text_input"
+            primary_out = "voice_output" if state["voice_output"] else "text_output"
+            verdict = f"primary={primary_in}->{primary_out}"
+        rows.append({"state": state, "verdict": verdict})
+    return rows