@tencent-rtc/trtc-agent-skills 0.1.0

package/skills/trtc-topic/runtime/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "trtc-topic-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Runtime telemetry bridge for TRTC topic skill (Web platform)",
+  "type": "module",
+  "scripts": {
+    "start": "node telemetry-bridge.mjs"
+  },
+  "dependencies": {
+    "puppeteer": "^23.0.0"
+  }
+}

package/skills/trtc-topic/runtime/telemetry-bridge.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// skills/trtc-topic/runtime/telemetry-bridge.mjs
+//
+// Web telemetry bridge for runtime log collection.
+//
+// Two modes:
+//   Mode A (default, visible): Launches a visible Chrome window + Vite dev
+//     server. User interacts directly in the Puppeteer-managed browser.
+//   Mode B (--connect): Connects to user's existing Chrome via CDP. No new
+//     browser launched, no Vite started. Attaches to the page matching the URL.
+//
+// In both modes, every page console event is forwarded as raw text to stdout,
+// which telemetry_collector.py pipes into .trtc-telemetry/runtime.log.
+
+import { spawn } from "node:child_process";
+import { connect as tcpConnect } from "node:net";
+import process from "node:process";
+
+// ---------------------------------------------------------------------------
+// Argv parsing
+// ---------------------------------------------------------------------------
+function parseArgv(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+    else if (a === "--workspace") out.workspace = argv[++i];
+    else if (a === "--connect") out.connect = argv[++i];
+  }
+  const missing = ["url", "workspace"].filter((k) => !out[k]);
+  if (missing.length) {
+    process.stderr.write(
+      `telemetry-bridge: missing required args: ${missing.join(", ")}\n` +
+        `usage: node telemetry-bridge.mjs --url <u> --workspace <path> [--connect <endpoint>]\n` +
+        `\n` +
+        `Modes:\n` +
+        `  (default)             Launch visible Chrome + Vite dev server\n` +
+        `  --connect <endpoint>  Connect to existing Chrome via CDP\n` +
+        `                        e.g. --connect http://localhost:9222\n`,
+    );
+    process.exit(2);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// TCP port probe
+// ---------------------------------------------------------------------------
+function parsePort(url) {
+  const m = url.match(/:(\d+)(?:\/|$)/);
+  return m ? Number.parseInt(m[1], 10) : 80;
+}
+
+function probeTcp(host, port, timeoutMs) {
+  return new Promise((resolve) => {
+    const socket = tcpConnect({ host, port });
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    setTimeout(() => finish(false), timeoutMs);
+  });
+}
+
+async function findFreePort(host, start, span) {
+  for (let p = start; p < start + span; p++) {
+    const occupied = await probeTcp(host, p, 200);
+    if (!occupied) return p;
+  }
+  return null;
+}
+
+async function waitForPort(host, port, attempts, intervalMs) {
+  for (let i = 0; i < attempts; i++) {
+    if (await probeTcp(host, port, intervalMs)) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Raw log emitter — outputs console text as-is, like Chrome DevTools
+// ---------------------------------------------------------------------------
+function emitRaw(line) {
+  process.stdout.write(line + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Attach console listeners to a page
+// ---------------------------------------------------------------------------
+function attachPageListeners(page) {
+  page.on("console", (msg) => {
+    let text;
+    try { text = msg.text(); } catch { text = String(msg); }
+    const location = msg.location();
+    const source = location && location.url
+      ? `${location.url.split("/").pop()}:${location.lineNumber ?? 0}`
+      : "";
+    const prefix = source ? `${source} ` : "";
+    emitRaw(`${prefix}${text}`);
+  });
+
+  page.on("pageerror", (err) => {
+    const message = err && err.message ? err.message : String(err);
+    emitRaw(`[pageerror] ${message}`);
+  });
+
+  page.on("requestfailed", (req) => {
+    const failure = req.failure();
+    emitRaw(`[requestfailed] ${req.url()} :: ${failure ? failure.errorText : "unknown"}`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Mode A: Launch visible browser + Vite dev server
+// ---------------------------------------------------------------------------
+async function modeVisible(puppeteer, url, workspace) {
+  const host = "localhost";
+  const requestedPort = parsePort(url);
+
+  // Find free port
+  const chosenPort = await findFreePort(host, requestedPort, 20);
+  if (chosenPort === null) {
+    emitRaw(`telemetry-bridge: no free port in [${requestedPort}, ${requestedPort + 20})`);
+    process.exit(1);
+  }
+  if (chosenPort !== requestedPort) {
+    emitRaw(`telemetry-bridge: port ${requestedPort} occupied; using ${chosenPort}`);
+  }
+  const targetUrl = url.replace(`:${requestedPort}`, `:${chosenPort}`);
+
+  // Spawn Vite dev server
+  const vite = spawn("npm", ["run", "dev", "--", "--port", String(chosenPort), "--strictPort"], {
+    cwd: workspace,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let viteExited = false;
+  vite.on("exit", (code, signal) => {
+    viteExited = true;
+    emitRaw(`telemetry-bridge: vite exited code=${code} signal=${signal || ""}`);
+  });
+  vite.stdout.resume();
+  vite.stderr.on("data", (chunk) => {
+    const text = chunk.toString("utf8").trimEnd();
+    if (text) emitRaw(`[vite] ${text}`);
+  });
+
+  // Wait for dev server
+  const ready = await waitForPort(host, chosenPort, 60, 1000);
+  if (!ready || viteExited) {
+    emitRaw(`telemetry-bridge: vite not ready on port ${chosenPort}`);
+    try { vite.kill("SIGTERM"); } catch {}
+    process.exit(1);
+  }
+
+  // Launch VISIBLE browser (headless: false)
+  let browser;
+  try {
+    browser = await puppeteer.launch({
+      headless: false,
+      args: [
+        "--no-sandbox",
+        "--disable-dev-shm-usage",
+        "--use-fake-ui-for-media-stream",
+        "--use-fake-device-for-media-stream",
+      ],
+    });
+  } catch (e) {
+    emitRaw(`telemetry-bridge: chromium launch failed: ${e.message}`);
+    try { vite.kill("SIGTERM"); } catch {}
+    process.exit(1);
+  }
+
+  const page = await browser.newPage();
+
+  // Install error probes before page load
+  await page.evaluateOnNewDocument(() => {
+    const tag = (probe, payload) =>
+      console.log(JSON.stringify({ __probe: probe, ...payload }));
+    window.addEventListener("error", (e) => {
+      tag("page_error", { message: (e && e.message) || String(e), filename: e && e.filename, lineno: e && e.lineno });
+    });
+    window.addEventListener("unhandledrejection", (e) => {
+      const reason = e && e.reason;
+      tag("unhandled_rejection", { message: reason && reason.message ? reason.message : String(reason) });
+    });
+  });
+
+  // Attach console listeners
+  attachPageListeners(page);
+
+  // Navigate
+  try {
+    await page.goto(targetUrl, { waitUntil: "domcontentloaded", timeout: 30_000 });
+  } catch (e) {
+    emitRaw(`telemetry-bridge: page.goto failed url=${targetUrl} err=${e.message}`);
+  }
+
+  emitRaw(`telemetry-bridge: [visible mode] page loaded at ${targetUrl}, capturing events...`);
+
+  // Shutdown handler — ensure Chromium is fully closed before exit
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    try { await browser.close(); } catch {}
+    try { vite.kill("SIGTERM"); } catch {}
+    // Give Vite a moment to exit gracefully, then force-kill
+    await new Promise((r) => setTimeout(r, 500));
+    try { if (!viteExited) vite.kill("SIGKILL"); } catch {}
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
+// ---------------------------------------------------------------------------
+// Mode B: Connect to existing Chrome via CDP
+// ---------------------------------------------------------------------------
+async function modeConnect(puppeteer, connectEndpoint, targetUrl) {
+  emitRaw(`telemetry-bridge: [connect mode] connecting to ${connectEndpoint}`);
+
+  // Connect to existing browser
+  let browser;
+  try {
+    if (connectEndpoint.startsWith("ws://") || connectEndpoint.startsWith("wss://")) {
+      browser = await puppeteer.connect({ browserWSEndpoint: connectEndpoint });
+    } else {
+      browser = await puppeteer.connect({ browserURL: connectEndpoint });
+    }
+  } catch (e) {
+    emitRaw(`telemetry-bridge: failed to connect to browser at ${connectEndpoint}: ${e.message}`);
+    emitRaw(`Hint: Start Chrome with --remote-debugging-port=9222`);
+    process.exit(1);
+  }
+
+  emitRaw(`telemetry-bridge: connected to browser`);
+
+  // Find the target page
+  const pages = await browser.pages();
+  const targetPort = parsePort(targetUrl);
+  let page = pages.find((p) => {
+    const u = p.url();
+    return u.includes(`localhost:${targetPort}`) || u.includes(`127.0.0.1:${targetPort}`);
+  });
+
+  if (!page) {
+    // Try matching by full URL
+    page = pages.find((p) => p.url().includes(targetUrl));
+  }
+
+  if (!page) {
+    emitRaw(`telemetry-bridge: no page found matching ${targetUrl}. Listing open pages:`);
+    for (const p of pages) {
+      emitRaw(`  - ${p.url()}`);
+    }
+    if (pages.length > 0) {
+      emitRaw(`telemetry-bridge: attaching to first available page. Open ${targetUrl} in the browser to capture its events.`);
+      page = pages[0];
+    } else {
+      emitRaw(`telemetry-bridge: no pages found in browser`);
+      await browser.disconnect();
+      process.exit(1);
+    }
+  } else {
+    emitRaw(`telemetry-bridge: found target page: ${page.url()}`);
+  }
+
+  // Attach console listeners
+  attachPageListeners(page);
+
+  // Also listen for new pages (user might navigate or open new tabs)
+  browser.on("targetcreated", async (target) => {
+    if (target.type() === "page") {
+      try {
+        const newPage = await target.page();
+        if (newPage) {
+          const newUrl = newPage.url();
+          if (newUrl.includes(`localhost:${targetPort}`) || newUrl.includes(`127.0.0.1:${targetPort}`)) {
+            emitRaw(`telemetry-bridge: new matching page detected: ${newUrl}`);
+            attachPageListeners(newPage);
+          }
+        }
+      } catch {}
+    }
+  });
+
+  emitRaw(`telemetry-bridge: [connect mode] capturing events from ${page.url()}...`);
+
+  // Shutdown handler — disconnect only, don't close user's browser
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    emitRaw(`telemetry-bridge: disconnecting (browser stays open)`);
+    try { await browser.disconnect(); } catch {}
+    setTimeout(() => process.exit(0), 100).unref();
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  const args = parseArgv(process.argv.slice(2));
+  const { url, workspace, connect: connectEndpoint } = args;
+
+  emitRaw(`telemetry-bridge: starting (mode=${connectEndpoint ? "connect" : "visible"})`);
+
+  // Import Puppeteer
+  let puppeteer;
+  try {
+    puppeteer = (await import("puppeteer")).default;
+  } catch (e) {
+    emitRaw(`telemetry-bridge: puppeteer import failed: ${e.message}. Run \`cd runtime && npm install\`.`);
+    process.exit(1);
+  }
+
+  if (connectEndpoint) {
+    await modeConnect(puppeteer, connectEndpoint, url);
+  } else {
+    await modeVisible(puppeteer, url, workspace);
+  }
+
+  // Keep alive — shutdown is driven by SIGTERM from telemetry_collector.py
+  setInterval(() => {}, 60_000).unref();
+}
+
+main().catch((e) => {
+  emitRaw(`telemetry-bridge: fatal ${e && e.stack ? e.stack : e}`);
+  process.exit(1);
+});

package/skills/trtc-topic/runtime/telemetry_collector.py

@@ -0,0 +1,293 @@
+"""telemetry_collector.py — Start/stop runtime log collection.
+
+Usage:
+    python3 telemetry_collector.py --mode start --platform web --workspace /path/to/project
+    python3 telemetry_collector.py --mode stop --workspace /path/to/project
+
+Starts a platform-specific log stream process in the background, piping its
+stdout to <workspace>/.trtc-telemetry/runtime.log. Stores the PID for later
+stop.
+
+On stop: kills processes → filters errors from runtime.log → writes
+runtime_error.log + runtime_context.json for MCP upload.
+"""
+import argparse
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from lib.platforms import discover_devices, log_stream_command
+
+
+# ---------------------------------------------------------------------------
+# Error filtering patterns
+# ---------------------------------------------------------------------------
+
+# Match: lines that are actual SDK errors
+_ERROR_PATTERNS = [
+    re.compile(r"<ERROR>"),
+    re.compile(r"error_code:\s*[1-9]\d*"),  # Non-zero error_code
+]
+
+# Exclude: false positives (skip even if _ERROR_PATTERNS match)
+_ERROR_EXCLUSIONS = [
+    re.compile(r"telemetry-bridge:"),
+    re.compile(r"favicon\.ico.*404"),
+    re.compile(r"AudioContext was not allowed"),
+    re.compile(r"\[↑t\d\] on error"),         # Event listener registration
+    re.compile(r"error_code:\s*0"),            # Success callback
+    re.compile(r"error_message:\s*success"),   # Success callback
+]
+
+# ---------------------------------------------------------------------------
+# Context extraction patterns
+# ---------------------------------------------------------------------------
+
+_CONTEXT_EXTRACTORS = {
+    "trtc_web":    re.compile(r"TRTC Web SDK Version:\s*([\d.\w-]+)"),
+    "trtc_cloud":  re.compile(r"TRTCCloud Version:\s*([\d.]+)"),
+    "room_engine": re.compile(r"TUIRoomEngine Web SDK Version:\s*([\d.]+)"),
+    "chat_engine": re.compile(r"TUIChatEngine-Lite\.VERSION:([\d.]+)"),
+    "os":          re.compile(r"<INFO> OS:\s*(.+)"),
+    "sdk_app_id":  re.compile(r"sdkAppId=(\d+)"),
+    "user_id":     re.compile(r"userId=(\w+)"),
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _telemetry_dir(workspace: Path) -> Path:
+    """Return the .trtc-telemetry directory inside the workspace."""
+    d = workspace / ".trtc-telemetry"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _filter_errors(runtime_log: Path, error_log: Path) -> list[str]:
+    """Filter error lines from runtime.log, write to runtime_error.log."""
+    if not runtime_log.exists() or runtime_log.stat().st_size == 0:
+        return []
+
+    errors: list[str] = []
+    try:
+        with open(runtime_log, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line_stripped = line.strip()
+                if not line_stripped:
+                    continue
+                # Check exclusions first
+                if any(exc.search(line_stripped) for exc in _ERROR_EXCLUSIONS):
+                    continue
+                # Check if line matches any error pattern
+                if any(pat.search(line_stripped) for pat in _ERROR_PATTERNS):
+                    errors.append(line_stripped)
+    except OSError:
+        return []
+
+    # Write error log (overwrite)
+    if errors:
+        try:
+            error_log.write_text("\n".join(errors) + "\n", encoding="utf-8")
+        except OSError:
+            pass
+    else:
+        # Clear previous error log if no errors this run
+        try:
+            error_log.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+    return errors
+
+
+def _extract_context(runtime_log: Path, context_file: Path) -> None:
+    """Extract environment context from runtime.log, write to runtime_context.json."""
+    if not runtime_log.exists() or runtime_log.stat().st_size == 0:
+        return
+
+    sdk_versions: dict[str, str] = {}
+    context: dict[str, str] = {}
+
+    version_keys = {"trtc_web", "trtc_cloud", "room_engine", "chat_engine"}
+
+    try:
+        with open(runtime_log, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                for key, pattern in _CONTEXT_EXTRACTORS.items():
+                    if key in sdk_versions or key in context:
+                        continue  # Already found
+                    m = pattern.search(line)
+                    if m:
+                        value = m.group(1).strip()
+                        if key in version_keys:
+                            sdk_versions[key] = value
+                        else:
+                            context[key] = value
+                # Early exit if all found
+                if len(sdk_versions) + len(context) == len(_CONTEXT_EXTRACTORS):
+                    break
+    except OSError:
+        return
+
+    result = {}
+    if sdk_versions:
+        result["sdk_versions"] = sdk_versions
+    if context.get("os"):
+        result["os"] = context["os"]
+    if context.get("sdk_app_id"):
+        result["sdk_app_id"] = context["sdk_app_id"]
+    if context.get("user_id"):
+        result["user_id"] = context["user_id"]
+
+    if result:
+        try:
+            context_file.write_text(
+                json.dumps(result, indent=2, ensure_ascii=False) + "\n",
+                encoding="utf-8",
+            )
+        except OSError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Start / Stop
+# ---------------------------------------------------------------------------
+
+def _start(platform: str, workspace: Path, connect: str | None = None) -> int:
+    """Start log collection in the background."""
+    tel_dir = _telemetry_dir(workspace)
+    runtime_log = tel_dir / "runtime.log"
+    pid_file = tel_dir / "collector.pid"
+
+    # Check if already running
+    if pid_file.exists():
+        pid = int(pid_file.read_text().strip())
+        try:
+            os.kill(pid, 0)  # Check if process exists
+            print(json.dumps({
+                "status": "already_running",
+                "pid": pid,
+            }))
+            return 0
+        except ProcessLookupError:
+            pid_file.unlink(missing_ok=True)
+
+    # Discover device
+    devices = discover_devices(platform)
+    if not devices:
+        print(json.dumps({
+            "status": "error",
+            "message": f"No {platform} device found.",
+        }))
+        return 1
+
+    device = devices[0]
+
+    # Get log stream command
+    try:
+        cmd = log_stream_command(platform, device, workspace=workspace, connect=connect)
+    except ValueError as e:
+        print(json.dumps({"status": "error", "message": str(e)}))
+        return 1
+
+    # Launch in background, stdout → runtime.log (truncate previous)
+    f = open(runtime_log, "wb")
+    try:
+        proc = subprocess.Popen(
+            cmd,
+            stdout=f,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,  # Create new process group for clean kill
+        )
+    except FileNotFoundError as e:
+        f.close()
+        print(json.dumps({"status": "error", "message": f"Command not found: {e}"}))
+        return 1
+
+    pid_file.write_text(str(proc.pid))
+
+    print(json.dumps({
+        "status": "started",
+        "pid": proc.pid,
+        "platform": platform,
+        "device": device.name or device.id,
+    }))
+    return 0
+
+
+def _stop(workspace: Path) -> int:
+    """Stop log collection, filter errors, extract context."""
+    tel_dir = _telemetry_dir(workspace)
+    pid_file = tel_dir / "collector.pid"
+
+    if not pid_file.exists():
+        print(json.dumps({"status": "not_running"}))
+        return 0
+
+    pid = int(pid_file.read_text().strip())
+
+    # Kill the entire process group (node + Chromium + Vite) to avoid orphans
+    try:
+        os.killpg(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        pass
+    except PermissionError:
+        # Fallback: kill just the main process if group kill fails
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+
+    # Wait briefly for graceful shutdown (browser.close() in bridge)
+    time.sleep(1)
+
+    # Force-kill any remaining processes in the group
+    try:
+        os.killpg(pid, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        pass
+
+    pid_file.unlink(missing_ok=True)
+
+    # --- Post-stop: filter errors + extract context ---
+    runtime_log = tel_dir / "runtime.log"
+    error_log = tel_dir / "runtime_error.log"
+    context_file = tel_dir / "runtime_context.json"
+
+    errors = _filter_errors(runtime_log, error_log)
+    _extract_context(runtime_log, context_file)
+
+    print(json.dumps({
+        "status": "stopped",
+        "errors_found": len(errors),
+    }))
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Runtime telemetry collector (start/stop)")
+    ap.add_argument("--mode", required=True, choices=["start", "stop"])
+    ap.add_argument("--platform", choices=["web", "ios", "android"], default="web")
+    ap.add_argument("--workspace", required=True, help="Path to the user's project")
+    ap.add_argument("--connect", default=None,
+                    help="CDP endpoint to connect to existing browser (e.g. http://localhost:9222)")
+    args = ap.parse_args()
+
+    workspace = Path(args.workspace).resolve()
+
+    if args.mode == "start":
+        return _start(args.platform, workspace, connect=args.connect)
+    else:
+        return _stop(workspace)
+
+
+if __name__ == "__main__":
+    sys.exit(main())