coze_lab 0.1.41 → 0.1.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coze_lab",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "description": "Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to CozeLoop",
   "keywords": [
     "cozeloop",

package/scripts/claude-code/cozeloop_hook.py

@@ -127,9 +127,9 @@ _DEFAULT_WORKSPACE_ID = "7649231955045072915"  # hardcoded spaceID fallback
 _COZE_CTX_OPEN = "<coze-context>"
 _COZE_CTX_CLOSE = "</coze-context>"
 
-# 中途事件(PostToolUse)增量上报的最小间隔（秒）。密集工具调用下用它节流，避免每秒多次 flush。
-# 终态事件(Stop)不受此限制。
-INCREMENTAL_UPLOAD_MIN_INTERVAL = float(os.environ.get("COZELOOP_INCREMENTAL_MIN_INTERVAL", "10"))
+# 实时 step 上报的批量间隔（秒）：距上次上报不足此值则跳过本次，把已结束的 span 攒到下次一起发，
+# 最多每 REALTIME_BATCH_INTERVAL 秒一批，压低请求数。终态(Stop)不受限，保证收尾即时完整。
+REALTIME_BATCH_INTERVAL = float(os.environ.get("COZELOOP_REALTIME_BATCH_INTERVAL", "5"))
 
 
 def _content_to_text(content: Any) -> str:
@@ -550,6 +550,19 @@ def read_new_messages(file_path: str, start_line: int = 0) -> List[Dict[str, Any
 
 # --- Content Helpers ---
 
+def _usage_int(usage: Any, key: str) -> int:
+    """Read a token count from a usage dict, treating missing/None/非数字 一律为 0。
+
+    Claude Code transcript 里 usage 的 cache_* 等字段常【存在但值为 null】，dict.get(key, 0)
+    对显式 null 返回 None 而非 0，后续 None + int / None > 0 会抛 TypeError，导致整个实时
+    上报失败、trace 查不到。这里统一兜底。
+    """
+    if not isinstance(usage, dict):
+        return 0
+    v = usage.get(key)
+    return v if isinstance(v, int) else 0
+
+
 def is_empty_content(content: Any) -> bool:
     """Return True if content carries no meaningful data."""
     if content is None:
@@ -676,7 +689,7 @@ def _group_subagent_steps(progress_msgs: List[Dict[str, Any]]) -> List[Dict[str,
                     existing.extend(content)
                 last_step["tool_calls"].extend(tool_calls)
                 usage = pmsg.get("usage", {})
-                if usage.get("input_tokens", 0) > 0 or usage.get("output_tokens", 0) > 0:
+                if _usage_int(usage, "input_tokens") > 0 or _usage_int(usage, "output_tokens") > 0:
                     last_step["assistant_message"]["message"]["usage"] = usage
             else:
                 steps.append({
@@ -849,7 +862,7 @@ def group_messages_into_turns(messages: List[Dict[str, Any]]) -> List[Dict[str,
                     last_step["tool_calls"].extend(tool_calls)
                     # Carry over usage from the later line (earlier line typically has zeros)
                     usage = message.get("usage", {})
-                    if usage.get("input_tokens", 0) > 0 or usage.get("output_tokens", 0) > 0:
+                    if _usage_int(usage, "input_tokens") > 0 or _usage_int(usage, "output_tokens") > 0:
                         last_step["assistant_message"]["message"]["usage"] = usage
                 else:
                     # New API response — create a new step
@@ -1329,10 +1342,10 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
 
                                 # Set token usage for this specific model call
                                 usage = assistant_message_obj.get("usage", {})
-                                input_tokens = usage.get("input_tokens", 0)
-                                output_tokens = usage.get("output_tokens", 0)
-                                cache_creation = usage.get("cache_creation_input_tokens", 0)
-                                cache_read = usage.get("cache_read_input_tokens", 0)
+                                input_tokens = _usage_int(usage, "input_tokens")
+                                output_tokens = _usage_int(usage, "output_tokens")
+                                cache_creation = _usage_int(usage, "cache_creation_input_tokens")
+                                cache_read = _usage_int(usage, "cache_read_input_tokens")
                                 if input_tokens > 0 or cache_creation > 0 or cache_read > 0:
                                     model_span.set_input_tokens(input_tokens + cache_creation + cache_read)
                                 if output_tokens > 0:
@@ -1402,10 +1415,10 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
 
                                         # Distribute total usage evenly across sub-agent model steps.
                                         total_usage = tool_call.get("_total_usage", {})
-                                        total_in = (total_usage.get("input_tokens", 0)
-                                                    + total_usage.get("cache_creation_input_tokens", 0)
-                                                    + total_usage.get("cache_read_input_tokens", 0))
-                                        total_out = total_usage.get("output_tokens", 0)
+                                        total_in = (_usage_int(total_usage, "input_tokens")
+                                                    + _usage_int(total_usage, "cache_creation_input_tokens")
+                                                    + _usage_int(total_usage, "cache_read_input_tokens"))
+                                        total_out = _usage_int(total_usage, "output_tokens")
                                         n_model_steps = len(sub_steps)
                                         per_step_in = total_in // n_model_steps if n_model_steps > 0 else 0
                                         per_step_out = total_out // n_model_steps if n_model_steps > 0 else 0
@@ -1615,6 +1628,249 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
     return True
 
 
+# --- 实时 step 级上报（方案 B：每个 step span 结束即可见）---------------------
+#
+# 设计：一个会话（thread）= 一条稳定 trace。首次触发时建 root span（claude_code_request）
+# 并把它的 to_header()（含 trace_id + root span_id + baggage）持久化到 state["rt_root_header"]。
+# 之后每次 hook 触发，从 header 重建 root context，把【自上次以来新完成的 step】作为
+# model_span(+其下 tool_span) 挂到固定 root 下、当场 flush —— 于是每个 step 结束即可查。
+# step 级水位线用 state["rt_last_global_step"] 跟踪（按 (turn_index, step_index) 线性展开）。
+#
+# 与整树 send_turns_to_cozeloop 的关系：实时路径独立成 trace，不依赖也不复用整树逻辑。
+# 终态(Stop)时调用 finalize_realtime_root 收尾（补 root 的 output、finish）。
+
+def _rt_state_key_header():
+    return "rt_root_header"
+
+def _flatten_completed_steps(turns: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """把 turns 线性展开成 step 列表；只取【已完成】的 step。
+
+    一个 step（assistant 一次模型调用 + 其触发的 tool_results）视为已完成的判定：
+    它后面还有别的 step/turn（说明模型已经继续往下走），或它带有 tool_results。
+    最后一个 step 若没有 tool_results 且无后继，视为仍可能在进行中 —— 留到下次。
+    返回的每项含: turn, step, turn_index, step_index, is_last_known。
+    """
+    flat = []
+    for ti, turn in enumerate(turns):
+        steps = turn.get("steps", [])
+        for si, step in enumerate(steps):
+            flat.append({"turn": turn, "step": step, "turn_index": ti, "step_index": si})
+    # 标记每个 step 是否“已完成”：非全局最后一个 step 一定已完成；
+    # 全局最后一个 step 仅当它有 tool_results（工具已回结果）才算完成。
+    completed = []
+    for idx, item in enumerate(flat):
+        is_global_last = (idx == len(flat) - 1)
+        has_results = bool(item["step"].get("tool_results"))
+        if (not is_global_last) or has_results:
+            completed.append(item)
+    return completed, len(flat)
+
+
+def send_steps_realtime(turns, session_id, history_turns, state, coze_tags_override=None, is_terminal=False):
+    """实时上报：把新完成的 step 作为 span 挂到稳定 root，结束即 flush。
+
+    返回 True 表示本次有推进（已发或已收尾），None 表示失败（state 不前进）。
+    """
+    token = get_fresh_token()
+    if token:
+        os.environ["COZELOOP_API_TOKEN"] = token
+    workspace_id = os.environ.get("COZELOOP_WORKSPACE_ID", "") or _DEFAULT_WORKSPACE_ID
+    client_kwargs = {"ultra_large_report": True, "upload_timeout": 120}
+    if workspace_id:
+        client_kwargs["workspace_id"] = workspace_id
+    if token:
+        client_kwargs["api_token"] = token
+    api_base_url = get_api_base_url()
+    if api_base_url:
+        client_kwargs["api_base_url"] = api_base_url
+
+    try:
+        client = cozeloop.new_client(**client_kwargs)
+    except Exception as e:
+        debug_log(f"[rt] new_client failed: {e}")
+        return None
+
+    try:
+        # ---- coze_tags（root 用，保证 root span 可按 message_id 查到）----
+        coze_tags = {}
+        for turn in list(turns) + list(history_turns or []):
+            um = turn.get("user_message", {}).get("message", {})
+            t = coze_context_tags(um.get("content") if um else None)
+            if t:
+                coze_tags = t
+                break
+        if not coze_tags and coze_tags_override:
+            coze_tags = dict(coze_tags_override)
+        coze_tags = {k: v for k, v in coze_tags.items() if isinstance(v, str) and v.strip()}
+
+        # ---- 取/建稳定 root ----
+        root_header = state.get(_rt_state_key_header())
+        root_ctx = None
+        if root_header:
+            try:
+                root_ctx = client.get_span_from_header(root_header)
+            except Exception as e:
+                debug_log(f"[rt] rebuild root from header failed: {e}")
+                root_ctx = None
+        if root_ctx is None or not getattr(root_ctx, "trace_id", ""):
+            # 首次：建 root span，立即发出（input=首条 user 文本），存 header。root 不在此处 finish，
+            # 用 start_new_trace 确保独立一条 trace。
+            first_user_text = ""
+            for turn in turns:
+                um = turn.get("user_message", {}).get("message", {})
+                uc = um.get("content") if um else None
+                if not is_empty_content(uc):
+                    first_user_text = format_content(uc)
+                    break
+            root_start_dt = None
+            if turns:
+                root_start_dt = _parse_ts(turns[0].get("user_message"))
+            root_span = client.start_span(name="claude_code_request", span_type="main",
+                                          start_time=root_start_dt, start_new_trace=True)
+            root_span.set_runtime(Runtime(library="claude-code"))
+            rtags = {"thread_id": session_id, "source": "claude_code", "realtime": True}
+            rtags.update(coze_tags)
+            root_span.set_tags(rtags)
+            rbag = {"thread_id": session_id}
+            rbag.update(coze_tags)
+            root_span.set_baggage(rbag)
+            if first_user_text:
+                root_span.set_input(first_user_text)
+            state[_rt_state_key_header()] = root_span.to_header()
+            root_ctx = client.get_span_from_header(state[_rt_state_key_header()])
+            # root 立即 finish 落库（后端 ResolveTraceIDByMessageID 按 root_span 查，root 必须可查）。
+            # 实测：root finish 后，子 span 仍可用其 header 挂到同一 trace_id 下，不影响后续增量。
+            root_span.finish()
+            client.flush()
+            debug_log(f"[rt] root created+finished trace_id={getattr(root_ctx,'trace_id','?')}")
+
+        # ---- 发新完成的 step ----
+        completed, total_steps = _flatten_completed_steps(turns)
+        last_global = state.get("rt_last_global_step", 0)
+        new_items = completed[last_global:]
+        # 批量节流：非终态时，距上次上报不足 REALTIME_BATCH_INTERVAL 秒则本次不发，
+        # 把已结束的 step 攒到下次触发一起发（最多每 5s 一批）。终态(Stop)不节流，立即收尾。
+        if new_items and not is_terminal:
+            since = time.time() - state.get("rt_last_upload_ts", 0)
+            if since < REALTIME_BATCH_INTERVAL:
+                debug_log(f"[rt] batch throttle: {since:.1f}s<{REALTIME_BATCH_INTERVAL}s, defer {len(new_items)} step(s)")
+                new_items = []
+        sent = 0
+        for item in new_items:
+            step = item["step"]
+            assistant_msg = step.get("assistant_message", {})
+            amo = assistant_msg.get("message", {})
+            model_name = amo.get("model", "claude-code")
+            gidx = last_global + sent  # 全局 step 序号，用于命名
+            step_start_dt = _parse_ts(assistant_msg)
+            step_end_dt = None
+            for r in step.get("tool_results", []):
+                te = _parse_ts_str(r.get("_result_ts"))
+                if te:
+                    step_end_dt = te
+
+            # model_span 挂 root
+            mspan = client.start_span(name=f"model_call_{gidx}", span_type="model",
+                                      start_time=step_start_dt, child_of=root_ctx)
+            mspan.set_runtime(Runtime(library="claude-code"))
+            try:
+                mspan.set_model_name(model_name)
+            except Exception:
+                pass
+            if step_start_dt is not None and step_end_dt is not None:
+                _set_finish_time_safe(mspan, step_end_dt)
+            raw_content = amo.get("content", [])
+            text_parts = []
+            if isinstance(raw_content, list):
+                for it in raw_content:
+                    if isinstance(it, dict) and it.get("type") == "text" and it.get("text"):
+                        text_parts.append(it["text"])
+            elif isinstance(raw_content, str):
+                text_parts.append(raw_content)
+            mspan.set_input(format_content((assistant_msg.get("message", {}) or {}).get("content")))
+            if text_parts:
+                mspan.set_output("\n".join(text_parts))
+            usage = amo.get("usage", {})
+            it_tok = _usage_int(usage, "input_tokens") + _usage_int(usage, "cache_creation_input_tokens") + _usage_int(usage, "cache_read_input_tokens")
+            if it_tok > 0:
+                try: mspan.set_input_tokens(it_tok)
+                except Exception: pass
+            if _usage_int(usage, "output_tokens") > 0:
+                try: mspan.set_output_tokens(_usage_int(usage, "output_tokens"))
+                except Exception: pass
+            mspan_ctx = client.get_span_from_header(mspan.to_header())
+            mspan.finish()
+
+            # tool_span 挂 model_span
+            for tc in step.get("tool_calls", []):
+                tname = tc.get("name", "unknown")
+                tid = tc.get("id")
+                tool_end_dt = None
+                for r in step.get("tool_results", []):
+                    if r.get("tool_use_id") == tid:
+                        tool_end_dt = _parse_ts_str(r.get("_result_ts"))
+                        break
+                tspan = client.start_span(name=f"tool_{tname}", span_type="tool",
+                                          start_time=step_start_dt, child_of=mspan_ctx)
+                tspan.set_runtime(Runtime(library="claude-code"))
+                if tool_end_dt is not None:
+                    _set_finish_time_safe(tspan, tool_end_dt)
+                tspan.set_tags({"tool_name": tname, "tool_call_id": tid, "step_index": gidx})
+                tspan.set_input(json.dumps(tc.get("input", {}), ensure_ascii=False)[:2000])
+                for r in step.get("tool_results", []):
+                    if r.get("tool_use_id") == tid:
+                        tspan.set_output(_format_tool_output(r.get("content", "")))
+                        break
+                tspan.finish()
+            sent += 1
+            # 每个 step 立即 flush —— 这是“结束即可见”的关键。
+            client.flush()
+
+        new_last = last_global + sent
+        state["rt_last_global_step"] = new_last
+        if sent > 0:
+            state["rt_last_upload_ts"] = time.time()
+
+        # ---- 收尾：终态时补 root output 并 finish ----
+        if is_terminal:
+            last_output = None
+            for turn in reversed(turns):
+                for step in reversed(turn.get("steps", [])):
+                    amo = step.get("assistant_message", {}).get("message", {})
+                    c = amo.get("content", [])
+                    if isinstance(c, list):
+                        tp = [x.get("text", "") for x in c if isinstance(x, dict) and x.get("type") == "text" and x.get("text")]
+                        if tp:
+                            last_output = "\n".join(tp); break
+                    elif isinstance(c, str) and c.strip():
+                        last_output = c; break
+                if last_output:
+                    break
+            if root_ctx is not None and last_output:
+                # 重发一个同 trace 的收尾 span 承载最终输出（root 对象已不可用，用子 span 兜底）。
+                fin = client.start_span(name="final_response", span_type="main", child_of=root_ctx)
+                fin.set_runtime(Runtime(library="claude-code"))
+                fin.set_output(last_output)
+                fin.finish()
+            client.flush()
+            debug_log(f"[rt] finalized, total sent steps={new_last}")
+
+        debug_log(f"[rt] sent {sent} new step(s), last_global={new_last}/{total_steps}, terminal={is_terminal}")
+        return True
+    except Exception as e:
+        debug_log(f"[rt] send_steps_realtime error: {e}")
+        return None
+    finally:
+        try:
+            client.flush()
+        except Exception:
+            pass
+        try:
+            client.close()
+        except Exception:
+            pass
+
+
 # --- Hook Input ---
 
 def read_hook_stdin() -> Dict[str, Any]:
@@ -1674,28 +1930,19 @@ def main():
     debug_log(f"Using conversation file: {conversation_file}")
     print(f"[CozeLoop] 读取会话文件: {conversation_file}", file=sys.stderr)
 
-    # Load state to know where to start reading
+    # Load state
     state_file = get_state_file_path(conversation_file)
     state = load_state(state_file)
-    last_processed_line = state.get("last_processed_line", 0)
-
-    # 节流：PostToolUse 在密集工具调用下会高频触发。距上次上报不足 INCREMENTAL_UPLOAD_MIN_INTERVAL
-    # 秒则跳过本次增量上报，避免每秒多次 flush 抬高上报量/成本。终态事件(Stop)永不被节流，
-    # 保证任务结束时一定收尾上报最后一批。
-    if not is_terminal_event:
-        now_ts = time.time()
-        last_upload_ts = state.get("last_upload_ts", 0)
-        if now_ts - last_upload_ts < INCREMENTAL_UPLOAD_MIN_INTERVAL:
-            debug_log(f"throttled: event={hook_event} since_last={now_ts - last_upload_ts:.1f}s < {INCREMENTAL_UPLOAD_MIN_INTERVAL}s, skip")
-            return
-
-    # Read new messages from the file
-    new_messages = read_new_messages(conversation_file, last_processed_line)
-
-    # Determine session ID: prefer stdin, then messages, then state, then generate
+
+    # 方案 B（实时 step 级上报）：读【全量】消息重建完整 turn/step 序列。实时路径用全局 step
+    # 水位线 state["rt_last_global_step"] 增量，不再用 last_processed_line（那是整树增量的水位线）。
+    # 每次 hook 触发（PostToolUse=每次工具调用后）都把新完成的 step 发出，结束即可见，不节流。
+    all_messages = read_new_messages(conversation_file, 0)
+
+    # Determine session ID
     session_id = hook_input.get("session_id")
     if not session_id:
-        for msg in new_messages:
+        for msg in all_messages:
             if msg.get("sessionId"):
                 session_id = msg.get("sessionId")
                 break
@@ -1704,83 +1951,48 @@ def main():
             session_id = state["session_id"]
         else:
             session_id = f"claude-code-{datetime.now().strftime('%Y%m%d-%H%M%S')}-{os.getpid()}"
-            debug_log(f"Generated new session ID: {session_id}")
-
     state["session_id"] = session_id
-    debug_log(f"Session ID: {session_id}")
+    debug_log(f"Session ID: {session_id}, event={hook_event}")
 
-    if not new_messages:
-        debug_log("No new messages to process.")
+    if not all_messages:
+        debug_log("No messages to process.")
         return
 
-    debug_log(f"Found {len(new_messages)} new messages.")
-
-    # Read historical messages to build context for model input
-    history_turns = []
-    if last_processed_line > 0:
-        historical_messages = read_new_messages(conversation_file, 0)
-        historical_messages = [m for m in historical_messages if m.get("_line_number", 0) < last_processed_line]
-        history_turns = group_messages_into_turns(historical_messages)
-        debug_log(f"Loaded {len(history_turns)} historical turn(s) for context.")
-
-    # Group messages into turns and send to CozeLoop — only if coze-context present.
-    turns = group_messages_into_turns(new_messages)
-    if turns:
-        # coze-context 只出现在首条用户消息里（cozelab 注入的 agent 才有）。增量 hook 触发时，
-        # 新消息往往全是工具调用/结果（不带 coze-context），故必须连同历史 turns 一起判断——
-        # 只要整个会话出现过 coze-context，就说明是被注入的 agent，后续增量都应上报。
-        def _turn_has_ctx(turn):
-            return bool(coze_context_tags(
-                (turn.get("user_message", {}).get("message", {}) or {}).get("content")
-            ))
-        has_coze_ctx = any(_turn_has_ctx(t) for t in turns) or any(_turn_has_ctx(t) for t in history_turns)
-        if not has_coze_ctx:
-            debug_log("No coze-context found in any turn (incl. history), skipping upload.")
-            return
-
-        # 持久化 coze_tags 到 state：<coze-context> 只在首 turn，后续增量批次的 turns 不含它，
-        # 其 root span 会缺 coze_message_id 而无法按 message_id 查到。首次解析到就存 state，
-        # 后续批次作为 override 传给 send_turns，保证每个 turn 的 root span 都带 coze_* tag。
-        for _t in list(turns) + list(history_turns):
+    # 全量分组成 turns/steps
+    turns = group_messages_into_turns(all_messages)
+    if not turns:
+        debug_log("No turns.")
+        return
+
+    # coze-context 判定：整个会话出现过即可（首 turn 注入）。
+    def _turn_has_ctx(turn):
+        return bool(coze_context_tags(
+            (turn.get("user_message", {}).get("message", {}) or {}).get("content")
+        ))
+    if not any(_turn_has_ctx(t) for t in turns):
+        debug_log("No coze-context in any turn, skipping upload.")
+        return
+
+    # 持久化 coze_tags 到 state，供 root span 注入（保证可按 message_id 查到）。
+    if not state.get("coze_tags"):
+        for _t in turns:
             _um = (_t.get("user_message", {}).get("message", {}) or {})
             _tags = {k: v for k, v in coze_context_tags(_um.get("content")).items() if isinstance(v, str) and v.strip()}
             if _tags:
                 state["coze_tags"] = _tags
                 break
-        coze_tags_override = state.get("coze_tags") or None
-
-        # turn 边界控制：中途事件(PostToolUse)触发时，最后一个 turn 往往仍在进行中
-        # （后续还会追加 step）。若此刻就上报并推进其行号，同一逻辑 turn 会在下次触发时
-        # 因缺了起始 user 消息而被拆成新的 root span。故中途事件只上报“已完成”的 turn
-        # （= 除最后一个之外的所有 turn），把最后一个留到下次/收尾。终态事件(Stop)上报全部。
-        if is_terminal_event:
-            turns_to_send = turns
-        else:
-            turns_to_send = turns[:-1]
-        if not turns_to_send:
-            debug_log(f"event={hook_event}: no completed turn to send yet (turns={len(turns)}), defer")
-            return
-
-        print(f"[CozeLoop] 开始上报: session={session_id}, event={hook_event}, turns={len(turns_to_send)}/{len(turns)}", file=sys.stderr)
-        uploaded = send_turns_to_cozeloop(turns_to_send, session_id, history_turns, coze_tags_override=coze_tags_override)
-        if uploaded is None:
-            debug_log("Send failed, state not advanced.")
-            return
-
-        # 推进 last_processed_line：只推进到已上报 turn 覆盖的最后一行。中途事件保留了最后一个
-        # 未完成 turn，故推进到“倒数第二个 turn 的末行”，让未完成 turn 的所有行下次重新读取。
-        if is_terminal_event:
-            last_line_in_batch = max(msg.get("_line_number", 0) for msg in new_messages)
-            state["last_processed_line"] = last_line_in_batch + 1
-        else:
-            # turns_to_send 是 turns[:-1]，下一个未发送 turn 的起始行即新的水位线。
-            next_turn_start = turns[-1].get("start_line", 0)
-            state["last_processed_line"] = next_turn_start
-        state["last_upload_ts"] = time.time()
-        save_state(state_file, state)
-        print(f"[CozeLoop] 上报完成 ✓ session={session_id}, turns={len(turns_to_send)}", file=sys.stderr)
-        debug_log(f"State updated. event={hook_event} last_processed_line={state['last_processed_line']}")
-
+    coze_tags_override = state.get("coze_tags") or None
+
+    print(f"[CozeLoop] 实时上报: session={session_id}, event={hook_event}", file=sys.stderr)
+    ok = send_steps_realtime(turns, session_id, [], state,
+                             coze_tags_override=coze_tags_override,
+                             is_terminal=is_terminal_event)
+    if ok is None:
+        debug_log("Realtime send failed, state not advanced.")
+        return
+    save_state(state_file, state)
+    print(f"[CozeLoop] 实时上报完成 ✓ session={session_id}, last_step={state.get('rt_last_global_step')}", file=sys.stderr)
+    debug_log(f"State saved. rt_last_global_step={state.get('rt_last_global_step')}")
     debug_log("Hook finished.")
 
 if __name__ == "__main__":

package/scripts/codex/cozeloop_hook.py

@@ -50,9 +50,9 @@ _REFRESH_LOCK_STALE = 30
 _DEFAULT_WORKSPACE_ID = "7649231955045072915"  # hardcoded spaceID fallback
 _OTEL_SUFFIX = "/v1/loop/opentelemetry"
 
-# 中途事件(PostToolUse)增量上报的最小间隔（秒）。密集工具调用下用它节流，避免每次工具调用都 flush。
-# 终态事件(Stop/SubagentStop)不受此限制。
-INCREMENTAL_UPLOAD_MIN_INTERVAL = float(os.environ.get("COZELOOP_INCREMENTAL_MIN_INTERVAL", "10"))
+# 实时 tool span 上报的批量间隔（秒）：距上次上报不足此值则本次不发，把已结束的 tool span
+# 攒到下次一起发（最多每 5s 一批）。终态(Stop/SubagentStop)不受限，立即收尾。
+REALTIME_BATCH_INTERVAL = float(os.environ.get("COZELOOP_REALTIME_BATCH_INTERVAL", "5"))
 
 
 # --- coze-context parsing -------------------------------------------------
@@ -787,6 +787,18 @@ def truncate_text(text: str, limit: int = 12000) -> str:
 
 # --- Message Grouping ---
 
+def _usage_int(usage, key):
+    """从 token_usage dict 读 token 数，missing/None/非数字 一律按 0。
+
+    transcript 里 token_usage 字段可能【存在但值为 null】，dict.get(key, 0) 对显式 null
+    返回 None 而非 0，后续 None > 0 / None + int 会抛 TypeError 中断上报。这里统一兜底。
+    """
+    if not isinstance(usage, dict):
+        return 0
+    v = usage.get(key)
+    return v if isinstance(v, int) else 0
+
+
 def _parse_ts(obj):
     """从 codex entry/payload 的 timestamp 解析 datetime（带时区）。失败返回 None。
 
@@ -1299,8 +1311,8 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
 
                                 # Set token usage
                                 token_usage = turn.get("token_usage", {})
-                                input_tokens = token_usage.get("input_tokens", 0)
-                                output_tokens = token_usage.get("output_tokens", 0)
+                                input_tokens = _usage_int(token_usage, "input_tokens")
+                                output_tokens = _usage_int(token_usage, "output_tokens")
                                 if input_tokens > 0:
                                     model_span.set_input_tokens(input_tokens)
                                 if output_tokens > 0:
@@ -1446,10 +1458,12 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                                                     sa_model_span.set_output(ModelOutput(choices=sa_choices))
 
                                                     sa_token = sa_turn.get("token_usage", {})
-                                                    if sa_token.get("input_tokens", 0) > 0:
-                                                        sa_model_span.set_input_tokens(sa_token["input_tokens"])
-                                                    if sa_token.get("output_tokens", 0) > 0:
-                                                        sa_model_span.set_output_tokens(sa_token["output_tokens"])
+                                                    sa_in = _usage_int(sa_token, "input_tokens")
+                                                    sa_out = _usage_int(sa_token, "output_tokens")
+                                                    if sa_in > 0:
+                                                        sa_model_span.set_input_tokens(sa_in)
+                                                    if sa_out > 0:
+                                                        sa_model_span.set_output_tokens(sa_out)
 
                                             # Subagent tool spans
                                             for sa_tc in sa_turn.get("tool_calls", []):
@@ -1552,6 +1566,165 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
     return ctx
 
 
+# --- 实时 step 级上报（方案 B：每个 tool_call 结束即可见）---------------------
+#
+# 与 claude-code 同架构：一个会话 = 一条稳定 trace。首次建 root(codex_request)立即 finish 并存
+# to_header() 到 state["rt_root_header"]；之后每次触发把【新完成的 tool_call】(有 result 的)作为
+# tool span 挂到固定 root、当场 flush。codex 的实时单元是 tool_call（turn 内平铺，按 call_id 关联
+# result）。全局水位线 state["rt_last_tool"] 跟踪已发的 tool_call 数。
+
+def send_steps_realtime(turns, session_id, state, model_name="codex", coze_tags_override=None, is_terminal=False):
+    import cozeloop
+    from cozeloop.spec.tracespec import Runtime
+    token = get_fresh_token()
+    if token:
+        os.environ["COZELOOP_API_TOKEN"] = token
+    workspace_id = os.environ.get("COZELOOP_WORKSPACE_ID", "") or _DEFAULT_WORKSPACE_ID
+    client_kwargs = {"ultra_large_report": True, "upload_timeout": 120}
+    if workspace_id:
+        client_kwargs["workspace_id"] = workspace_id
+    if token:
+        client_kwargs["api_token"] = token
+    api_base_url = get_api_base_url()
+    if api_base_url:
+        client_kwargs["api_base_url"] = api_base_url
+    try:
+        client = cozeloop.new_client(**client_kwargs)
+    except Exception as e:
+        hook_log(f"[rt] new_client failed: {e}")
+        return None
+
+    try:
+        # coze_tags
+        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
+                break
+        if not coze_tags and coze_tags_override:
+            coze_tags = dict(coze_tags_override)
+        coze_tags = {k: v for k, v in coze_tags.items() if isinstance(v, str) and v.strip()}
+
+        # 取/建稳定 root
+        root_header = state.get("rt_root_header")
+        root_ctx = None
+        if root_header:
+            try:
+                root_ctx = client.get_span_from_header(root_header)
+            except Exception:
+                root_ctx = None
+        if root_ctx is None or not getattr(root_ctx, "trace_id", ""):
+            first_user_text = ""
+            for turn in turns:
+                if turn.get("user_message_text"):
+                    first_user_text = turn["user_message_text"]
+                    break
+            root_start_dt = _parse_ts_value(turns[0].get("tool_calls", [{}])[0].get("_ts")) if turns and turns[0].get("tool_calls") else None
+            root_span = client.start_span(name="codex_request", span_type="main",
+                                          start_time=root_start_dt, start_new_trace=True)
+            root_span.set_runtime(Runtime(library="codex-cli"))
+            rtags = {"thread_id": session_id, "source": "codex_cli", "realtime": True}
+            rtags.update(coze_tags)
+            root_span.set_tags(rtags)
+            rbag = {"thread_id": session_id}
+            rbag.update(coze_tags)
+            root_span.set_baggage(rbag)
+            if first_user_text:
+                root_span.set_input(truncate_text(first_user_text))
+            state["rt_root_header"] = root_span.to_header()
+            root_ctx = client.get_span_from_header(state["rt_root_header"])
+            root_span.finish()  # 立即 finish 落库（后端按 root_span 查），子 span 仍可挂同 trace
+            client.flush()
+            hook_log(f"[rt] root created trace_id={getattr(root_ctx,'trace_id','?')}")
+
+        # 线性展开所有 tool_call（带 result 的才算完成），按全局序增量发
+        flat = []
+        for ti, turn in enumerate(turns):
+            results = {r.get("call_id"): r for r in turn.get("tool_results", [])}
+            for tc in turn.get("tool_calls", []):
+                cid = tc.get("call_id")
+                flat.append({"tc": tc, "result": results.get(cid), "turn_index": ti})
+        # 只发已完成（有 result）的，且全局最后一个若无 result 则留到下次
+        completed = []
+        for idx, item in enumerate(flat):
+            is_last = (idx == len(flat) - 1)
+            if item["result"] is not None or (not is_last):
+                completed.append(item)
+        last_tool = state.get("rt_last_tool", 0)
+        new_items = completed[last_tool:]
+        # 批量节流：非终态时距上次上报<5s 则本次不发，攒到下次一起发。终态不节流。
+        if new_items and not is_terminal:
+            since = time.time() - state.get("rt_last_upload_ts", 0)
+            if since < REALTIME_BATCH_INTERVAL:
+                hook_log(f"[rt] batch throttle {since:.1f}s<{REALTIME_BATCH_INTERVAL}s defer {len(new_items)} tool(s)")
+                new_items = []
+        sent = 0
+        for item in new_items:
+            tc = item["tc"]; result = item["result"]
+            gidx = last_tool + sent
+            tname = tc.get("name", "unknown")
+            start_dt = _parse_ts_value(tc.get("_ts"))
+            end_dt = _parse_ts_value(result.get("_ts")) if result else None
+            # 每个 tool_call 用一个 model_call_+tool 子树（与 claude-code 视觉一致）
+            mspan = client.start_span(name=f"model_call_{gidx}", span_type="model",
+                                      start_time=start_dt, child_of=root_ctx)
+            mspan.set_runtime(Runtime(library="codex-cli"))
+            try: mspan.set_model_name(model_name)
+            except Exception: pass
+            if start_dt and end_dt:
+                _set_finish_time_safe(mspan, end_dt)
+            mspan.set_input(truncate_text(json.dumps(tc.get("input", {}), ensure_ascii=False)))
+            mspan_ctx = client.get_span_from_header(mspan.to_header())
+            mspan.finish()
+
+            tspan = client.start_span(name=f"tool_{tname}", span_type="tool",
+                                      start_time=start_dt, child_of=mspan_ctx)
+            tspan.set_runtime(Runtime(library="codex-cli"))
+            if end_dt:
+                _set_finish_time_safe(tspan, end_dt)
+            tspan.set_tags({"tool_name": tname, "tool_call_id": tc.get("call_id"), "step_index": gidx})
+            tspan.set_input(truncate_text(json.dumps(tc.get("input", {}), ensure_ascii=False)))
+            if result is not None:
+                tspan.set_output(truncate_text(str(result.get("output", ""))))
+            tspan.finish()
+            sent += 1
+            client.flush()  # 每个 tool_call 立即 flush → 结束即可见
+
+        state["rt_last_tool"] = last_tool + sent
+        if sent > 0:
+            state["rt_last_upload_ts"] = time.time()
+
+        if is_terminal:
+            # 收尾：补最终 assistant 输出
+            last_out = ""
+            for turn in reversed(turns):
+                for am in reversed(turn.get("assistant_messages", [])):
+                    txt = extract_assistant_text(am)
+                    if txt:
+                        last_out = txt; break
+                if last_out:
+                    break
+            if last_out:
+                fin = client.start_span(name="final_response", span_type="main", child_of=root_ctx)
+                fin.set_runtime(Runtime(library="codex-cli"))
+                fin.set_output(truncate_text(last_out))
+                fin.finish()
+            client.flush()
+            hook_log(f"[rt] finalized total_tools={state['rt_last_tool']}")
+
+        hook_log(f"[rt] sent {sent} tool span(s), last_tool={state['rt_last_tool']}, terminal={is_terminal}")
+        return True
+    except Exception as e:
+        hook_log(f"[rt] error: {e}")
+        return None
+    finally:
+        try: client.flush()
+        except Exception: pass
+        try: client.close()
+        except Exception: pass
+
+
 # --- Main Execution ---
 
 def main():
@@ -1615,19 +1788,19 @@ def main():
     state_file = get_state_file_path(transcript_path)
     state = load_state(state_file)
 
-    # Read new entries
-    entries = read_rollout_messages(transcript_path, state["last_processed_line"])
+    # 方案 B（实时）：读【全量】entries 重建完整 turn/tool 序列。实时路径用全局 tool 水位线
+    # state["rt_last_tool"] 增量，每次触发把新完成的 tool_call 发出，结束即可见，不节流。
+    entries = read_rollout_messages(transcript_path, 0)
 
     if not entries:
-        hook_log(f"skip no new entries transcript={transcript_path}")
-        debug_log("No new entries to process")
+        hook_log(f"skip no entries transcript={transcript_path}")
+        debug_log("No 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']}")
+    hook_log(f"read entries={len(entries)} (full) transcript={transcript_path}")
 
     # Parse session identity
-    all_entries_for_meta = read_rollout_messages(transcript_path, 0)
+    all_entries_for_meta = entries
     session_info = parse_session_meta(all_entries_for_meta)
 
     session_id = session_info["session_id"] or hook_input.get("session_id", "")
@@ -1679,25 +1852,14 @@ def main():
 
     # Send turns to CozeLoop — only if at least one turn carries coze-context.
     if turns:
-        # coze-context 只出现在首个 turn 的 user 消息里。增量上报推进后，后续批次的 turns
-        # 已不含首 turn，直接判断会误判为"无 coze-context"而跳过。故用 state 持久化"本会话
-        # 曾见过 coze-context"标记：一旦见过，后续增量批次都视为应上报（与 claude-code 用
-        # history_turns 判断等效）。
-        seen_ctx = bool(state.get("seen_coze_context"))
-        has_coze_ctx = seen_ctx or any(
-            turn_coze_context(t)
-            for t in turns
-        )
+        # coze-context 只出现在首个 turn。会话出现过即视为应上报。
+        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
-        if not seen_ctx:
-            state["seen_coze_context"] = True
 
-        # 持久化 coze_tags 到 state：<coze-context> 只在首 turn，后续增量批次不含它，其 root span
-        # 会缺 coze_message_id 无法按 message_id 查到。首次解析到就存 state，后续批次作为 override
-        # 传给 send_turns，保证每个 turn 的 root span 都带 coze_* tag。
+        # 持久化 coze_tags 到 state，供 root span 注入。
         if not state.get("coze_tags"):
             for _t in turns:
                 _tags = {f"coze_{k}": v for k, v in turn_coze_context(_t).items() if isinstance(v, str) and v.strip()}
@@ -1706,50 +1868,17 @@ def main():
                     break
         coze_tags_override = state.get("coze_tags") or None
 
-        # 节流：PostToolUse 在密集工具调用下高频触发。距上次上报不足间隔则跳过本次增量上报。
-        # 终态事件(Stop/SubagentStop)永不被节流，保证 turn 结束时一定收尾。
-        if not is_terminal_event:
-            now_ts = time.time()
-            last_upload_ts = state.get("last_upload_ts", 0)
-            if now_ts - last_upload_ts < INCREMENTAL_UPLOAD_MIN_INTERVAL:
-                hook_log(f"throttled event={hook_event} since_last={now_ts - last_upload_ts:.1f}s session_id={session_id}")
-                debug_log(f"throttled: event={hook_event}, skip incremental upload")
-                return
-
-        # turn 边界控制：中途事件(PostToolUse)触发时，最后一个 turn 往往仍在进行中
-        # （task_complete 尚未到达，后续还会追加内容）。只上报已完成 turn（turns[:-1]），
-        # 把最后一个留到下次/收尾，避免同一 turn 被拆成多个 trace。终态事件上报全部。
-        if is_terminal_event:
-            turns_to_send = turns
-        else:
-            turns_to_send = turns[:-1]
-        if not turns_to_send:
-            hook_log(f"defer no completed turn event={hook_event} turns={len(turns)} session_id={session_id}")
-            debug_log(f"event={hook_event}: no completed turn to send yet, defer")
+        # 方案 B 实时：把新完成的 tool_call 作为 span 挂稳定 root，结束即可见。不节流。
+        ok = send_steps_realtime(turns, session_id, state, model_name=model_name,
+                                 coze_tags_override=coze_tags_override,
+                                 is_terminal=is_terminal_event)
+        if ok is None:
+            hook_log(f"realtime send failed session_id={session_id}")
+            debug_log("Realtime send failed, state not advanced")
             return
-
-        history_context = state.get("conversation_history", [])
-        updated_history = send_turns_to_cozeloop(
-            turns_to_send, session_id, model_name,
-            history_context=history_context,
-            coze_tags_override=coze_tags_override,
-        )
-        if updated_history is not None:
-            # 推进 last_processed_line：终态推进到所有 entry 末行；中途保留最后一个未完成 turn，
-            # 推进到该 turn 的起始行，让它的所有 entry 下次重新读取。
-            if is_terminal_event:
-                last_line = max(e.get("_line_number", 0) for e in entries) + 1
-            else:
-                last_line = turns[-1].get("start_line", max(e.get("_line_number", 0) for e in entries) + 1)
-            state["last_processed_line"] = last_line
-            state["conversation_history"] = updated_history
-            state["last_upload_ts"] = time.time()
-            save_state(state_file, state)
-            hook_log(f"state advanced event={hook_event} last_line={last_line} sent={len(turns_to_send)}/{len(turns)} 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")
+        save_state(state_file, state)
+        hook_log(f"rt state saved event={hook_event} last_tool={state.get('rt_last_tool')} session_id={session_id}")
+        debug_log(f"State saved. rt_last_tool={state.get('rt_last_tool')}")
     else:
         hook_log(f"skip no turns session_id={session_id}")
         debug_log("No turns to send")

package/scripts/openclaw/dist/cozeloop-exporter.js

@@ -633,8 +633,9 @@ export class CozeloopExporter {
         this.provider = new BasicTracerProvider({ resource });
         this.provider.addSpanProcessor(new BatchSpanProcessor(exporter, {
             maxQueueSize: 100,
-            maxExportBatchSize: this.config.batchSize || 10,
-            scheduledDelayMillis: this.config.batchInterval || 5000,
+            // 实时上报：每个 span 结束即发。maxExportBatchSize=1 + 短延迟，不攒批。
+            maxExportBatchSize: this.config.batchSize || 1,
+            scheduledDelayMillis: this.config.batchInterval || 500,
         }));
         // Do NOT call this.provider.register() — it sets the global TracerProvider
         // singleton, so if the plugin is activated more than once (e.g. gateway +

package/scripts/openclaw/dist/index.js

@@ -534,8 +534,10 @@ const cozeloopTracePlugin = {
             workspaceId,
             serviceName: pluginConfig.serviceName || "openclaw-agent",
             debug: pluginConfig.debug || false,
-            batchSize: pluginConfig.batchSize || 10,
-            batchInterval: pluginConfig.batchInterval || 5000,
+            // 实时上报：每个 span 结束即发，不攒批。batchSize=1 + 短延迟让 span 秒级可见。
+            // 如需降上报量可在 plugin config 显式调大 batchSize/batchInterval。
+            batchSize: pluginConfig.batchSize || 1,
+            batchInterval: pluginConfig.batchInterval || 500,
             enabledHooks: pluginConfig.enabledHooks,
             disableLocalCredentials: pluginConfig.disableLocalCredentials === true,
             logFile: pluginConfig.logFile,

package/scripts/openclaw/openclaw.plugin.json

@@ -35,13 +35,13 @@
       },
       "batchSize": {
         "type": "number",
-        "default": 10,
-        "description": "Number of spans to buffer before sending"
+        "default": 1,
+        "description": "Spans per export batch. Default 1 = 每个 span 结束即发(实时)。调大可降上报量但牺牲实时性。"
       },
       "batchInterval": {
         "type": "number",
-        "default": 5000,
-        "description": "Maximum time (ms) to wait before sending buffered spans"
+        "default": 500,
+        "description": "Max ms to wait before flushing. Default 500ms 配合 batchSize=1 实现秒级可见。"
       },
       "enabledHooks": {
         "type": "array",