coze_lab 0.1.26 → 0.1.28

package/index.js

@@ -103,6 +103,18 @@ function successBox(lines) {
 // ─── 2. Script loading (scripts live as real files under ./scripts) ───────────
 const SCRIPTS_DIR = require('path').join(__dirname, 'scripts');
 
+// OpenClaw 插件版本：来自 scripts/openclaw/package.json。写进 openclaw.json 的 pcfg，
+// 参与 isOpenClawAlreadyInjected 幂等比对——插件代码升级（bump 该 version）后即使
+// token/endpoint/workspace 不变也会被判定为“需更新”，强制重写插件文件 + npm install +
+// gateway restart，避免旧插件 dist 滞留在云端 pluginDir 里不生效。
+const OPENCLAW_PLUGIN_VERSION = (() => {
+  try {
+    return require('./scripts/openclaw/package.json').version || '';
+  } catch {
+    return '';
+  }
+})();
+
 // Read a single script file (Python hook / refresh) as a UTF-8 string.
 function readScript(relPath) {
   return require('fs').readFileSync(require('path').join(SCRIPTS_DIR, relPath), 'utf8');
@@ -216,15 +228,21 @@ def _refresh_token(refresh_token: str) -> Optional[str]:
         req = urllib.request.Request(
             f"{_COZE_API}/api/permission/oauth2/token",
             data=payload,
-            headers={"Content-Type": "application/json"},
+            headers={
+                "Content-Type": "application/json",
+                "x-tt-env": "ppe_cozelab",
+                "x-use-ppe": "1",
+            },
         )
         with urllib.request.urlopen(req, timeout=10) as resp:
             data = json.loads(resp.read())
         if data.get("access_token"):
+            existing = _load_credentials() or {}
             creds = {
                 "access_token": data["access_token"],
                 "refresh_token": data.get("refresh_token", refresh_token),
                 "expires_at": data.get("expires_in", 0) * 1000,  # unix timestamp in seconds
+                "workspace_id": existing.get("workspace_id", ""),
             }
             _save_credentials(creds)
             debug_log("Token refreshed successfully.")
@@ -233,22 +251,34 @@ def _refresh_token(refresh_token: str) -> Optional[str]:
         debug_log(f"Token refresh failed: {e}")
     return None
 
+def _token_from_credentials() -> Optional[str]:
+    creds = _load_credentials()
+    if not creds:
+        return None
+    expires_at_sec = creds.get("expires_at", 0) / 1000
+    remaining = expires_at_sec - time.time()
+    if remaining > _REFRESH_THRESHOLD:
+        debug_log(f"Cached token valid, expires in {int(remaining)}s.")
+        return creds.get("access_token")
+    if creds.get("refresh_token"):
+        debug_log(f"Token expiring in {int(remaining)}s, refreshing...")
+        new_token = _refresh_token(creds["refresh_token"])
+        if new_token:
+            return new_token
+        debug_log("Refresh failed.")
+    return None
+
 def get_fresh_token() -> Optional[str]:
-    """Return a valid access token, refreshing if needed. Falls back to env var."""
+    """Return a valid access token, refreshing if needed."""
+    env_token = os.environ.get("COZELOOP_API_TOKEN")
+    env_coze_token = os.environ.get("COZE_API_TOKEN")
+    is_cloud = os.environ.get("COZELAB_ONBOARD_CLOUD", "").lower() in ("1", "true", "yes")
+    if is_cloud:
+        return env_token or env_coze_token or _token_from_credentials()
     creds = _load_credentials()
     if creds:
-        expires_at_sec = creds.get("expires_at", 0) / 1000
-        remaining = expires_at_sec - time.time()
-        if remaining > _REFRESH_THRESHOLD:
-            debug_log(f"Cached token valid, expires in {int(remaining)}s.")
-            return creds["access_token"]
-        if creds.get("refresh_token"):
-            debug_log(f"Token expiring in {int(remaining)}s, refreshing...")
-            new_token = _refresh_token(creds["refresh_token"])
-            if new_token:
-                return new_token
-            debug_log("Refresh failed, falling back to env var.")
-    return os.environ.get("COZELOOP_API_TOKEN")
+        return _token_from_credentials()
+    return env_token or env_coze_token
 
 # -------------------------------------------------------------------------
 
@@ -1334,6 +1364,125 @@ from typing import Optional, List, Dict, Any
 _COZELOOP_CLIENT_ID = "46371084383473718052118955183420.app.coze"
 _COZE_API = "https://api.coze.cn"
 _REFRESH_THRESHOLD = 10 * 60
+_DEFAULT_WORKSPACE_ID = "7644910356078837760"  # hardcoded spaceID fallback
+_OTEL_SUFFIX = "/v1/loop/opentelemetry"
+
+
+# --- coze-context parsing -------------------------------------------------
+# User messages may embed a block like:
+#   <coze-context>
+#   account_id: 0
+#   agent_id: 7644920552473395499
+#   session_id: 7644919579054997796
+#   message_id: 04dd5246-...
+#   </coze-context>
+# We parse its key:value pairs and inject them into the trace.
+
+_COZE_CTX_OPEN = "<coze-context>"
+_COZE_CTX_CLOSE = "</coze-context>"
+
+
+def parse_coze_context(text: str) -> Dict[str, str]:
+    """Extract the LAST <coze-context> block's key:value pairs from text.
+
+    Returns {} if no block is present. Tag keys are prefixed with
+    'coze_' by the caller; here we return raw keys as written.
+    """
+    if not text or _COZE_CTX_OPEN not in text:
+        return {}
+    # Take the last occurrence (latest context wins).
+    open_idx = text.rfind(_COZE_CTX_OPEN)
+    close_idx = text.find(_COZE_CTX_CLOSE, open_idx)
+    if close_idx == -1:
+        return {}
+    body = text[open_idx + len(_COZE_CTX_OPEN):close_idx]
+    # The block may arrive with real newlines, OR with literal backslash-n
+    # (e.g. when the whole message is an embedded JSON string that was never
+    # un-escaped). Normalize both forms before splitting into lines.
+    body = body.replace("\\r\\n", "\n").replace("\\n", "\n").replace("\\r", "\n")
+    result: Dict[str, str] = {}
+    for line in body.splitlines():
+        line = line.strip()
+        if not line or ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if key:
+            result[key] = value
+    return result
+
+
+def coze_context_tags(text: str) -> Dict[str, str]:
+    """Return coze-context kv as trace tags, prefixed with 'coze_'."""
+    return {f"coze_{k}": v for k, v in parse_coze_context(text).items()}
+
+
+def turn_coze_context(turn: Dict[str, Any]) -> Dict[str, str]:
+    """Extract coze-context from a grouped turn with fallbacks for Codex rollout shapes."""
+    texts = [turn.get("user_message_text", "")]
+    for msg in turn.get("input_messages", []):
+        if isinstance(msg, dict):
+            texts.append(str(msg.get("content", "")))
+    user_payload = turn.get("user_message")
+    if isinstance(user_payload, dict):
+        texts.append(extract_message_content_text(user_payload))
+    for text in texts:
+        ctx = parse_coze_context(text)
+        if ctx:
+            return ctx
+    return {}
+
+
+# --- trace upload failure / logid capture ---------------------------------
+def _extract_logid(msg: str) -> str:
+    """Pull the server logid out of an SDK error message, if present.
+
+    SDK failure messages embed it as 'logid=XXXX' (sometimes within brackets).
+    """
+    if not msg:
+        return ""
+    marker = "logid="
+    idx = msg.find(marker)
+    if idx == -1:
+        return ""
+    rest = msg[idx + len(marker):]
+    logid = []
+    for ch in rest:
+        if ch.isalnum():
+            logid.append(ch)
+        else:
+            break
+    return "".join(logid)
+
+
+def _make_finish_event_processor(upload_events: Optional[List[str]] = None):
+    """Return a trace_finish_event_processor that surfaces failures + logid.
+
+    The CozeLoop SDK calls this for each flush event; on failure we print the
+    server logid to stderr so it can be handed to platform support for tracing
+    the root cause (e.g. via \`bytedcli log get-logid-log <logid>\`).
+    """
+    def _processor(info):
+        try:
+            if not getattr(info, "is_event_fail", False):
+                hook_log("upload success")
+                return
+            detail = getattr(info, "detail_msg", "") or ""
+            if upload_events is not None:
+                upload_events.append(detail or "trace export failed")
+            logid = _extract_logid(detail)
+            if logid:
+                hook_log(f"upload failed logid={logid} detail={detail[:500]}")
+                print(f"[CozeLoop] 上报失败 logid={logid} (可用 bytedcli log get-logid-log {logid} 排查)", file=sys.stderr)
+            else:
+                hook_log(f"upload failed detail={detail[:500]}")
+                print(f"[CozeLoop] 上报失败: {detail[:300]}", file=sys.stderr)
+        except Exception:
+            pass
+    return _processor
+
+
 
 def _get_credentials_path() -> Path:
     return Path.home() / ".cozeloop" / "credentials.json"
@@ -1363,15 +1512,21 @@ def _refresh_token(refresh_tok: str):
         req = urllib.request.Request(
             f"{_COZE_API}/api/permission/oauth2/token",
             data=payload,
-            headers={"Content-Type": "application/json"},
+            headers={
+                "Content-Type": "application/json",
+                "x-tt-env": "ppe_cozelab",
+                "x-use-ppe": "1",
+            },
         )
         with urllib.request.urlopen(req, timeout=10) as resp:
             data = json.loads(resp.read())
         if data.get("access_token"):
+            existing = _load_credentials() or {}
             creds = {
                 "access_token": data["access_token"],
                 "refresh_token": data.get("refresh_token", refresh_tok),
-                "expires_at": data.get("expires_in", 0) * 1000  # unix timestamp in seconds
+                "expires_at": data.get("expires_in", 0) * 1000,  # unix timestamp in seconds
+                "workspace_id": existing.get("workspace_id", ""),
             }
             _save_credentials(creds)
             return creds["access_token"]
@@ -1379,37 +1534,168 @@ def _refresh_token(refresh_tok: str):
         pass
     return None
 
+
+def _normalize_api_base_url(url: str) -> str:
+    base = (url or "").strip().rstrip("/")
+    if base.endswith(_OTEL_SUFFIX + "/v1/traces"):
+        return base[:-len(_OTEL_SUFFIX + "/v1/traces")].rstrip("/")
+    if base.endswith("/api/v1/loop/opentelemetry/v1/traces"):
+        return base[:-len("/v1/loop/opentelemetry/v1/traces")].rstrip("/")
+    if base.endswith(_OTEL_SUFFIX):
+        return base[:-len(_OTEL_SUFFIX)].rstrip("/")
+    if base.endswith("/api/v1/loop/opentelemetry"):
+        return base[:-len("/v1/loop/opentelemetry")].rstrip("/")
+    if base.endswith("/api/v1"):
+        return base[:-len("/v1")].rstrip("/")
+    return base
+
+
+def get_api_base_url() -> str:
+    return _normalize_api_base_url(
+        os.environ.get("COZELOOP_API_BASE_URL", "")
+    )
+
+
+def _token_from_credentials():
+    creds = _load_credentials()
+    if not creds:
+        return None
+    remaining = creds.get("expires_at", 0) / 1000 - time.time()
+    if remaining > _REFRESH_THRESHOLD:
+        return creds.get("access_token")
+    if creds.get("refresh_token"):
+        new_token = _refresh_token(creds["refresh_token"])
+        if new_token:
+            return new_token
+    return None
+
+
 def get_fresh_token():
+    env_token = os.environ.get("COZELOOP_API_TOKEN")
+    env_coze_token = os.environ.get("COZE_API_TOKEN")
+    is_cloud = os.environ.get("COZELAB_ONBOARD_CLOUD", "").lower() in ("1", "true", "yes")
+    if is_cloud:
+        return env_token or env_coze_token or _token_from_credentials()
+
+    # Local onboard used to write a short-lived access token into cozeloop.env.
+    # If credentials exist but cannot be refreshed, do not fall back to that stale
+    # env token; failing closed keeps state from advancing on a known-bad token.
     creds = _load_credentials()
     if creds:
-        remaining = creds.get("expires_at", 0) / 1000 - time.time()
-        if remaining > _REFRESH_THRESHOLD:
-            return creds["access_token"]
-        if creds.get("refresh_token"):
-            new_token = _refresh_token(creds["refresh_token"])
-            if new_token:
-                return new_token
-    return os.environ.get("COZELOOP_API_TOKEN")
+        return _token_from_credentials()
+    if env_token and not env_coze_token:
+        token = _token_from_credentials()
+        if token:
+            return token
+        return env_token
+    if env_token:
+        return env_token
+    if env_coze_token:
+        return env_coze_token
+    return _token_from_credentials()
 # -------------------------------------------------------------------------
 
 # --- SDK Import ---
-try:
+# 最低版本：set_finish_time 是 cozeloop SDK 0.1.25 才引入的方法，云端预装旧版（<=0.1.24）
+# 调用会抛 AttributeError 并使整条 trace 上报失败。统一用能力探测（hasattr）判定，与
+# _set_finish_time_safe 兜底口径一致，避免版本号字符串比较的边界问题。
+_MIN_COZELOOP_SPEC = "cozeloop>=0.1.28"
+
+
+def _cozeloop_capable():
+    """已装 cozeloop 是否具备 set_finish_time 能力。未装/异常返回 None（无法判定）。"""
+    try:
+        import cozeloop  # noqa: F401
+    except ImportError:
+        return None
+    try:
+        return hasattr(cozeloop.Span, "set_finish_time")
+    except Exception:
+        return False
+
+
+def _ensure_cozeloop_sdk():
+    """确保 cozeloop 可 import 且尽量满足 set_finish_time 能力。
+
+    返回 True 表示 cozeloop 可 import（不保证版本达标——能力不足时由
+    _set_finish_time_safe 兜底，不阻断上报）；返回 False 表示完全无法 import。
+    """
+    capable = _cozeloop_capable()
+    if capable is True:
+        return True
+    # 已装但能力不足（capable is False）→ 需升级；未装（None）→ 需安装。
+    import subprocess
+    import importlib
+    import site
+    # 能力不足时强制升级到带下限的版本；未装时直接装下限版本。
+    pkg = _MIN_COZELOOP_SPEC
+    base_flags = ["--quiet", "--disable-pip-version-check", "--upgrade"]
+    attempts = (
+        [*base_flags, pkg],
+        [*base_flags, "--break-system-packages", pkg],
+        [*base_flags, "--break-system-packages", "--user", pkg],
+    )
+    for extra in attempts:
+        try:
+            subprocess.run(
+                [sys.executable, "-m", "pip", "install", *extra],
+                timeout=180, check=True,
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            )
+        except Exception:
+            continue
+        try:
+            importlib.reload(site)
+            user_site = site.getusersitepackages()
+            for p in ([user_site] if isinstance(user_site, str) else list(user_site)):
+                if p and p not in sys.path:
+                    sys.path.insert(0, p)
+            importlib.invalidate_caches()
+            import cozeloop  # noqa: F401
+            print("[CozeLoop] cozeloop SDK installed/upgraded at runtime.", file=sys.stderr)
+            return True
+        except ImportError:
+            continue
+    # 升级没成功，但只要原本能 import（capable is False）就继续——兜底会处理能力缺失。
+    return capable is False
+
+
+if _ensure_cozeloop_sdk():
     import cozeloop
     from cozeloop.spec.tracespec import (
         Runtime, ModelInput, ModelMessage, ModelToolChoice,
         ModelOutput, ModelChoice, ModelToolCall, ModelToolCallFunction,
         ModelMessagePart, ModelMessagePartType
     )
-except ImportError:
-    print("Error: cozeloop SDK not found. Please install it with: pip install cozeloop", file=sys.stderr)
+else:
+    print("Error: cozeloop SDK not found and auto-install failed. Try: pip install cozeloop", file=sys.stderr)
     sys.exit(1)
 
 # --- Configuration ---
 DEBUG = os.environ.get("CC_COZELOOP_DEBUG", "").lower() == "true"
 
 
+def _log_file_path() -> str:
+    return os.environ.get("COZELOOP_HOOK_LOG", "").strip()
+
+
+def hook_log(message: str):
+    """Append one diagnostic line to the hook log, if configured."""
+    log_path = _log_file_path()
+    if not log_path:
+        return
+    try:
+        p = Path(log_path).expanduser()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        with p.open("a", encoding="utf-8") as f:
+            f.write(f"{datetime.now().isoformat()} {message}\n")
+    except Exception:
+        pass
+
+
 def debug_log(message: str):
     """Print debug message if debug mode is enabled."""
+    hook_log(f"DEBUG {message}")
     if DEBUG:
         print(f"[COZELOOP_HOOK_DEBUG] {datetime.now().isoformat()} - {message}", file=sys.stderr)
 
@@ -1497,6 +1783,101 @@ def read_rollout_messages(transcript_path: str, start_line: int = 0) -> List[Dic
     return entries
 
 
+def _add_unique_path(paths: List[Path], p: Optional[Path]):
+    if not p:
+        return
+    try:
+        resolved = p.expanduser().resolve()
+    except Exception:
+        return
+    if resolved not in paths:
+        paths.append(resolved)
+
+
+def _candidate_codex_homes() -> List[Path]:
+    homes: List[Path] = []
+    _add_unique_path(homes, Path(os.environ["CODEX_HOME"]) if os.environ.get("CODEX_HOME") else None)
+
+    log_path = _log_file_path()
+    if log_path:
+        try:
+            log_parent = Path(log_path).expanduser().resolve().parent
+            if log_parent.name == "hooks":
+                _add_unique_path(homes, log_parent.parent)
+        except Exception:
+            pass
+
+    _add_unique_path(homes, Path.home() / ".codex")
+
+    agents_root = Path.home() / ".coze" / "agents"
+    try:
+        if agents_root.exists():
+            for child in agents_root.iterdir():
+                _add_unique_path(homes, child / "codex-home")
+    except Exception:
+        pass
+
+    return homes
+
+
+def _latest_file(paths: List[Path]) -> Optional[Path]:
+    existing = []
+    for p in paths:
+        try:
+            if p.is_file():
+                existing.append(p)
+        except Exception:
+            pass
+    if not existing:
+        return None
+    return max(existing, key=lambda p: p.stat().st_mtime)
+
+
+def find_latest_transcript() -> Optional[str]:
+    """Best-effort fallback when Codex does not pass hook stdin."""
+    candidates: List[Path] = []
+    for codex_home in _candidate_codex_homes():
+        sessions_dir = codex_home / "sessions"
+        if not sessions_dir.exists():
+            continue
+        try:
+            candidates.extend(sessions_dir.rglob("rollout-*.jsonl"))
+        except Exception as e:
+            hook_log(f"fallback scan failed dir={sessions_dir} error={repr(e)}")
+
+    latest = _latest_file(candidates)
+    if latest:
+        return str(latest)
+
+    for codex_home in _candidate_codex_homes():
+        sessions_dir = codex_home / "sessions"
+        if not sessions_dir.exists():
+            continue
+        try:
+            candidates.extend(sessions_dir.rglob("*.jsonl"))
+        except Exception:
+            pass
+
+    latest = _latest_file(candidates)
+    return str(latest) if latest else None
+
+
+def recover_hook_input(reason: str) -> Optional[Dict[str, Any]]:
+    transcript_path = find_latest_transcript()
+    if not transcript_path:
+        hook_log(f"fallback failed reason={reason} no transcript found")
+        print(f"[CozeLoop] Hook input missing ({reason}); no Codex transcript found.", file=sys.stderr)
+        return None
+    hook_log(f"fallback transcript reason={reason} path={transcript_path}")
+    print(f"[CozeLoop] Hook input missing ({reason}); fallback transcript: {transcript_path}", file=sys.stderr)
+    return {
+        "hook_event_name": "Stop",
+        "session_id": "",
+        "transcript_path": transcript_path,
+        "input_fallback": reason,
+    }
+
+
 def parse_session_meta(entries: List[Dict[str, Any]]) -> Dict[str, Any]:
     """Extract session identity from session_meta entry."""
     result = {
@@ -1552,6 +1933,8 @@ def is_real_user_message(payload: Dict[str, Any]) -> bool:
         if item.get("type") != "input_text":
             continue
         text = item.get("text", "")
+        if parse_coze_context(text):
+            return True
         if text.startswith("<environment_context>"):
             continue
         if text.startswith("<permissions instructions>"):
@@ -1570,11 +1953,12 @@ def extract_user_text(payload: Dict[str, Any]) -> str:
     for item in payload.get("content", []):
         if isinstance(item, dict) and item.get("type") == "input_text":
             text = item.get("text", "")
-            if (not text.startswith("<environment_context>") and
+            if (parse_coze_context(text) or
+                    (not text.startswith("<environment_context>") and
                     not text.startswith("<permissions instructions>") and
-                    not text.startswith("<turn_aborted>")):
+                    not text.startswith("<turn_aborted>"))):
                 parts.append(text)
-    return "\\n".join(parts)
+    return "\n".join(parts)
 
 
 def extract_assistant_text(payload: Dict[str, Any]) -> str:
@@ -1583,7 +1967,7 @@ def extract_assistant_text(payload: Dict[str, Any]) -> str:
     for item in payload.get("content", []):
         if isinstance(item, dict) and item.get("type") in ("output_text", "text"):
             parts.append(item.get("text", ""))
-    return "\\n".join(parts)
+    return "\n".join(parts)
 
 
 def extract_message_content_text(payload: Dict[str, Any]) -> str:
@@ -1595,7 +1979,7 @@ def extract_message_content_text(payload: Dict[str, Any]) -> str:
         text = item.get("text", "")
         if text:
             parts.append(text)
-    return "\\n".join(parts)
+    return "\n".join(parts)
 
 
 def truncate_text(text: str, limit: int = 12000) -> str:
@@ -1607,6 +1991,93 @@ def truncate_text(text: str, limit: int = 12000) -> str:
 
 # --- Message Grouping ---
 
+def _parse_ts(obj):
+    """从 codex entry/payload 的 timestamp 解析 datetime（带时区）。失败返回 None。
+
+    Codex rollout JSONL 每条 entry 顶层带 ISO8601 timestamp。建 span 时用它做
+    start_time，避免回放时所有 span 挤在几毫秒内。
+    """
+    if not isinstance(obj, dict):
+        return None
+    ts = obj.get("timestamp") or obj.get("_ts")
+    if not ts or not isinstance(ts, str):
+        return None
+    try:
+        return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except Exception:
+        return None
+
+
+def _ts_ms(dt):
+    """datetime → 毫秒时间戳（int）；None → None。"""
+    return int(dt.timestamp() * 1000) if dt is not None else None
+
+
+def _set_finish_time_safe(span, dt):
+    """安全设置 span 结束时间。
+
+    set_finish_time 是 cozeloop SDK 0.1.25+ 的方法，云端旧版没有；缺失或异常都不能
+    让整条 trace 上报失败（real_*_ms tag 仍保留耗时信息）。
+    """
+    if dt is None:
+        return
+    fn = getattr(span, "set_finish_time", None)
+    if fn is None:
+        return
+    try:
+        fn(dt)
+    except Exception:
+        pass
+
+
+def _max_dt(*values):
+    result = None
+    for value in values:
+        if value is not None and (result is None or value > result):
+            result = value
+    return result
+
+
+def _parse_ts_value(value):
+    return _parse_ts({"_ts": value}) if value else None
+
+
+def _turn_timestamps(turn):
+    values = []
+    for item in [turn.get("user_message"), *turn.get("assistant_messages", [])]:
+        dt = _parse_ts(item)
+        if dt:
+            values.append(dt)
+    for item in [*turn.get("tool_calls", []), *turn.get("tool_results", [])]:
+        dt = _parse_ts(item)
+        if dt:
+            values.append(dt)
+    for sc in turn.get("subagent_calls", []):
+        for key in ("_start_ts", "_end_ts"):
+            dt = _parse_ts_value(sc.get(key))
+            if dt:
+                values.append(dt)
+    return values
+
+
+def _turn_bounds(turn):
+    values = _turn_timestamps(turn)
+    if not values:
+        return None, None
+    return min(values), max(values)
+
+
+def _assistant_bounds(turn):
+    values = []
+    for item in turn.get("assistant_messages", []):
+        dt = _parse_ts(item)
+        if dt:
+            values.append(dt)
+    if not values:
+        return None, None
+    return min(values), max(values)
+
+
 def group_messages_into_turns(entries: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     """Group raw JSONL entries into conversation turns.
 
@@ -1629,6 +2100,9 @@ def group_messages_into_turns(entries: List[Dict[str, Any]]) -> List[Dict[str, A
     for entry in entries:
         entry_type = entry.get("type")
         payload = entry.get("payload", {})
+        # 把 entry 顶层 timestamp 注入 payload，供后续建 span 取真实时间
+        if isinstance(payload, dict) and entry.get("timestamp") and "_ts" not in payload:
+            payload["_ts"] = entry.get("timestamp")
 
         # --- Turn lifecycle events ---
         if entry_type == "event_msg":
@@ -1713,6 +2187,8 @@ def group_messages_into_turns(entries: List[Dict[str, Any]]) -> List[Dict[str, A
                         "message": args.get("message", ""),
                         "model": args.get("model"),
                         "result": None,
+                        "_start_ts": payload.get("_ts"),
+                        "_end_ts": None,
                     }
                     current_turn["subagent_calls"].append(subagent_call)
                     pending_calls[call_id] = {"kind": "spawn", "subagent_call": subagent_call}
@@ -1720,14 +2196,16 @@ def group_messages_into_turns(entries: List[Dict[str, Any]]) -> List[Dict[str, A
                     pending_calls[call_id] = {
                         "kind": "wait",
                         "ids": args.get("ids", []),
+                        "_start_ts": payload.get("_ts"),
                     }
                 else:
                     current_turn["tool_calls"].append({
                         "call_id": call_id,
                         "name": name,
                         "input": args,
+                        "_ts": payload.get("_ts"),
                     })
-                    pending_calls[call_id] = {"kind": "tool"}
+                    pending_calls[call_id] = {"kind": "tool", "_start_ts": payload.get("_ts")}
 
             elif item_type == "function_call_output":
                 if current_turn is None:
@@ -1747,6 +2225,7 @@ def group_messages_into_turns(entries: List[Dict[str, Any]]) -> List[Dict[str, A
                             subagent_call["nickname"] = out.get("nickname")
                         except (json.JSONDecodeError, TypeError, AttributeError):
                             pass
+                        subagent_call["_end_ts"] = payload.get("_ts")
 
                 elif kind == "wait":
                     try:
@@ -1759,6 +2238,7 @@ def group_messages_into_turns(entries: List[Dict[str, Any]]) -> List[Dict[str, A
                             for sc in current_turn["subagent_calls"]:
                                 if sc.get("agent_id") == agent_id and sc.get("result") is None:
                                     sc["result"] = result_text
+                                    sc["_end_ts"] = payload.get("_ts")
                                     break
                     except (json.JSONDecodeError, TypeError, AttributeError):
                         pass
@@ -1767,6 +2247,7 @@ def group_messages_into_turns(entries: List[Dict[str, Any]]) -> List[Dict[str, A
                     current_turn["tool_results"].append({
                         "call_id": call_id,
                         "output": raw_output,
+                        "_ts": payload.get("_ts"),
                     })
 
     if current_turn is not None:
@@ -1818,20 +2299,71 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
     token = get_fresh_token()
     if token:
         os.environ["COZELOOP_API_TOKEN"] = token
-    client = cozeloop.new_client()
+        hook_log(f"token resolved prefix={token[:12]}...")
+        print(f"[CozeLoop] Token 获取成功 ({token[:12]}...)", file=sys.stderr)
+    else:
+        hook_log(
+            "token missing "
+            f"has_cozeloop_token={bool(os.environ.get('COZELOOP_API_TOKEN'))} "
+            f"has_coze_token={bool(os.environ.get('COZE_API_TOKEN'))} "
+            f"api_base_url={bool(get_api_base_url())}"
+        )
+        print("[CozeLoop] 警告: 未找到有效 Token，上报可能失败", file=sys.stderr)
+    creds = _load_credentials()
+    workspace_id = (creds or {}).get("workspace_id") or os.environ.get("COZELOOP_WORKSPACE_ID", "") or _DEFAULT_WORKSPACE_ID
+    os.environ["COZELOOP_WORKSPACE_ID"] = workspace_id
+    hook_log(f"workspace_id={workspace_id}")
+    upload_events: List[str] = []
+    client_kwargs = {
+        "ultra_large_report": True,
+        "upload_timeout": 120,
+        "trace_finish_event_processor": _make_finish_event_processor(upload_events),
+    }
+    api_base_url = get_api_base_url()
+    if api_base_url:
+        client_kwargs["api_base_url"] = api_base_url
+        hook_log(f"api_base_url={api_base_url}")
+    if workspace_id:
+        client_kwargs["workspace_id"] = workspace_id
+    if token:
+        client_kwargs["api_token"] = token
+    client = cozeloop.new_client(**client_kwargs)
     ctx: List[Dict[str, Any]] = list(history_context) if history_context else []
 
     try:
-        with client.start_span(name="codex_request", span_type="main") as root_span:
+        # 整体时间范围：所有 user/assistant payload 的真实 timestamp 极值
+        _all_ts = []
+        for _t in turns:
+            _all_ts.extend(_turn_timestamps(_t))
+        root_start_dt = min(_all_ts) if _all_ts else None
+        root_end_dt = max(_all_ts) if _all_ts else None
+
+        with client.start_span(name="codex_request", span_type="main", start_time=root_start_dt) as root_span:
             root_span.set_runtime(Runtime(library="codex-cli"))
-            root_span.set_tags({
+            root_tags = {
                 "thread_id": session_id,
                 "total_turns": len(turns),
                 "source": "codex_cli",
-            })
-            root_span.set_baggage({
+            }
+            if root_start_dt is not None and root_end_dt is not None:
+                _set_finish_time_safe(root_span, root_end_dt)
+                root_tags["real_start_ms"] = _ts_ms(root_start_dt)
+                root_tags["real_end_ms"] = _ts_ms(root_end_dt)
+                root_tags["latency_ms"] = _ts_ms(root_end_dt) - _ts_ms(root_start_dt)
+            root_baggage = {
                 "thread_id": session_id,
-            })
+            }
+            # Inject coze-context kv (last occurrence across turns wins).
+            coze_tags = {}
+            for turn in turns:
+                t = {f"coze_{k}": v for k, v in turn_coze_context(turn).items()}
+                if t:
+                    coze_tags = t
+            if coze_tags:
+                root_tags.update(coze_tags)
+                root_baggage.update(coze_tags)
+            root_span.set_tags(root_tags)
+            root_span.set_baggage(root_baggage)
 
             # Set root span input: all user messages
             root_input_parts = []
@@ -1840,7 +2372,7 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                 if text:
                     root_input_parts.append(text)
             if root_input_parts:
-                root_span.set_input(truncate_text("\\n\\n".join(root_input_parts)))
+                root_span.set_input(truncate_text("\n\n".join(root_input_parts)))
 
             # Set root span output: all assistant messages
             root_output_parts = []
@@ -1850,25 +2382,47 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                     if assistant_text:
                         root_output_parts.append(assistant_text)
             if root_output_parts:
-                root_span.set_output(truncate_text("\\n\\n".join(root_output_parts)))
+                root_span.set_output(truncate_text("\n\n".join(root_output_parts)))
 
             # Process each turn
             for i, turn in enumerate(turns):
                 try:
-                    with client.start_span(name=f"turn_{i}", span_type="main") as turn_span:
+                    # turn 真实时间：start=user payload 时间；end=最后一条 assistant payload 时间
+                    turn_start_dt, turn_end_dt = _turn_bounds(turn)
+
+                    with client.start_span(name=f"turn_{i}", span_type="main", start_time=turn_start_dt) as turn_span:
                         turn_span.set_runtime(Runtime(library="codex-cli"))
-                        turn_span.set_tags({
+                        _turn_tags = {
                             "thread_id": session_id,
                             "turn_index": i,
                             "turn_id": turn.get("turn_id", ""),
                             "source": "codex_cli",
-                        })
+                        }
+                        if turn_start_dt is not None and turn_end_dt is not None:
+                            _set_finish_time_safe(turn_span, turn_end_dt)
+                            _turn_tags["real_start_ms"] = _ts_ms(turn_start_dt)
+                            _turn_tags["real_end_ms"] = _ts_ms(turn_end_dt)
+                            _turn_tags["latency_ms"] = _ts_ms(turn_end_dt) - _ts_ms(turn_start_dt)
+                        turn_span.set_tags(_turn_tags)
 
                         # --- Model span for assistant response ---
                         if turn.get("assistant_messages"):
-                            with client.start_span(name="assistant_response", span_type="model") as model_span:
+                            # model span start：第一条 assistant payload 时间，回退到 turn 起点
+                            _model_start_dt, _model_end_dt = _assistant_bounds(turn)
+                            if _model_start_dt is None:
+                                _model_start_dt = turn_start_dt
+                            if _model_end_dt is None:
+                                _model_end_dt = turn_end_dt
+                            with client.start_span(name="assistant_response", span_type="model", start_time=_model_start_dt) as model_span:
                                 model_span.set_runtime(Runtime(library="codex-cli"))
                                 model_span.set_model_name(model_name)
+                                if _model_start_dt is not None and _model_end_dt is not None:
+                                    _set_finish_time_safe(model_span, _model_end_dt)
+                                    model_span.set_tags({
+                                        "real_start_ms": _ts_ms(_model_start_dt),
+                                        "real_end_ms": _ts_ms(_model_end_dt),
+                                        "latency_ms": _ts_ms(_model_end_dt) - _ts_ms(_model_start_dt),
+                                    })
 
                                 # Build input messages: history + current turn input
                                 turn_input = turn.get("input_messages", [])
@@ -1936,17 +2490,30 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                         # --- Tool call spans ---
                         for tool_call in turn.get("tool_calls", []):
                             tool_name = tool_call.get("name", "unknown")
-                            with client.start_span(name=f"tool_{tool_name}", span_type="tool") as tool_span:
+                            tool_start_dt = _parse_ts(tool_call) or turn_start_dt
+                            tool_end_dt = None
+                            call_id = tool_call.get("call_id")
+                            for result in turn.get("tool_results", []):
+                                if result.get("call_id") == call_id:
+                                    tool_end_dt = _parse_ts(result)
+                                    break
+                            tool_finish_dt = _max_dt(tool_end_dt, tool_start_dt)
+                            with client.start_span(name=f"tool_{tool_name}", span_type="tool", start_time=tool_start_dt) as tool_span:
                                 tool_span.set_runtime(Runtime(library="codex-cli"))
-                                tool_span.set_tags({
+                                tool_tags = {
                                     "tool_name": tool_name,
-                                    "call_id": tool_call.get("call_id"),
-                                })
+                                    "call_id": call_id,
+                                }
+                                if tool_start_dt is not None and tool_finish_dt is not None:
+                                    _set_finish_time_safe(tool_span, tool_finish_dt)
+                                    tool_tags["real_start_ms"] = _ts_ms(tool_start_dt)
+                                    tool_tags["real_end_ms"] = _ts_ms(tool_finish_dt)
+                                    tool_tags["latency_ms"] = _ts_ms(tool_finish_dt) - _ts_ms(tool_start_dt)
+                                tool_span.set_tags(tool_tags)
                                 tool_span.set_input(
                                     json.dumps(tool_call.get("input", {}), ensure_ascii=False)[:2000]
                                 )
                                 # Find matching tool result
-                                call_id = tool_call.get("call_id")
                                 for result in turn.get("tool_results", []):
                                     if result.get("call_id") == call_id:
                                         output = result.get("output", "")
@@ -1959,15 +2526,24 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                         for sc in turn.get("subagent_calls", []):
                             agent_id = sc.get("agent_id") or "unknown"
                             nickname = sc.get("nickname") or agent_id
+                            subagent_start_dt = _parse_ts_value(sc.get("_start_ts")) or turn_start_dt
+                            subagent_end_dt = _parse_ts_value(sc.get("_end_ts")) or turn_end_dt
+                            subagent_finish_dt = _max_dt(subagent_end_dt, subagent_start_dt)
 
-                            with client.start_span(name=f"subagent_{nickname}", span_type="agent") as subagent_span:
+                            with client.start_span(name=f"subagent_{nickname}", span_type="agent", start_time=subagent_start_dt) as subagent_span:
                                 subagent_span.set_runtime(Runtime(library="codex-cli"))
-                                subagent_span.set_tags({
+                                subagent_tags = {
                                     "agent_id": agent_id,
                                     "agent_nickname": nickname,
                                     "agent_role": sc.get("role") or "",
                                     "agent_model": sc.get("model") or "",
-                                })
+                                }
+                                if subagent_start_dt is not None and subagent_finish_dt is not None:
+                                    _set_finish_time_safe(subagent_span, subagent_finish_dt)
+                                    subagent_tags["real_start_ms"] = _ts_ms(subagent_start_dt)
+                                    subagent_tags["real_end_ms"] = _ts_ms(subagent_finish_dt)
+                                    subagent_tags["latency_ms"] = _ts_ms(subagent_finish_dt) - _ts_ms(subagent_start_dt)
+                                subagent_span.set_tags(subagent_tags)
                                 subagent_span.set_input(sc.get("message", "")[:2000])
 
                                 # Load and include saved subagent turn data
@@ -1977,20 +2553,45 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                                     sa_model = sa_data.get("model_name", "codex")
 
                                     for si, sa_turn in enumerate(sa_turns):
-                                        with client.start_span(name=f"turn_{si}", span_type="main") as sa_turn_span:
+                                        sa_turn_start_dt, sa_turn_end_dt = _turn_bounds(sa_turn)
+                                        if sa_turn_start_dt is None:
+                                            sa_turn_start_dt = subagent_start_dt
+                                        if sa_turn_end_dt is None:
+                                            sa_turn_end_dt = sa_turn_start_dt
+                                        sa_turn_finish_dt = _max_dt(sa_turn_end_dt, sa_turn_start_dt)
+
+                                        with client.start_span(name=f"turn_{si}", span_type="main", start_time=sa_turn_start_dt) as sa_turn_span:
                                             sa_turn_span.set_runtime(Runtime(library="codex-cli"))
-                                            sa_turn_span.set_tags({
+                                            sa_turn_tags = {
                                                 "turn_index": si,
                                                 "turn_id": sa_turn.get("turn_id", ""),
                                                 "agent_name": nickname,
-                                            })
+                                            }
+                                            if sa_turn_start_dt is not None and sa_turn_finish_dt is not None:
+                                                _set_finish_time_safe(sa_turn_span, sa_turn_finish_dt)
+                                                sa_turn_tags["real_start_ms"] = _ts_ms(sa_turn_start_dt)
+                                                sa_turn_tags["real_end_ms"] = _ts_ms(sa_turn_finish_dt)
+                                                sa_turn_tags["latency_ms"] = _ts_ms(sa_turn_finish_dt) - _ts_ms(sa_turn_start_dt)
+                                            sa_turn_span.set_tags(sa_turn_tags)
 
                                             # Subagent model span
                                             if sa_turn.get("assistant_messages"):
-                                                with client.start_span(name="assistant_response", span_type="model") as sa_model_span:
+                                                sa_model_start_dt, sa_model_end_dt = _assistant_bounds(sa_turn)
+                                                if sa_model_start_dt is None:
+                                                    sa_model_start_dt = sa_turn_start_dt
+                                                if sa_model_end_dt is None:
+                                                    sa_model_end_dt = sa_turn_end_dt
+                                                sa_model_finish_dt = _max_dt(sa_model_end_dt, sa_model_start_dt)
+                                                with client.start_span(name="assistant_response", span_type="model", start_time=sa_model_start_dt) as sa_model_span:
                                                     sa_model_span.set_runtime(Runtime(library="codex-cli"))
                                                     sa_model_span.set_model_name(sa_model)
-                                                    sa_model_span.set_tags({"agent_name": nickname})
+                                                    sa_model_tags = {"agent_name": nickname}
+                                                    if sa_model_start_dt is not None and sa_model_finish_dt is not None:
+                                                        _set_finish_time_safe(sa_model_span, sa_model_finish_dt)
+                                                        sa_model_tags["real_start_ms"] = _ts_ms(sa_model_start_dt)
+                                                        sa_model_tags["real_end_ms"] = _ts_ms(sa_model_finish_dt)
+                                                        sa_model_tags["latency_ms"] = _ts_ms(sa_model_finish_dt) - _ts_ms(sa_model_start_dt)
+                                                    sa_model_span.set_tags(sa_model_tags)
 
                                                     sa_input = sa_turn.get("input_messages", [])
                                                     if not sa_input:
@@ -2034,17 +2635,30 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                                             # Subagent tool spans
                                             for sa_tc in sa_turn.get("tool_calls", []):
                                                 sa_tool_name = sa_tc.get("name", "unknown")
-                                                with client.start_span(name=f"tool_{sa_tool_name}", span_type="tool") as sa_tool_span:
+                                                sa_tool_start_dt = _parse_ts(sa_tc) or sa_turn_start_dt
+                                                sa_tool_end_dt = None
+                                                sa_cid = sa_tc.get("call_id")
+                                                for sa_r in sa_turn.get("tool_results", []):
+                                                    if sa_r.get("call_id") == sa_cid:
+                                                        sa_tool_end_dt = _parse_ts(sa_r)
+                                                        break
+                                                sa_tool_finish_dt = _max_dt(sa_tool_end_dt, sa_tool_start_dt)
+                                                with client.start_span(name=f"tool_{sa_tool_name}", span_type="tool", start_time=sa_tool_start_dt) as sa_tool_span:
                                                     sa_tool_span.set_runtime(Runtime(library="codex-cli"))
-                                                    sa_tool_span.set_tags({
+                                                    sa_tool_tags = {
                                                         "tool_name": sa_tool_name,
-                                                        "call_id": sa_tc.get("call_id"),
+                                                        "call_id": sa_cid,
                                                         "agent_name": nickname,
-                                                    })
+                                                    }
+                                                    if sa_tool_start_dt is not None and sa_tool_finish_dt is not None:
+                                                        _set_finish_time_safe(sa_tool_span, sa_tool_finish_dt)
+                                                        sa_tool_tags["real_start_ms"] = _ts_ms(sa_tool_start_dt)
+                                                        sa_tool_tags["real_end_ms"] = _ts_ms(sa_tool_finish_dt)
+                                                        sa_tool_tags["latency_ms"] = _ts_ms(sa_tool_finish_dt) - _ts_ms(sa_tool_start_dt)
+                                                    sa_tool_span.set_tags(sa_tool_tags)
                                                     sa_tool_span.set_input(
                                                         json.dumps(sa_tc.get("input", {}), ensure_ascii=False)[:2000]
                                                     )
-                                                    sa_cid = sa_tc.get("call_id")
                                                     for sa_r in sa_turn.get("tool_results", []):
                                                         if sa_r.get("call_id") == sa_cid:
                                                             sa_out = sa_r.get("output", "")
@@ -2074,15 +2688,22 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                     debug_log(f"Error processing turn {i}: {e}")
                     continue
 
+        hook_log(f"processed turns={len(turns)} session_id={session_id}")
         debug_log(f"Successfully processed {len(turns)} turn(s) for session {session_id}")
 
     except Exception as e:
+        hook_log(f"send exception={repr(e)}")
         debug_log(f"An error occurred while sending traces to CozeLoop: {e}")
         return None
     finally:
         client.close()
+        hook_log("client closed")
         debug_log("CozeLoop client closed.")
 
+    if upload_events:
+        hook_log(f"upload failed state not advanced failures={len(upload_events)} detail={upload_events[-1][:500]}")
+        return None
+
     return ctx
 
 
@@ -2090,10 +2711,13 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
 
 def main():
     """Main entry point for the Codex CozeLoop hook."""
+    print("[CozeLoop] Hook triggered (Codex).", file=sys.stderr)
+    hook_log("hook triggered")
     debug_log("Codex CozeLoop hook started.")
 
     # Check if tracing is enabled
     if os.environ.get("TRACE_TO_COZELOOP", "").lower() == "false":
+        hook_log("skip trace disabled")
         debug_log("TRACE_TO_COZELOOP is set to 'false', skipping")
         return
 
@@ -2101,24 +2725,41 @@ def main():
     try:
         raw_input = sys.stdin.read().strip()
         if not raw_input:
+            hook_log("stdin empty, trying fallback")
             debug_log("No input received from stdin")
-            return
-        hook_input = json.loads(raw_input)
+            hook_input = recover_hook_input("empty_stdin")
+            if not hook_input:
+                return
+        else:
+            hook_input = json.loads(raw_input)
     except Exception as e:
+        hook_log(f"stdin parse error={repr(e)}, trying fallback")
         debug_log(f"Error reading hook input from stdin: {e}")
-        return
+        hook_input = recover_hook_input("stdin_parse_error")
+        if not hook_input:
+            return
 
     debug_log(f"Hook input: {json.dumps(hook_input, ensure_ascii=False)}")
 
     # Get transcript path
     transcript_path = hook_input.get("transcript_path")
     if not transcript_path:
+        hook_log("missing transcript_path, trying fallback")
         debug_log("No transcript_path in hook input")
-        return
+        recovered = recover_hook_input("missing_transcript_path")
+        if not recovered:
+            return
+        hook_input = recovered
+        transcript_path = hook_input.get("transcript_path")
 
     if not os.path.exists(transcript_path):
+        hook_log(f"transcript not found path={transcript_path}, trying fallback")
         debug_log(f"Transcript file not found: {transcript_path}")
-        return
+        recovered = recover_hook_input("transcript_not_found")
+        if not recovered:
+            return
+        hook_input = recovered
+        transcript_path = hook_input.get("transcript_path")
 
     # Load state
     state_file = get_state_file_path(transcript_path)
@@ -2128,9 +2769,11 @@ def main():
     entries = read_rollout_messages(transcript_path, state["last_processed_line"])
 
     if not entries:
+        hook_log(f"skip no new entries transcript={transcript_path}")
         debug_log("No new entries to process")
         return
 
+    hook_log(f"read entries={len(entries)} from_line={state['last_processed_line']} transcript={transcript_path}")
     debug_log(f"Read {len(entries)} new entries from line {state['last_processed_line']}")
 
     # Parse session identity
@@ -2180,11 +2823,20 @@ def main():
         last_line = max(e.get("_line_number", 0) for e in entries) + 1
         state["last_processed_line"] = last_line
         save_state(state_file, state)
+        hook_log(f"subagent saved session_id={session_id} turns={len(turns[-1:])} last_line={last_line}")
         debug_log("Subagent data saved, hook completed")
         return
 
-    # Send turns to CozeLoop
+    # Send turns to CozeLoop — only if at least one turn carries coze-context.
     if turns:
+        has_coze_ctx = any(
+            turn_coze_context(t)
+            for t in turns
+        )
+        if not has_coze_ctx:
+            hook_log(f"skip no coze-context turns={len(turns)} session_id={session_id}")
+            debug_log("No coze-context found in any turn, skipping upload.")
+            return
         history_context = state.get("conversation_history", [])
         updated_history = send_turns_to_cozeloop(
             turns, session_id, model_name,
@@ -2195,12 +2847,16 @@ def main():
             state["last_processed_line"] = last_line
             state["conversation_history"] = updated_history
             save_state(state_file, state)
+            hook_log(f"state advanced last_line={last_line} session_id={session_id}")
             debug_log(f"State updated, last processed line: {last_line}")
         else:
+            hook_log(f"send failed state not advanced session_id={session_id}")
             debug_log("Send failed, state not advanced")
     else:
+        hook_log(f"skip no turns session_id={session_id}")
         debug_log("No turns to send")
 
+    hook_log("hook completed")
     debug_log("Codex CozeLoop hook completed.")
 
 
@@ -3514,10 +4170,12 @@ async function _refreshToken(refreshTok) {
                 try {
                     const d = JSON.parse(buf);
                     if (d.access_token) {
+                        const existing = _loadCreds() ?? {};
                         const creds = {
                             access_token: d.access_token,
                             refresh_token: d.refresh_token ?? refreshTok,
                             expires_at: (d.expires_in ?? 0) * 1000,  // unix timestamp in seconds
+                            workspace_id: existing.workspace_id ?? "",
                         };
                         _saveCreds(creds);
                         resolve(creds.access_token);
@@ -3541,7 +4199,7 @@ async function getRefreshedToken(currentAuthorization) {
         const newToken = await _refreshToken(creds.refresh_token);
         if (newToken) return \`Bearer \${newToken}\`;
     }
-    return currentAuthorization; // fallback
+    return null;
 }
 // ─────────────────────────────────────────────────────────────────────────
 
@@ -3613,6 +4271,9 @@ export class CozeloopExporter {
                 this.provider = null;
                 this.tracer = null;
             }
+        } else if (fresh === null) {
+            this.api.logger.error("[CozeloopTrace] Local credentials exist but token refresh failed; refusing to reuse stale authorization.");
+            this.config.authorization = "";
         }
     }
     async ensureInitialized() {
@@ -4126,13 +4787,19 @@ def refresh(rt):
     try:
         body = json.dumps({"grant_type":"refresh_token","client_id":CLIENT_ID,"refresh_token":rt}).encode()
         req = urllib.request.Request(f"{COZE_API}/api/permission/oauth2/token",
-            data=body, headers={"Content-Type":"application/json"})
+            data=body, headers={
+                "Content-Type":"application/json",
+                "x-tt-env":"ppe_cozelab",
+                "x-use-ppe":"1",
+            })
         with urllib.request.urlopen(req, timeout=10) as r:
             d = json.loads(r.read())
         if d.get("access_token"):
+            existing = load() or {}
             save({"access_token":d["access_token"],
                   "refresh_token":d.get("refresh_token",rt),
-                  "expires_at":d.get("expires_in",0)*1000})
+                  "expires_at":d.get("expires_in",0)*1000,
+                  "workspace_id":existing.get("workspace_id","")})
             return True
     except Exception as e:
         print(f"[cozeloop_refresh] refresh failed: {e}", file=sys.stderr)
@@ -4164,6 +4831,7 @@ function parseArgs() {
     if (arg === '--refresh') { args['refresh'] = true; continue; }
     if (arg === '--verify')  { args['verify']  = true; continue; }
     if (arg === '--cloud')   { args['cloud']   = true; continue; }
+    if (arg === '--force')   { args['force']   = true; continue; }
     const m = arg.match(/^--([^=]+)=(.+)$/);
     if (m) args[m[1]] = m[2];
   }
@@ -4225,6 +4893,7 @@ function validateArgs(args) {
         'codex-home': args['codex-home'],
         pairCode: args['pair-code'],
         cloud: true,
+        force: !!args['force'],
       };
     }
     // config.json 缺失：回退到显式 --agent
@@ -4243,6 +4912,7 @@ function validateArgs(args) {
       'codex-home': args['codex-home'],
       pairCode: args['pair-code'],
       cloud: true,
+      force: !!args['force'],
     };
   }
 
@@ -4257,6 +4927,7 @@ function validateArgs(args) {
       'codex-home': args['codex-home'],
       pairCode: args['pair-code'],
       cloud: !!args['cloud'],
+      force: !!args['force'],
     };
   }
 
@@ -4268,6 +4939,9 @@ function validateArgs(args) {
       '  --agent=claude-code | codex | openclaw   (全局配置)',
       '  --agent-id=<id>                          (按 ~/.coze/agents/<id> 的 framework 自动路由)',
       '',
+      'Flags:',
+      '  --force    强制重装（OpenClaw 跳过幂等检查，无条件重写插件 + 重装依赖 + 重启 gateway）',
+      '',
       'Other commands:',
       '  --status   Show authorization status',
       '  --login    Login (Device Code flow)',
@@ -4287,7 +4961,7 @@ function validateArgs(args) {
       '  --agent=openclaw',
     ]);
   }
-  return { agent: args['agent'], 'codex-home': args['codex-home'], pairCode: args['pair-code'], cloud: !!args['cloud'] };
+  return { agent: args['agent'], 'codex-home': args['codex-home'], pairCode: args['pair-code'], cloud: !!args['cloud'], force: !!args['force'] };
 }
 
 // ─── 4. Agent detection ──────────────────────────────────────────────────────
@@ -4378,28 +5052,34 @@ function checkPython() {
   return pythonCmd;
 }
 
-// Verify the `cozeloop` Python SDK is importable; auto-install if missing.
-// Claude Code / Codex hooks `import cozeloop` at runtime — without it the
-// first Stop hook fails with "cozeloop SDK not found" long after onboarding.
+// Verify the `cozeloop` Python SDK is importable AND new enough; install/upgrade otherwise.
+// Claude Code / Codex hooks `import cozeloop` at runtime and call set_finish_time（0.1.25+）。
+// 旧版（<=0.1.24）能 import 但缺该方法，会让 hook 上报整条 trace 失败，所以这里用能力探测
+// （hasattr set_finish_time）而非单纯 import，并在不达标时升级到带下限的版本。
+// 注意：这是安装阶段的 python，可能不是跑 hook 的那个 python（已知坑），所以它只是双保险——
+// 真正的运行时拦截在 hook 脚本的 _ensure_cozeloop_sdk 里。
+const COZELOOP_MIN_SPEC = 'cozeloop>=0.1.28';
+// 探测脚本：import 成功且具备 set_finish_time 能力 → exit 0；否则非 0。
+const COZELOOP_CAPABLE_PROBE = `import cozeloop,sys; sys.exit(0 if hasattr(cozeloop.Span,'set_finish_time') else 3)`;
 function checkCozeloopSdk(pythonCmd) {
   try {
-    execSync(`${pythonCmd} -c "import cozeloop"`, { stdio: 'pipe' });
+    execSync(`${pythonCmd} -c "${COZELOOP_CAPABLE_PROBE}"`, { stdio: 'pipe' });
     ok('cozeloop SDK — OK');
     return;
-  } catch { /* not installed — try to install below */ }
+  } catch { /* 未装或版本过旧 — 下面安装/升级 */ }
 
-  info('cozeloop SDK 未安装，正在安装 (pip install cozeloop)...');
+  info(`cozeloop SDK 不可用或版本过旧，正在安装/升级 (pip install -U '${COZELOOP_MIN_SPEC}')...`);
   try {
-    execSync(`${pythonCmd} -m pip install --quiet --upgrade cozeloop`, { stdio: 'pipe' });
-    // Confirm it imports now
-    execSync(`${pythonCmd} -c "import cozeloop"`, { stdio: 'pipe' });
-    ok('cozeloop SDK 安装成功');
+    execSync(`${pythonCmd} -m pip install --quiet --upgrade '${COZELOOP_MIN_SPEC}'`, { stdio: 'pipe' });
+    // Confirm it imports and is capable now
+    execSync(`${pythonCmd} -c "${COZELOOP_CAPABLE_PROBE}"`, { stdio: 'pipe' });
+    ok('cozeloop SDK 安装/升级成功');
   } catch (e) {
     warnBox([
-      '⚠ WARNING: 无法自动安装 cozeloop SDK',
+      '⚠ WARNING: 无法自动安装/升级 cozeloop SDK 到所需版本',
       '',
       '请手动安装后再使用，否则 hook 触发时 trace 上报会失败：',
-      `  ${pythonCmd} -m pip install cozeloop`,
+      `  ${pythonCmd} -m pip install -U '${COZELOOP_MIN_SPEC}'`,
       '',
       (e.stderr ? e.stderr.toString().trim() : e.message),
     ]);
@@ -4544,6 +5224,7 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cl
     if (cloud) {
       const loopToken = readEnv('COZELOOP_API_TOKEN');
       const cozeToken = readEnv('COZE_API_TOKEN');
+      existing.env.COZELAB_ONBOARD_CLOUD = '1';
       if (loopToken) {
         existing.env.COZELOOP_API_TOKEN = loopToken;
         delete existing.env.COZE_API_TOKEN;
@@ -4552,8 +5233,9 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cl
         delete existing.env.COZELOOP_API_TOKEN;
       }
     } else {
-      existing.env.COZELOOP_API_TOKEN = patToken;
+      delete existing.env.COZELOOP_API_TOKEN;
       delete existing.env.COZE_API_TOKEN;
+      delete existing.env.COZELAB_ONBOARD_CLOUD;
     }
     const loopBaseUrl = readEnv('COZELOOP_API_BASE_URL');
     const otelEndpoint = readEnv('OTEL_ENDPOINT');
@@ -4582,8 +5264,8 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cl
 
 // writeCodexHook 把 hook 写进指定的 CODEX_HOME。codexHome 缺省 ~/.codex；
 // 传入动态目录（如 coze-bridge 的 /tmp/coze-bridge-codex-home-xxx）即可 per-agent 生效。
-// cloud=true 时 cozeloop.env 不写死 token —— 云端 hook 运行时直接读环境变量
-// COZE_API_TOKEN（见 scripts/codex/cozeloop_hook.py 的 get_fresh_token）。
+// 本地模式不把短期 token 写入 cozeloop.env；Hook 运行时读取 ~/.cozeloop/credentials.json。
+// cloud=true 时写 COZELAB_ONBOARD_CLOUD，并带入 sandbox 注入的 trace token。
 function writeCodexHook(token, workspaceId, pythonCmd, codexHome, cloud) {
   const home       = codexHome || path.join(os.homedir(), '.codex');
   const hooksDir   = path.join(home, 'hooks');
@@ -4606,13 +5288,12 @@ function writeCodexHook(token, workspaceId, pythonCmd, codexHome, cloud) {
   if (cloud) {
     const loopToken = readEnv('COZELOOP_API_TOKEN');
     const cozeToken = readEnv('COZE_API_TOKEN');
+    envLines.push(shellEnvLine('COZELAB_ONBOARD_CLOUD', '1'));
     if (loopToken) {
       envLines.push(shellEnvLine('COZELOOP_API_TOKEN', loopToken));
     } else if (cozeToken) {
       envLines.push(shellEnvLine('COZE_API_TOKEN', cozeToken));
     }
-  } else {
-    envLines.push(shellEnvLine('COZELOOP_API_TOKEN', token));
   }
   envLines.push(shellEnvLine('CODEX_HOME', home));
   envLines.push(shellEnvLine('COZELOOP_HOOK_LOG', logFile));
@@ -4722,7 +5403,7 @@ function normalizeCozeloopApiBaseUrl(raw) {
     return base.slice(0, -'/v1/loop/opentelemetry'.length).replace(/\/+$/, '');
   }
   if (base.endsWith('/api/v1/loop/opentelemetry')) {
-    return base.slice(0, -'/loop/opentelemetry'.length).replace(/\/+$/, '');
+    return base.slice(0, -'/v1/loop/opentelemetry'.length).replace(/\/+$/, '');
   }
   if (base.endsWith('/api/v1')) {
     return base.slice(0, -'/v1'.length).replace(/\/+$/, '');
@@ -4772,6 +5453,12 @@ function applyOpenClawPluginConfig(existing, token, workspaceId, agentId, cloud)
   pcfg.endpoint      = getOtelEndpointBase(cloud);
   pcfg.workspaceId   = workspaceId;
   pcfg.debug         = true;
+  pcfg.disableLocalCredentials = !!cloud;
+  // 插件代码版本：参与幂等比对，升级插件（bump scripts/openclaw/package.json version）后
+  // 强制触发重写+重装+重启，避免云端 pluginDir 滞留旧插件 dist。
+  if (OPENCLAW_PLUGIN_VERSION) {
+    pcfg.pluginVersion = OPENCLAW_PLUGIN_VERSION;
+  }
   // per-agent trace 放行：把当前 agentId 并入 traceAgentIds（去重、归一为小写，
   // 与插件侧 resolveAgentIdFromHookCtx 的归一一致）。无 agentId（全局模式）则不动
   // allowlist —— 空 allowlist 表示全部放行。
@@ -5132,6 +5819,117 @@ async function verifyTraceReport(token, workspaceId, pairCode, tracesUrl) {
   return { success, status: res.status, body: res.body, traceId, pairCode: pair };
 }
 
+// ── OpenClaw 专属上报链路校验 ──────────────────────────────────────────────
+// 为什么单独一条：claude-code/codex 的 verify 用主流程刚 getValidToken() 刷新过的有效
+// token 直发，而 openclaw 运行时上报用的是【写死在 openclaw.json 插件 config.authorization
+// 里的静态 token】。两者是不同 token —— 插件那个失效（401/4100）时通用 verify 照样 ok，
+// 这就是“verify=ok 但实际查不到 trace”假象的根因。本函数改为读插件实际配置的 token 打
+// ingest，真实反映运行时会不会 401。
+//
+// cloud/local 兼容：插件配置位置都在 resolveHomeDir(cloud)/.openclaw/openclaw.json，
+// endpoint 都走 getOtelEndpointBase(cloud)，逻辑统一。差异在 token 刷新：
+//   - local：disableLocalCredentials=false，插件会读 ~/.cozeloop/credentials.json 自动刷新，
+//            所以额外检测【实际加载的插件是否含刷新逻辑 getRefreshedToken】，无则告警。
+//   - cloud：disableLocalCredentials=true，插件只用写死的 token、不刷新，token 失效需重注入，
+//            刷新能力检测对 cloud 无意义（跳过）。
+async function verifyOpenClawTraceLink(cloud) {
+  const home = resolveHomeDir(cloud);
+  const configPath = path.join(home, '.openclaw', 'openclaw.json');
+  let pcfg = null;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    pcfg = cfg?.plugins?.entries?.['openclaw-cozeloop-trace']?.config || null;
+  } catch (e) {
+    warn(`无法读取 openclaw.json 插件配置: ${e.message}`);
+    return { success: false, status: 0, body: `read ${configPath} failed: ${e.message}` };
+  }
+  if (!pcfg || !pcfg.authorization) {
+    warn('openclaw 插件未配置 authorization，无法校验上报链路。');
+    return { success: false, status: 0, body: 'plugin authorization missing' };
+  }
+
+  // 1) 用插件【实际配置的】token 打 ingest（空 spans）——这才是运行时真实用的那个 token。
+  const authHeader = pcfg.authorization; // 形如 "Bearer czu_xxx"
+  const tracesUrl = (pcfg.endpoint
+    ? `${String(pcfg.endpoint).replace(/\/+$/, '')}/v1/traces`
+    : getOtelTracesUrl(cloud));
+  const workspaceId = pcfg.workspaceId || WORKSPACE_ID;
+  let res;
+  try {
+    res = await httpsPost(
+      tracesUrl,
+      { resourceSpans: [] },
+      { Authorization: authHeader, 'cozeloop-workspace-id': String(workspaceId) },
+    );
+  } catch (e) {
+    warn(`openclaw 插件 token 上报探测失败: ${e.message}`);
+    return { success: false, status: 0, body: e.message };
+  }
+  const success = res.status >= 200 && res.status < 300;
+  const tokenPrefix = authHeader.replace(/^Bearer\s+/i, '').slice(0, 12);
+
+  if (success) {
+    ok(`openclaw 插件实际 token 上报正常 (token=${tokenPrefix}..., HTTP ${res.status})`);
+  } else {
+    warn(`openclaw 插件实际 token 上报失败: HTTP ${res.status} (token=${tokenPrefix}...)`);
+    const snippet = (res.body || '').slice(0, 300);
+    if (snippet) console.log(snippet);
+    // 4100/401 = 该 token 已失效。指出根因与修复方式。
+    if (res.status === 401 || /\b4100\b/.test(res.body || '')) {
+      info('插件配置的 token 已失效。运行时上报会 401 → OTLP 抛 unhandled rejection → gateway 崩溃 → span 丢失。');
+      info('修复：重跑 `node index.js --agent=openclaw --force` 写入新 token（local 会从 ~/.cozeloop 自动刷新）。');
+    }
+  }
+
+  // 2) 仅 local：检测实际加载的插件是否具备 token 自动刷新能力。
+  //    cloud 主动 disableLocalCredentials，不刷新，检测无意义。
+  if (!cloud) {
+    const refreshOk = openClawPluginHasRefresh(home);
+    if (refreshOk === true) {
+      ok('openclaw 插件具备 token 自动刷新能力 (getRefreshedToken)。');
+    } else if (refreshOk === false) {
+      warn('本机加载的 openclaw 插件【无 token 刷新逻辑】，token 过期后会反复 401 崩 gateway。');
+      info('修复：重跑 `node index.js --agent=openclaw --force` 安装带刷新逻辑的新插件。');
+    }
+    // refreshOk === null：定位不到插件文件，不下结论（不误报）。
+  }
+
+  return { success, status: res.status, body: res.body || '' };
+}
+
+// 检测本机【实际加载的】openclaw trace 插件是否含 token 刷新逻辑（getRefreshedToken）。
+// 返回 true=有 / false=无 / null=定位不到插件文件（不下结论）。
+// 探测顺序：openclaw plugins list 给出的真实路径 > onboard 安装位置 ~/.cozeloop/openclaw-plugin
+// > 历史手改位置 ~/.openclaw/workspace/cozeloop-trace-fix。
+function openClawPluginHasRefresh(home) {
+  const candidates = [];
+  // openclaw plugins list 拿实际加载路径（最准——能发现 cozeloop-trace-fix 这类残留旧插件）
+  try {
+    const { execSync } = require('child_process');
+    const out = execSync('openclaw plugins list', { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+    for (const line of out.split(/\r?\n/)) {
+      if (!/cozeloop|trace/i.test(line)) continue;
+      const m = line.match(/(\/[^\s'"]+)/); // 抓行内绝对路径
+      if (m) candidates.push(m[1]);
+    }
+  } catch { /* CLI 不可用则回退已知路径 */ }
+  candidates.push(path.join(home, '.cozeloop', 'openclaw-plugin'));
+  candidates.push(path.join(home, '.openclaw', 'workspace', 'cozeloop-trace-fix'));
+
+  let foundAny = false;
+  for (const base of candidates) {
+    for (const rel of ['dist/cozeloop-exporter.js', 'dist/index.js', 'cozeloop-exporter.js', 'index.js']) {
+      const f = path.isAbsolute(rel) ? rel : path.join(base, rel);
+      try {
+        if (!fs.existsSync(f)) continue;
+        foundAny = true;
+        if (fs.readFileSync(f, 'utf8').includes('getRefreshedToken')) return true;
+      } catch { /* ignore */ }
+    }
+  }
+  return foundAny ? false : null;
+}
+
 function httpsGet(url, headers) {
   return new Promise((resolve, reject) => {
     // 合并 PPE 泳道 header
@@ -5463,7 +6261,22 @@ async function main() {
     const token = await getValidToken();   // 无凭证会自动走登录/刷新
     console.log('');
     const result = await verifyTraceReport(token, WORKSPACE_ID, args.pairCode, getOtelTracesUrl(false));
-    process.exit(result.success ? 0 : 1);
+    // 若本机装了 openclaw 插件，额外校验插件【实际配置的静态 token】——通用 verify 用刚刷新的
+    // token 测不到它。任一失败则整体判失败（exit 1）。
+    let ocOk = true;
+    const ocConfigPath = path.join(resolveHomeDir(false), '.openclaw', 'openclaw.json');
+    if (fs.existsSync(ocConfigPath)) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(ocConfigPath, 'utf8'));
+        if (cfg?.plugins?.entries?.['openclaw-cozeloop-trace']?.config?.authorization) {
+          console.log('');
+          info('检测到 openclaw cozeloop-trace 插件，校验其实际 token...');
+          const ocRes = await verifyOpenClawTraceLink(false);
+          ocOk = ocRes.success;
+        }
+      } catch { /* 读不了就跳过 openclaw 校验 */ }
+    }
+    process.exit(result.success && ocOk ? 0 : 1);
   }
 
   const { agent } = args;
@@ -5593,9 +6406,15 @@ async function main() {
 
   // Step 5: Verify trace reporting end-to-end
   info('Step 5/5: 验证 trace 上报链路...');
-  const verifyResult = args.cloud
-    ? await verifyTraceReportViaSdk(token, WORKSPACE_ID, args.pairCode, pythonCmd || 'python3', tokenSource)
-    : await verifyTraceReport(token, WORKSPACE_ID, args.pairCode, getOtelTracesUrl(false));
+  // openclaw 走专属校验：claude-code/codex 的 verify 用主流程刚 getValidToken() 刷新过的
+  // 有效 token 直发，测不到 openclaw 插件【写死在 openclaw.json 里的静态 token】是否失效
+  // （插件不读这个临时 token）。openclaw 必须用插件实际配置的 authorization 打 ingest，
+  // 才能真实反映运行时上报会不会 401。cloud/local 配置位置一致，统一走这条。
+  const verifyResult = agent === 'openclaw'
+    ? await verifyOpenClawTraceLink(args.cloud)
+    : args.cloud
+      ? await verifyTraceReportViaSdk(token, WORKSPACE_ID, args.pairCode, pythonCmd || 'python3', tokenSource)
+      : await verifyTraceReport(token, WORKSPACE_ID, args.pairCode, getOtelTracesUrl(false));
   if (verifyResult.success) {
     cloudResult.verify = 'ok';
   } else if (CLOUD_MODE) {