openclaw-tencent-cls-plugin 1.0.0

package/index.ts

@@ -0,0 +1,18 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/core";
+import { createTencentClsPlugin } from "./src/service.js";
+import type { TencentClsPluginConfig } from "./src/service.js";
+
+export default definePluginEntry({
+  id: "openclaw-tencent-cls-plugin",
+  name: "OpenClaw Tencent CLS Plugin",
+  description:
+    "腾讯云 CLS 可观测性插件，将 OpenClaw 全链路 Trace 数据直接写入腾讯云日志服务（CLS）",
+
+  register(api) {
+    const config = (api.pluginConfig ?? {}) as unknown as TencentClsPluginConfig;
+    const plugin = createTencentClsPlugin(config);
+    plugin.registerHooks(api);
+    api.registerService(plugin.service);
+    api.logger.info("[openclaw-tencent-cls-plugin] Plugin registered");
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,33 @@
+{
+  "id": "openclaw-tencent-cls-plugin",
+  "name": "OpenClaw Tencent CLS Plugin",
+  "description": "腾讯云 CLS 可观测性插件，将 OpenClaw 全链路 Trace 数据直接写入腾讯云日志服务（CLS）",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["topicId", "endpoint", "secretId", "secretKey"],
+    "properties": {
+      "topicId": {
+        "type": "string",
+        "description": "腾讯云 CLS 日志主题 ID"
+      },
+      "endpoint": {
+        "type": "string",
+        "description": "CLS 接入点，如 ap-guangzhou.cls.tencentcs.com"
+      },
+      "secretId": {
+        "type": "string",
+        "description": "腾讯云 SecretId"
+      },
+      "secretKey": {
+        "type": "string",
+        "description": "腾讯云 SecretKey"
+      },
+      "token": {
+        "type": "string",
+        "description": "临时 Token（可选，使用临时密钥时填写）"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "openclaw-tencent-cls-plugin",
+  "version": "1.0.0",
+  "description": "OpenClaw Tencent Cloud CLS observability plugin",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.3"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "tencentcloud-cls-sdk-nodejs": "1.0.1"
+  }
+}

package/src/service.ts

@@ -0,0 +1,985 @@
+import { Producer, LogItem, Content } from "tencentcloud-cls-sdk-nodejs";
+
+// ─── Span Names ──────────────────────────────────────────────────────────
+
+const SPAN = {
+  MESSAGE: "openclaw.message",
+  SESSION: "openclaw.session",
+  AGENT_PROCESSING: "openclaw.agent",
+  MODEL_RESOLVE: "openclaw.model.resolve",
+  PROMPT_BUILD: "openclaw.prompt.build",
+  LLM_CALL: "openclaw.llm.call",
+  TOOL: "openclaw.tool",
+  COMPACTION: "openclaw.compaction",
+  SUBAGENT: "openclaw.subagent",
+  REPLY: "openclaw.reply.send",
+} as const;
+
+// ─── Attribute Keys ───────────────────────────────────────────────────────
+
+const A = {
+  GENAI_SYSTEM: "gen_ai.system",
+  GENAI_REQUEST_MODEL: "gen_ai.request.model",
+  GENAI_RESPONSE_MODEL: "gen_ai.response.model",
+  GENAI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens",
+  GENAI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
+  GENAI_USAGE_CACHE_READ_INPUT: "gen_ai.usage.cache_read.input_tokens",
+  GENAI_USAGE_CACHE_CREATION_INPUT: "gen_ai.usage.cache_creation.input_tokens",
+  GENAI_USAGE_PROMPT_TOKENS: "gen_ai.usage.prompt_tokens",
+  GENAI_USAGE_COMPLETION_TOKENS: "gen_ai.usage.completion_tokens",
+  GENAI_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens",
+  GENAI_MODEL_NAME: "gen_ai.model_name",
+  GENAI_PROVIDER_NAME: "gen_ai.provider.name",
+  LLM_REQUEST_TYPE: "llm.request.type",
+  TRACELOOP_ENTITY_INPUT: "traceloop.entity.input",
+  TRACELOOP_ENTITY_OUTPUT: "traceloop.entity.output",
+  SESSION_KEY: "openclaw.session.key",
+  MESSAGE_TO: "openclaw.message.to",
+  MESSAGE_SUCCESS: "openclaw.message.success",
+  TOOL_DURATION_MS: "openclaw.tool.duration_ms",
+  SESSION_DURATION_MS: "openclaw.session.duration_ms",
+  SESSION_MSG_COUNT: "openclaw.session.message_count",
+  COMPACTION_MSG_AFTER: "openclaw.compaction.messages.after",
+  COMPACTION_TOKENS_AFTER: "openclaw.compaction.tokens.after",
+  COMPACTION_COMPACTED: "openclaw.compaction.compacted_count",
+} as const;
+
+// ─── 常量 ─────────────────────────────────────────────────────────────────
+
+const MAX_CONTENT_LENGTH = 4096;
+const MAX_INDEXED_PROMPT_MESSAGES = 20;
+const MAX_ATTR_CONTENT_LENGTH = 4096;
+const MAX_SPAN_AGE_MS = 300_000;
+export const LOG_PREFIX = "[openclaw-tencent-cls-plugin]";
+
+// ─── 插件配置类型 ─────────────────────────────────────────────────────────
+
+export interface TencentClsPluginConfig {
+  topicId: string;
+  endpoint: string;
+  secretId: string;
+  secretKey: string;
+  token?: string;
+}
+
+// ─── 工具函数 ─────────────────────────────────────────────────────────────
+
+function truncate(s: string | undefined | null, maxLen = MAX_CONTENT_LENGTH): string {
+  if (!s) return "";
+  if (s.length <= maxLen) return s;
+  return s.slice(0, maxLen) + `... [truncated, total ${s.length} chars]`;
+}
+
+function ensureJson(s: string): string {
+  try { JSON.parse(s); return s; } catch { return JSON.stringify(s); }
+}
+
+function truncateJson(jsonStr: string, maxLen: number): string {
+  if (jsonStr.length <= maxLen) return jsonStr;
+  try {
+    const data = JSON.parse(jsonStr);
+    if (Array.isArray(data)) {
+      const perItem = Math.max(200, Math.floor((maxLen - 100) / Math.max(data.length, 1)));
+      const trimmed = data.map((item: any) => {
+        if (item && typeof item === "object" && typeof item.content === "string") {
+          return { ...item, content: truncate(item.content, perItem) };
+        }
+        return item;
+      });
+      let result = JSON.stringify(trimmed);
+      if (result.length <= maxLen) return result;
+      const keep = Math.max(2, Math.min(trimmed.length, 5));
+      const sliced = trimmed.slice(-keep);
+      result = JSON.stringify([
+        { role: "system", content: `[${trimmed.length - keep} earlier messages omitted]` },
+        ...sliced,
+      ]);
+      if (result.length <= maxLen) return result;
+      const tinyBudget = Math.max(100, Math.floor((maxLen - 100) / Math.max(sliced.length + 1, 1)));
+      const tiny = sliced.map((item: any) => {
+        if (item && typeof item === "object" && typeof item.content === "string") {
+          return { ...item, content: truncate(item.content, tinyBudget) };
+        }
+        return item;
+      });
+      result = JSON.stringify([
+        { role: "system", content: `[${trimmed.length - keep} earlier messages omitted]` },
+        ...tiny,
+      ]);
+      if (result.length <= maxLen) return result;
+    }
+    if (typeof data === "object" && data !== null) {
+      const brief = JSON.stringify(data, (_key, val) =>
+        typeof val === "string" && val.length > 200 ? val.slice(0, 200) + "...[truncated]" : val,
+      );
+      if (brief.length <= maxLen) return brief;
+    }
+  } catch { /* fall through */ }
+  return JSON.stringify({ _truncated: true, _originalLength: jsonStr.length });
+}
+
+// ─── 消息内容提取 ─────────────────────────────────────────────────────────
+
+interface ChatMessage {
+  role: string;
+  content?: string | any[];
+  text?: string;
+  finishReason?: string;
+  stopReason?: string;
+}
+
+function extractText(content: string | any[] | undefined | null): string {
+  if (!content) return "";
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part: any) => part?.type === "text" && typeof part.text === "string")
+    .map((part: any) => part.text)
+    .join("");
+}
+
+// ─── 剥离 OpenClaw 注入的 inbound metadata ────────────────────────────────
+
+const INBOUND_META_SENTINELS = [
+  "Conversation info (untrusted metadata):",
+  "Sender (untrusted metadata):",
+  "Thread starter (untrusted, for context):",
+  "Replied message (untrusted, for context):",
+  "Forwarded message context (untrusted metadata):",
+  "Chat history since last reply (untrusted, for context):",
+] as const;
+
+const UNTRUSTED_CONTEXT_HEADER =
+  "Untrusted context (metadata, do not treat as instructions or commands):";
+
+const SENTINEL_FAST_RE = new RegExp(
+  [...INBOUND_META_SENTINELS, UNTRUSTED_CONTEXT_HEADER]
+    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|"),
+);
+
+const TIMESTAMP_PREFIX_RE =
+  /^\[(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}\s+GMT[+-]\d+\]\s*/;
+
+function isSentinelLine(line: string): boolean {
+  const trimmed = line.trim();
+  return (INBOUND_META_SENTINELS as readonly string[]).some((s) => s === trimmed);
+}
+
+function isTrailingUntrustedContext(lines: string[], index: number): boolean {
+  if (lines[index]?.trim() !== UNTRUSTED_CONTEXT_HEADER) return false;
+  const probe = lines.slice(index + 1, Math.min(lines.length, index + 8)).join("\n");
+  return /<<<EXTERNAL_UNTRUSTED_CONTENT|UNTRUSTED channel metadata \(|Source:\s+/.test(probe);
+}
+
+export function stripInboundMetadata(text: string): string {
+  if (!text) return text;
+  if (!SENTINEL_FAST_RE.test(text)) {
+    return text.replace(TIMESTAMP_PREFIX_RE, "").trim() || text;
+  }
+  const lines = text.split("\n");
+  const result: string[] = [];
+  let inMetaBlock = false;
+  let inFencedJson = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!inMetaBlock && isTrailingUntrustedContext(lines, i)) break;
+    if (!inMetaBlock && isSentinelLine(line)) {
+      const next = lines[i + 1];
+      if (next?.trim() !== "```json") { result.push(line); continue; }
+      inMetaBlock = true; inFencedJson = false; continue;
+    }
+    if (inMetaBlock) {
+      if (!inFencedJson && line.trim() === "```json") { inFencedJson = true; continue; }
+      if (inFencedJson) {
+        if (line.trim() === "```") { inMetaBlock = false; inFencedJson = false; }
+        continue;
+      }
+      if (line.trim() === "") continue;
+      inMetaBlock = false;
+    }
+    result.push(line);
+  }
+  let cleaned = result.join("\n").replace(/^\n+/, "").replace(/\n+$/, "");
+  cleaned = cleaned.replace(TIMESTAMP_PREFIX_RE, "").trim();
+  return cleaned;
+}
+
+function extractToolCallsFromContent(content: any[] | undefined): Array<{
+  id: string; name: string; arguments: string;
+}> {
+  if (!Array.isArray(content)) return [];
+  const calls: Array<{ id: string; name: string; arguments: string }> = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    if (block.type === "toolCall" || block.type === "tool_use") {
+      calls.push({
+        id: block.id ?? `call_${Date.now()}`,
+        name: block.name ?? "unknown",
+        arguments: typeof block.arguments === "string"
+          ? block.arguments
+          : JSON.stringify(block.arguments ?? {}),
+      });
+    }
+  }
+  return calls;
+}
+
+// ─── APM 兼容的索引属性设置 ───────────────────────────────────────────────
+
+function setIndexedPromptAttrs(attrs: Record<string, any>, messages: ChatMessage[]): void {
+  let selected = messages;
+  if (messages.length > MAX_INDEXED_PROMPT_MESSAGES) {
+    selected = [...messages.slice(0, 1), ...messages.slice(-(MAX_INDEXED_PROMPT_MESSAGES - 1))];
+  }
+  for (let i = 0; i < selected.length; i++) {
+    const msg = selected[i];
+    attrs[`gen_ai.prompt.${i}.role`] = msg.role ?? "unknown";
+    const text = extractText(msg.content ?? msg.text);
+    if (text) attrs[`gen_ai.prompt.${i}.content`] = truncate(text, MAX_ATTR_CONTENT_LENGTH);
+  }
+}
+
+function setIndexedCompletionAttrs(
+  attrs: Record<string, any>,
+  messages: Array<ChatMessage & { toolCalls?: Array<{ id: string; name: string; arguments: string }> }>,
+): void {
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    attrs[`gen_ai.completion.${i}.role`] = msg.role ?? "assistant";
+    const text = extractText(msg.content ?? msg.text);
+    if (text) attrs[`gen_ai.completion.${i}.content`] = truncate(text, MAX_ATTR_CONTENT_LENGTH);
+    const finishReason = msg.finishReason ?? msg.stopReason ?? "stop";
+    attrs[`gen_ai.completion.${i}.finish_reason`] = finishReason;
+    const toolCalls = msg.toolCalls ?? extractToolCallsFromContent(msg.content as any[]);
+    if (toolCalls.length > 0) {
+      attrs[`gen_ai.completion.${i}.finish_reason`] = "tool_calls";
+      for (let j = 0; j < toolCalls.length; j++) {
+        const tc = toolCalls[j];
+        attrs[`gen_ai.completion.${i}.tool_calls.${j}.id`] = tc.id;
+        attrs[`gen_ai.completion.${i}.tool_calls.${j}.name`] = tc.name;
+        attrs[`gen_ai.completion.${i}.tool_calls.${j}.arguments`] = truncate(tc.arguments, MAX_ATTR_CONTENT_LENGTH);
+      }
+    }
+  }
+}
+
+interface ToolDefinition { name: string; description?: string; parameters?: any; }
+
+function setIndexedFunctionAttrs(attrs: Record<string, any>, tools: ToolDefinition[]): void {
+  for (let i = 0; i < tools.length; i++) {
+    const tool = tools[i];
+    attrs[`llm.request.functions.${i}.name`] = tool.name;
+    if (tool.description) attrs[`llm.request.functions.${i}.description`] = truncate(tool.description, 1024);
+    if (tool.parameters) {
+      const params = typeof tool.parameters === "string" ? tool.parameters : JSON.stringify(tool.parameters);
+      attrs[`llm.request.functions.${i}.parameters`] = truncate(params, 2048);
+    }
+  }
+}
+
+function setPromptSummary(attrs: Record<string, any>, totalMessages: number, roleCounts: Map<string, number>) {
+  attrs["gen_ai.prompt.num_messages"] = totalMessages;
+  attrs["gen_ai.prompt.role_counts"] = [...roleCounts.entries()].map(([r, c]) => `${r}:${c}`).join(", ");
+}
+
+// ─── 轻量级 Span 实现 ────────────────────────────────────────────────────
+
+type SpanStatusCode = "UNSET" | "OK" | "ERROR";
+interface SpanStatus { code: SpanStatusCode; message?: string; }
+
+function genTraceId(): string {
+  return Array.from({ length: 32 }, () => Math.floor(Math.random() * 16).toString(16)).join("");
+}
+
+function genSpanId(): string {
+  return Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join("");
+}
+
+export class ClsSpan {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId: string | undefined;
+  readonly name: string;
+  readonly startTimeMs: number;
+  private endTimeMs: number | undefined;
+  public status: SpanStatus = { code: "UNSET" };
+  public attrs: Record<string, any> = {};
+  private events: Array<{ name: string; attrs?: Record<string, any>; timeMs: number }> = [];
+  private _ended = false;
+  onEnd?: (span: ClsSpan) => void;
+
+  constructor(name: string, traceId: string, parentSpanId?: string) {
+    this.name = name;
+    this.traceId = traceId;
+    this.spanId = genSpanId();
+    this.parentSpanId = parentSpanId;
+    this.startTimeMs = Date.now();
+  }
+
+  setAttribute(key: string, value: any): this { this.attrs[key] = value; return this; }
+  setAttributes(kv: Record<string, any>): this { Object.assign(this.attrs, kv); return this; }
+  setStatus(status: SpanStatus): this { this.status = status; return this; }
+  addEvent(name: string, attrs?: Record<string, any>): this {
+    this.events.push({ name, attrs, timeMs: Date.now() }); return this;
+  }
+  end(): void {
+    if (this._ended) return;
+    this._ended = true;
+    this.endTimeMs = Date.now();
+    this.onEnd?.(this);
+  }
+  isEnded(): boolean { return this._ended; }
+
+  toRecord(): Record<string, string> {
+    const rec: Record<string, string> = {
+      "trace.id": this.traceId,
+      "span.id": this.spanId,
+      "span.name": this.name,
+      "span.kind": this.attrs["gen_ai.span.kind"] ?? "INTERNAL",
+      "span.status": this.status.code,
+      "span.start_time": new Date(this.startTimeMs).toISOString(),
+      "span.end_time": this.endTimeMs ? new Date(this.endTimeMs).toISOString() : "",
+      "span.duration_ms": String(this.endTimeMs ? this.endTimeMs - this.startTimeMs : 0),
+    };
+    if (this.parentSpanId) rec["span.parent_id"] = this.parentSpanId;
+    if (this.status.message) rec["span.status_message"] = this.status.message;
+    for (const [k, v] of Object.entries(this.attrs)) {
+      if (v === undefined || v === null) continue;
+      rec[k] = typeof v === "string" ? v : String(v);
+    }
+    if (this.events.length > 0) rec["span.events"] = JSON.stringify(this.events);
+    return rec;
+  }
+}
+
+// ─── CLS 发送器 ───────────────────────────────────────────────────────────
+
+export class ClsSender {
+  private producer: Producer;
+  constructor(producer: Producer) { this.producer = producer; }
+
+  async sendSpan(span: ClsSpan): Promise<void> {
+    try {
+      const record = span.toRecord();
+      const logItem = new LogItem();
+      logItem.setTime(Math.floor(span.startTimeMs / 1000));
+      for (const [k, v] of Object.entries(record)) {
+        logItem.pushBack(new Content(k, v));
+      }
+      await this.producer.send(logItem);
+    } catch (_e) { /* 发送失败静默处理 */ }
+  }
+}
+
+// ─── 每会话 Trace 状态 ────────────────────────────────────────────────────
+
+export interface TraceState {
+  traceId: string;
+  rootSpan: ClsSpan;
+  sessionSpan?: ClsSpan;
+  agentSpan?: ClsSpan;
+  modelResolveSpan?: ClsSpan;
+  promptBuildSpan?: ClsSpan;
+  llmSpan?: ClsSpan;
+  llmRound: number;
+  toolSpans: Map<string, ClsSpan>;
+  subagentSpans: Map<string, ClsSpan>;
+  compactionSpan?: ClsSpan;
+  replySpan?: ClsSpan;
+  createdAt: number;
+  messageCount: number;
+  agentInputUserMessage?: string;
+  agentOutputAssistantMessage?: string;
+  agentOutputToolCalls?: Array<{ id: string; name: string; arguments: string }>;
+  agentProvider?: string;
+  agentModel?: string;
+}
+
+// ─── Helper: close all child spans ───────────────────────────────────────
+
+export function endAllChildren(st: TraceState): void {
+  for (const [, span] of st.toolSpans) { span.setStatus({ code: "OK" }); span.end(); }
+  st.toolSpans.clear();
+  for (const [, span] of st.subagentSpans) { span.setStatus({ code: "OK" }); span.end(); }
+  st.subagentSpans.clear();
+  if (st.llmSpan) { st.llmSpan.setStatus({ code: "OK" }); st.llmSpan.end(); st.llmSpan = undefined; }
+  if (st.compactionSpan) { st.compactionSpan.setStatus({ code: "OK" }); st.compactionSpan.end(); st.compactionSpan = undefined; }
+  if (st.modelResolveSpan) { st.modelResolveSpan.setStatus({ code: "OK" }); st.modelResolveSpan.end(); st.modelResolveSpan = undefined; }
+  if (st.promptBuildSpan) { st.promptBuildSpan.setStatus({ code: "OK" }); st.promptBuildSpan.end(); st.promptBuildSpan = undefined; }
+  if (st.replySpan) { st.replySpan.setStatus({ code: "OK" }); st.replySpan.end(); st.replySpan = undefined; }
+  if (st.agentSpan) {
+    try {
+      st.agentSpan.setAttribute("llm.request.type", "chat");
+      if (st.agentInputUserMessage) {
+        setIndexedPromptAttrs(st.agentSpan.attrs, [{ role: "user", content: st.agentInputUserMessage }]);
+      }
+      if (st.agentOutputAssistantMessage || st.agentOutputToolCalls) {
+        const completionMsg: ChatMessage & { toolCalls?: Array<{ id: string; name: string; arguments: string }> } = {
+          role: "assistant",
+          content: st.agentOutputAssistantMessage ?? "",
+          stopReason: st.agentOutputToolCalls ? "tool_calls" : "stop",
+          toolCalls: st.agentOutputToolCalls,
+        };
+        setIndexedCompletionAttrs(st.agentSpan.attrs, [completionMsg]);
+      }
+      if (st.agentProvider) {
+        st.agentSpan.setAttribute(A.GENAI_PROVIDER_NAME, st.agentProvider);
+        st.agentSpan.setAttribute(A.GENAI_SYSTEM, st.agentProvider);
+      }
+      if (st.agentModel) {
+        st.agentSpan.setAttribute(A.GENAI_MODEL_NAME, st.agentModel);
+        st.agentSpan.setAttribute(A.GENAI_REQUEST_MODEL, st.agentModel);
+      }
+    } catch (_) { /* best-effort */ }
+    st.agentSpan.setStatus({ code: "OK" }); st.agentSpan.end(); st.agentSpan = undefined;
+  }
+  if (st.sessionSpan) { st.sessionSpan.setStatus({ code: "OK" }); st.sessionSpan.end(); st.sessionSpan = undefined; }
+}
+
+// ─── 插件核心：创建 CLS 插件实例（service + hook 注册器）────────────────
+
+export interface TencentClsPlugin {
+  /** 注册所有 hook 到 api.on() */
+  registerHooks(api: any): void;
+  /** OpenClawPluginService 对象，用于 api.registerService() */
+  service: {
+    id: string;
+    start(ctx: any): void | Promise<void>;
+    stop(ctx: any): void | Promise<void>;
+  };
+}
+
+export function createTencentClsPlugin(config: TencentClsPluginConfig): TencentClsPlugin {
+  const topicId = config.topicId ?? "";
+  const endpoint = config.endpoint ?? "";
+  const secretId = config.secretId ?? "";
+  const secretKey = config.secretKey ?? "";
+  const token = config.token;
+
+  let sender: ClsSender | null = null;
+  const states = new Map<string, TraceState>();
+  const sessionKeyMap = new Map<string, string>();
+  let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+  // ── Span 工厂 ──────────────────────────────────────────────────────────
+  function makeSpan(name: string, traceId: string, parentSpanId?: string): ClsSpan {
+    const span = new ClsSpan(name, traceId, parentSpanId);
+    span.onEnd = (s) => { sender?.sendSpan(s).catch(() => {}); };
+    return span;
+  }
+
+  // ── Helper: resolve session key ────────────────────────────────────────
+  function resolveKey(hookCtx: any, event?: any): string {
+    if (hookCtx?.sessionKey) {
+      const mapped = sessionKeyMap.get(hookCtx.sessionKey);
+      if (mapped && states.has(mapped)) return mapped;
+      if (states.has(hookCtx.sessionKey)) return hookCtx.sessionKey;
+      if (mapped) return mapped;
+    }
+    const channelId = hookCtx?.channelId ?? "unknown";
+    const convId = hookCtx?.conversationId ?? event?.metadata?.threadId ?? "default";
+    return `${channelId}:${convId}`;
+  }
+
+  function ensureSessionKeyMapping(hookCtx: any, log: any) {
+    if (!hookCtx?.sessionKey) return;
+    if (sessionKeyMap.has(hookCtx.sessionKey)) return;
+    for (const [ck] of states) {
+      if (!ck.includes(":")) continue;
+      sessionKeyMap.set(hookCtx.sessionKey, ck);
+      log.info(`${LOG_PREFIX} Auto-mapped sessionKey=${hookCtx.sessionKey} → compositeKey=${ck}`);
+      return;
+    }
+  }
+
+  function agentOrRoot(st: TraceState): ClsSpan | undefined {
+    return st.agentSpan ?? st.rootSpan;
+  }
+
+  function cleanupState(key: string) {
+    states.delete(key);
+    for (const [sk, ck] of sessionKeyMap) {
+      if (ck === key) sessionKeyMap.delete(sk);
+    }
+  }
+
+  // ── Service ────────────────────────────────────────────────────────────
+  const service = {
+    id: "openclaw-tencent-cls-plugin",
+
+    async start(ctx: any) {
+      const log = ctx.logger;
+      if (!topicId || !endpoint || !secretId || !secretKey) {
+        log.warn(`${LOG_PREFIX} CLS 配置不完整（topicId/endpoint/secretId/secretKey），trace 数据将不会发送`);
+      }
+      const producer = new Producer({
+        topic_id: topicId,
+        endpoint,
+        credential: { secretId, secretKey, token },
+        onSendLogsError: (res: any) => {
+          log.warn(`${LOG_PREFIX} CLS 发送失败: ${JSON.stringify(res)}`);
+        },
+      });
+      sender = new ClsSender(producer);
+      log.info(`${LOG_PREFIX} CLS Producer 已初始化，endpoint=${endpoint} topicId=${topicId}`);
+
+      sweepTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [key, st] of states) {
+          if (now - st.createdAt > MAX_SPAN_AGE_MS) {
+            log.info(`${LOG_PREFIX} Sweeping orphan trace for key=${key}`);
+            endAllChildren(st);
+            st.rootSpan.setStatus({ code: "OK" });
+            st.rootSpan.setAttribute("openclaw.sweep", true);
+            st.rootSpan.end();
+            states.delete(key);
+          }
+        }
+      }, 60_000);
+    },
+
+    async stop(_ctx: any) {
+      if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+      for (const [, st] of states) {
+        endAllChildren(st);
+        st.rootSpan.setStatus({ code: "OK" });
+        st.rootSpan.setAttribute("openclaw.cleanup", true);
+        st.rootSpan.end();
+      }
+      states.clear();
+      sessionKeyMap.clear();
+      sender = null;
+    },
+  };
+
+  // ── Hook 注册器 ────────────────────────────────────────────────────────
+  function registerHooks(api: any) {
+    const log = api.logger;
+
+    // 1. message_received → Root Span
+    api.on("message_received", (event: any, hookCtx: any) => {
+      const channelId = hookCtx?.channelId ?? "unknown";
+      const convId = hookCtx?.conversationId ?? "default";
+      const compositeKey = `${channelId}:${convId}`;
+      log.info(`${LOG_PREFIX} [message_received] key=${compositeKey} from=${event?.from ?? "?"}`);
+      const prev = states.get(compositeKey);
+      if (prev) {
+        endAllChildren(prev);
+        prev.rootSpan.setAttribute("openclaw.message.count", prev.messageCount);
+        prev.rootSpan.setStatus({ code: "OK" });
+        prev.rootSpan.end();
+        states.delete(compositeKey);
+      }
+      const traceId = genTraceId();
+      const rootSpan = makeSpan(SPAN.MESSAGE, traceId);
+      try {
+        const userMsg = event?.content;
+        if (userMsg) {
+          const rawStr = typeof userMsg === "string" ? userMsg : extractText(userMsg);
+          rootSpan.setAttribute("openclaw.user.message", truncate(rawStr, MAX_ATTR_CONTENT_LENGTH));
+        }
+      } catch (_) { /* best-effort */ }
+      states.set(compositeKey, {
+        traceId, rootSpan, llmRound: 0,
+        toolSpans: new Map(), subagentSpans: new Map(),
+        createdAt: Date.now(), messageCount: 1,
+      });
+      log.info(`${LOG_PREFIX} Started root span: traceId=${rootSpan.traceId} key=${compositeKey}`);
+    }, { priority: -100 });
+
+    // 2. session_start → Session Span
+    api.on("session_start", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [session_start] key=${key} hasState=${!!st}`);
+      if (!st) return;
+      if (hookCtx?.sessionKey && hookCtx.sessionKey !== key) sessionKeyMap.set(hookCtx.sessionKey, key);
+      st.sessionSpan = makeSpan(SPAN.SESSION, st.traceId, st.rootSpan.spanId);
+    }, { priority: -100 });
+
+    // 3. before_model_resolve → Model Resolve Span + Agent Span
+    api.on("before_model_resolve", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [before_model_resolve] key=${key} hasState=${!!st}`);
+      if (!st) return;
+      if (!st.agentSpan) st.agentSpan = makeSpan(SPAN.AGENT_PROCESSING, st.traceId, st.rootSpan.spanId);
+      st.modelResolveSpan = makeSpan(SPAN.MODEL_RESOLVE, st.traceId, st.agentSpan.spanId);
+    }, { priority: -100 });
+
+    // 4. before_prompt_build → Prompt Build Span
+    api.on("before_prompt_build", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      let st = states.get(key);
+      log.info(`${LOG_PREFIX} [before_prompt_build] key=${key} hasState=${!!st}`);
+      if (!st) {
+        const traceId = genTraceId();
+        const rootSpan = makeSpan(SPAN.MESSAGE, traceId);
+        st = { traceId, rootSpan, llmRound: 0, toolSpans: new Map(), subagentSpans: new Map(), createdAt: Date.now(), messageCount: 1 };
+        states.set(key, st);
+        if (hookCtx?.sessionKey && hookCtx.sessionKey !== key) sessionKeyMap.set(hookCtx.sessionKey, key);
+      }
+      if (st.modelResolveSpan) { st.modelResolveSpan.setStatus({ code: "OK" }); st.modelResolveSpan.end(); st.modelResolveSpan = undefined; }
+      st.promptBuildSpan = makeSpan(SPAN.PROMPT_BUILD, st.traceId, agentOrRoot(st)?.spanId);
+    }, { priority: -100 });
+
+    // 5. before_agent_start → Fallback agent span
+    api.on("before_agent_start", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      let st = states.get(key);
+      log.info(`${LOG_PREFIX} [before_agent_start] key=${key} hasState=${!!st}`);
+      if (!st) {
+        const traceId = genTraceId();
+        const rootSpan = makeSpan(SPAN.MESSAGE, traceId);
+        st = { traceId, rootSpan, llmRound: 0, toolSpans: new Map(), subagentSpans: new Map(), createdAt: Date.now(), messageCount: 1 };
+        states.set(key, st);
+        if (hookCtx?.sessionKey && hookCtx.sessionKey !== key) sessionKeyMap.set(hookCtx.sessionKey, key);
+      }
+      if (!st.agentSpan) st.agentSpan = makeSpan(SPAN.AGENT_PROCESSING, st.traceId, st.rootSpan.spanId);
+    }, { priority: -100 });
+
+    // 6. llm_input → LLM Call Span
+    api.on("llm_input", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [llm_input] key=${key} provider=${event?.provider ?? "?"} model=${event?.model ?? "?"} hasState=${!!st}`);
+      if (!st) return;
+      if (st.promptBuildSpan) { st.promptBuildSpan.setStatus({ code: "OK" }); st.promptBuildSpan.end(); st.promptBuildSpan = undefined; }
+      if (st.modelResolveSpan) { st.modelResolveSpan.setStatus({ code: "OK" }); st.modelResolveSpan.end(); st.modelResolveSpan = undefined; }
+      if (st.llmSpan) { st.llmSpan.setStatus({ code: "OK" }); st.llmSpan.end(); }
+      st.llmRound += 1;
+      const provider = event?.provider ?? "unknown";
+      const model = event?.model ?? "unknown";
+      if (st.llmRound === 1) {
+        st.agentProvider = provider;
+        st.agentModel = model;
+        if (event?.prompt) {
+          st.agentInputUserMessage = stripInboundMetadata(
+            typeof event.prompt === "string" ? event.prompt : extractText(event.prompt),
+          );
+        }
+      }
+      st.llmSpan = makeSpan(`chat ${model}`, st.traceId, agentOrRoot(st)?.spanId);
+      try {
+        const promptMessages: ChatMessage[] = [];
+        if (event?.systemPrompt) promptMessages.push({ role: "system", content: event.systemPrompt });
+        if (Array.isArray(event?.historyMessages)) {
+          for (const msg of event.historyMessages) {
+            const role = msg?.role ?? "unknown";
+            let content = msg?.content ?? msg?.text ?? "";
+            if (content) {
+              if (role === "user") {
+                const textContent = typeof content === "string" ? content : extractText(content);
+                content = stripInboundMetadata(textContent);
+              }
+              promptMessages.push({ role, content });
+            }
+          }
+        }
+        if (event?.prompt) {
+          const cleanedPrompt = stripInboundMetadata(
+            typeof event.prompt === "string" ? event.prompt : extractText(event.prompt),
+          );
+          promptMessages.push({ role: "user", content: cleanedPrompt });
+        }
+        if (promptMessages.length > 0) {
+          st.llmSpan.setAttribute(A.LLM_REQUEST_TYPE, "chat");
+          setIndexedPromptAttrs(st.llmSpan.attrs, promptMessages);
+          try {
+            const entityInput = JSON.stringify(promptMessages.map((m) => ({
+              role: m.role,
+              content: truncate(
+                m.role === "user"
+                  ? stripInboundMetadata(extractText(m.content ?? m.text))
+                  : extractText(m.content ?? m.text),
+                MAX_ATTR_CONTENT_LENGTH,
+              ),
+            })));
+            st.llmSpan.setAttribute(A.TRACELOOP_ENTITY_INPUT, truncateJson(entityInput, MAX_ATTR_CONTENT_LENGTH));
+          } catch (_) { /* best-effort */ }
+          const roleCounts = new Map<string, number>();
+          for (const m of promptMessages) {
+            const r = typeof m.role === "string" ? m.role : "unknown";
+            roleCounts.set(r, (roleCounts.get(r) ?? 0) + 1);
+          }
+          setPromptSummary(st.llmSpan.attrs, promptMessages.length, roleCounts);
+        }
+        if (Array.isArray(event?.tools)) {
+          const toolDefs: ToolDefinition[] = event.tools.map((t: any) => ({
+            name: t.name ?? "unknown", description: t.description ?? "", parameters: t.parameters ?? t.inputSchema ?? {},
+          }));
+          setIndexedFunctionAttrs(st.llmSpan.attrs, toolDefs);
+        }
+      } catch (e) {
+        log.info(`${LOG_PREFIX} [llm_input] Error setting prompt attributes: ${e}`);
+      }
+    }, { priority: -100 });
+
+    // 7. llm_output → End LLM Call Span
+    api.on("llm_output", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      if (!st?.llmSpan) { log.info(`${LOG_PREFIX} [llm_output] key=${key} — no LLM span to end`); return; }
+      const usage = event?.usage ?? {};
+      const inputTokens = usage.input ?? usage.promptTokens ?? 0;
+      const outputTokens = usage.output ?? usage.completionTokens ?? 0;
+      const totalTokens = usage.total ?? (inputTokens + outputTokens);
+      const cacheRead = usage.cacheRead ?? 0;
+      const cacheWrite = usage.cacheWrite ?? usage.cacheCreation ?? 0;
+      st.llmSpan.setAttributes({
+        [A.GENAI_USAGE_INPUT_TOKENS]: inputTokens,
+        [A.GENAI_USAGE_OUTPUT_TOKENS]: outputTokens,
+        [A.GENAI_USAGE_CACHE_READ_INPUT]: cacheRead,
+        [A.GENAI_USAGE_CACHE_CREATION_INPUT]: cacheWrite,
+        [A.GENAI_USAGE_PROMPT_TOKENS]: inputTokens,
+        [A.GENAI_USAGE_COMPLETION_TOKENS]: outputTokens,
+        [A.GENAI_USAGE_TOTAL_TOKENS]: totalTokens,
+        [A.GENAI_RESPONSE_MODEL]: event?.model ?? "unknown",
+      });
+      try {
+        const completionMessages: Array<ChatMessage & { toolCalls?: Array<{ id: string; name: string; arguments: string }> }> = [];
+        if (Array.isArray(event?.assistantTexts) && event.assistantTexts.length > 0) {
+          const fullText = event.assistantTexts.join("");
+          const toolCalls = extractToolCallsFromContent(event?.lastAssistant?.content);
+          completionMessages.push({ role: "assistant", content: fullText, stopReason: event?.lastAssistant?.stopReason ?? "stop", toolCalls: toolCalls.length > 0 ? toolCalls : undefined });
+        } else if (event?.lastAssistant) {
+          const la = event.lastAssistant;
+          const text = extractText(la.content ?? la.text);
+          const toolCalls = extractToolCallsFromContent(la.content);
+          completionMessages.push({ role: "assistant", content: text, stopReason: la.stopReason ?? "stop", toolCalls: toolCalls.length > 0 ? toolCalls : undefined });
+        }
+        if (completionMessages.length > 0) {
+          setIndexedCompletionAttrs(st.llmSpan.attrs, completionMessages);
+          try {
+            const entityOutput = JSON.stringify(completionMessages.map((m) => ({
+              role: m.role ?? "assistant",
+              content: truncate(typeof m.content === "string" ? m.content : extractText(m.content), MAX_ATTR_CONTENT_LENGTH),
+              ...(m.toolCalls && m.toolCalls.length > 0 ? { tool_calls: m.toolCalls } : {}),
+            })));
+            st.llmSpan.setAttribute(A.TRACELOOP_ENTITY_OUTPUT, truncateJson(entityOutput, MAX_ATTR_CONTENT_LENGTH));
+          } catch (_) { /* best-effort */ }
+          const lastContent = typeof completionMessages[0]?.content === "string" ? completionMessages[0].content : extractText(completionMessages[0]?.content);
+          if (lastContent) st.agentOutputAssistantMessage = lastContent;
+          if (completionMessages[0]?.toolCalls) st.agentOutputToolCalls = completionMessages[0].toolCalls;
+        }
+      } catch (e) {
+        log.info(`${LOG_PREFIX} [llm_output] Error setting completion attributes: ${e}`);
+      }
+      st.llmSpan.setStatus({ code: "OK" });
+      st.llmSpan.end();
+      log.info(`${LOG_PREFIX} [llm_output] Ended LLM span for key=${key} tokens.in=${inputTokens} tokens.out=${outputTokens}`);
+      st.llmSpan = undefined;
+    }, { priority: -100 });
+
+    // 8. before_tool_call → Tool Span
+    api.on("before_tool_call", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      const toolName = event?.toolName ?? hookCtx?.toolName ?? "unknown";
+      const toolCallId = hookCtx?.toolCallId ?? event?.toolCallId ?? `tool-${Date.now()}`;
+      log.info(`${LOG_PREFIX} [before_tool_call] key=${key} tool=${toolName} callId=${toolCallId} hasState=${!!st}`);
+      if (!st) return;
+      const span = makeSpan(`${SPAN.TOOL}.${toolName}`, st.traceId, st.llmSpan?.spanId);
+      try {
+        const toolInput = event?.arguments ?? event?.input ?? event?.params;
+        if (toolInput) {
+          const inputStr = typeof toolInput === "string" ? ensureJson(toolInput) : JSON.stringify(toolInput);
+          span.setAttribute(A.TRACELOOP_ENTITY_INPUT, truncateJson(inputStr, MAX_ATTR_CONTENT_LENGTH));
+        }
+      } catch (_) { /* best-effort */ }
+      st.toolSpans.set(toolCallId, span);
+    }, { priority: -100 });
+
+    // 9. after_tool_call → End Tool Span
+    api.on("after_tool_call", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      if (!st) return;
+      const toolCallId = hookCtx?.toolCallId ?? event?.toolCallId ?? "";
+      const span = st.toolSpans.get(toolCallId);
+      if (!span) { log.info(`${LOG_PREFIX} [after_tool_call] key=${key} callId=${toolCallId} — no matching span`); return; }
+      if (event?.durationMs != null) span.setAttribute(A.TOOL_DURATION_MS, event.durationMs);
+      try {
+        const toolOutput = event?.result ?? event?.output ?? event?.response;
+        if (toolOutput) {
+          const outputStr = typeof toolOutput === "string" ? ensureJson(toolOutput) : JSON.stringify(toolOutput);
+          span.setAttribute(A.TRACELOOP_ENTITY_OUTPUT, truncateJson(outputStr, MAX_ATTR_CONTENT_LENGTH));
+        }
+      } catch (_) { /* best-effort */ }
+      if (event?.error) { span.setStatus({ code: "ERROR", message: String(event.error) }); } else { span.setStatus({ code: "OK" }); }
+      span.end();
+      st.toolSpans.delete(toolCallId);
+      log.info(`${LOG_PREFIX} [after_tool_call] Ended tool span key=${key} tool=${event?.toolName ?? "?"} callId=${toolCallId}`);
+    }, { priority: -100 });
+
+    // 10. before_compaction → Compaction Span
+    api.on("before_compaction", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [before_compaction] key=${key} hasState=${!!st}`);
+      if (!st) return;
+      st.compactionSpan = makeSpan(SPAN.COMPACTION, st.traceId, agentOrRoot(st)?.spanId);
+    }, { priority: -100 });
+
+    // 11. after_compaction → End Compaction Span
+    api.on("after_compaction", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [after_compaction] key=${key} hasState=${!!st}`);
+      if (!st?.compactionSpan) return;
+      st.compactionSpan.setAttributes({
+        [A.COMPACTION_MSG_AFTER]: event?.messageCount ?? -1,
+        [A.COMPACTION_TOKENS_AFTER]: event?.tokenCount ?? -1,
+        [A.COMPACTION_COMPACTED]: event?.compactedCount ?? 0,
+      });
+      st.compactionSpan.setStatus({ code: "OK" });
+      st.compactionSpan.end();
+      st.compactionSpan = undefined;
+    }, { priority: -100 });
+
+    // 12. subagent_spawning → Log
+    api.on("subagent_spawning", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      log.info(`${LOG_PREFIX} [subagent_spawning] key=${key} childSessionKey=${event?.sessionKey ?? "?"}`);
+    }, { priority: -100 });
+
+    // 13. subagent_spawned → Subagent Span
+    api.on("subagent_spawned", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const parentKey = resolveKey(hookCtx, event);
+      const st = states.get(parentKey);
+      if (!st) return;
+      const childKey = event?.sessionKey ?? event?.childSessionKey ?? "unknown-child";
+      const span = makeSpan(SPAN.SUBAGENT, st.traceId, st.agentSpan?.spanId);
+      st.subagentSpans.set(childKey, span);
+      log.info(`${LOG_PREFIX} [subagent_spawned] parent=${parentKey} child=${childKey}`);
+    }, { priority: -100 });
+
+    // 14. subagent_ended → End Subagent Span
+    api.on("subagent_ended", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const parentKey = resolveKey(hookCtx, event);
+      const st = states.get(parentKey);
+      if (!st) return;
+      const childKey = event?.sessionKey ?? event?.childSessionKey ?? "unknown-child";
+      const span = st.subagentSpans.get(childKey);
+      if (!span) return;
+      span.setStatus({ code: "OK" }); span.end(); st.subagentSpans.delete(childKey);
+      log.info(`${LOG_PREFIX} [subagent_ended] parent=${parentKey} child=${childKey}`);
+    }, { priority: -100 });
+
+    // 15. message_sending → Reply Span
+    api.on("message_sending", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [message_sending] key=${key} hasState=${!!st}`);
+      if (!st) return;
+      st.replySpan = makeSpan(SPAN.REPLY, st.traceId, st.rootSpan.spanId);
+    }, { priority: -100 });
+
+    // 16. message_sent → End Reply Span + Root Span
+    api.on("message_sent", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [message_sent] key=${key} hasState=${!!st}`);
+      if (!st) return;
+      if (st.replySpan) {
+        st.replySpan.setAttributes({ [A.MESSAGE_TO]: event?.to ?? "", [A.MESSAGE_SUCCESS]: event?.success ?? true });
+        if (event?.error) { st.replySpan.setStatus({ code: "ERROR", message: String(event.error) }); } else { st.replySpan.setStatus({ code: "OK" }); }
+        st.replySpan.end(); st.replySpan = undefined;
+      }
+      endAllChildren(st);
+      st.rootSpan.setAttribute("openclaw.message.count", st.messageCount);
+      st.rootSpan.setAttribute("openclaw.ended_by", "message_sent");
+      try {
+        if (st.agentOutputAssistantMessage) {
+          st.rootSpan.setAttribute("openclaw.assistant.reply", truncate(st.agentOutputAssistantMessage, MAX_ATTR_CONTENT_LENGTH));
+        }
+      } catch (_) { /* best-effort */ }
+      st.rootSpan.setStatus({ code: "OK" }); st.rootSpan.end();
+      log.info(`${LOG_PREFIX} [message_sent] Completed trace traceId=${st.rootSpan.traceId} key=${key}`);
+      cleanupState(key);
+    }, { priority: -100 });
+
+    // 17. session_end → End Session + Root
+    api.on("session_end", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [session_end] key=${key} hasState=${!!st}`);
+      if (!st) return;
+      if (st.sessionSpan) {
+        if (event?.durationMs != null) st.sessionSpan.setAttribute(A.SESSION_DURATION_MS, event.durationMs);
+        if (event?.messageCount != null) st.sessionSpan.setAttribute(A.SESSION_MSG_COUNT, event.messageCount);
+        st.sessionSpan.setStatus({ code: "OK" }); st.sessionSpan.end(); st.sessionSpan = undefined;
+      }
+      endAllChildren(st);
+      st.rootSpan.setAttribute("openclaw.message.count", st.messageCount);
+      st.rootSpan.setAttribute("openclaw.ended_by", "session_end");
+      if (event?.durationMs != null) st.rootSpan.setAttribute(A.SESSION_DURATION_MS, event.durationMs);
+      try {
+        if (st.agentOutputAssistantMessage) {
+          st.rootSpan.setAttribute("openclaw.assistant.reply", truncate(st.agentOutputAssistantMessage, MAX_ATTR_CONTENT_LENGTH));
+        }
+      } catch (_) { /* best-effort */ }
+      st.rootSpan.setStatus({ code: "OK" }); st.rootSpan.end();
+      log.info(`${LOG_PREFIX} [session_end] Completed trace traceId=${st.rootSpan.traceId} key=${key}`);
+      cleanupState(key);
+    }, { priority: -100 });
+
+    // 18. agent_end → Fallback (delayed 2s)
+    api.on("agent_end", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [agent_end] key=${key} hasState=${!!st}`);
+      if (!st) return;
+      setTimeout(() => {
+        const currentSt = states.get(key);
+        if (!currentSt) { log.info(`${LOG_PREFIX} [agent_end/delayed] key=${key} already cleaned up`); return; }
+        endAllChildren(currentSt);
+        currentSt.rootSpan.setAttribute("openclaw.message.count", currentSt.messageCount);
+        currentSt.rootSpan.setAttribute("openclaw.ended_by", "agent_end");
+        try {
+          if (currentSt.agentOutputAssistantMessage) {
+            currentSt.rootSpan.setAttribute("openclaw.assistant.reply", truncate(currentSt.agentOutputAssistantMessage, MAX_ATTR_CONTENT_LENGTH));
+          }
+        } catch (_) { /* best-effort */ }
+        currentSt.rootSpan.setStatus({ code: "OK" }); currentSt.rootSpan.end();
+        log.info(`${LOG_PREFIX} [agent_end/delayed] Completed trace traceId=${currentSt.rootSpan.traceId} key=${key}`);
+        cleanupState(key);
+      }, 2000);
+    }, { priority: -100 });
+
+    // 19. before_reset → Add event to root span
+    api.on("before_reset", (event: any, hookCtx: any) => {
+      ensureSessionKeyMapping(hookCtx, log);
+      const key = resolveKey(hookCtx, event);
+      const st = states.get(key);
+      log.info(`${LOG_PREFIX} [before_reset] key=${key} hasState=${!!st}`);
+      if (!st) return;
+      st.rootSpan.addEvent("session.reset", {
+        [A.SESSION_KEY]: key,
+        "openclaw.reset.reason": event?.reason ?? "user_request",
+      });
+    }, { priority: -100 });
+
+    log.info(`${LOG_PREFIX} Registered 19 hook handlers.`);
+  }
+
+  return { service, registerHooks };
+}