coze_lab 0.1.4 → 0.1.6

package/README.md

@@ -1,4 +1,4 @@
-# @cozeloop/onboard
+# coze_lab
 
 Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to CozeLoop.
 
@@ -6,13 +6,13 @@ Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to Coz
 
 ```bash
 # First-time setup — triggers browser OAuth authorization
-npx @cozeloop/onboard --agent=<type>
+npx coze_lab --agent=<type>
 
 # Auth-only commands (no agent configuration)
-npx @cozeloop/onboard --login      # Device Code login only
-npx @cozeloop/onboard --status     # Show current authorization status
-npx @cozeloop/onboard --refresh    # Force-refresh the access token
-npx @cozeloop/onboard --logout     # Clear cached credentials
+npx coze_lab --login      # Device Code login only
+npx coze_lab --status     # Show current authorization status
+npx coze_lab --refresh    # Force-refresh the access token
+npx coze_lab --logout     # Clear cached credentials
 ```
 
 ### Parameters
@@ -62,7 +62,7 @@ OAuth tokens are stored in `~/.cozeloop/credentials.json` (mode 600).
 
 This means traces continue to upload without interruption even across token expiry, as long as the refresh token is still valid.
 
-**For OpenClaw**, the token is read from `openclaw.json` at startup. Re-run `npx @cozeloop/onboard --agent=openclaw` to refresh it if OpenClaw reports auth errors.
+**For OpenClaw**, the token is read from `openclaw.json` at startup. Re-run `npx coze_lab --agent=openclaw` to refresh it if OpenClaw reports auth errors.
 
 ## Supported versions
 

package/index.js

@@ -4,13 +4,41 @@
 // ─── 0. Constants ─────────────────────────────────────────────────────────────
 const CLIENT_ID   = '46371084383473718052118955183420.app.coze';
 const WORKSPACE_ID = '7644910356078837760';
-// TEMP(test): 临时写死 token，跳过 OAuth。测试结束后请删除并恢复 getValidToken() 流程。
-const HARDCODED_TOKEN = 'sat_KwzIM1cOhtgrKUAbxCbPTjmwxEktM61BVtkekkLD6DZldTv6keCtbzJHOzWaFynu';
+// PPE 泳道：所有 cozeloop 上报 / OAuth 请求都带这两个 header（SDK 读 x_tt_env/x_use_ppe 环境变量自动注入）。
+const PPE_TT_ENV  = 'ppe_cozelab';
+const PPE_USE_PPE = '1';
 const COZE_API    = 'https://api.coze.cn';
 const CREDS_PATH  = require('path').join(require('os').homedir(), '.cozeloop', 'credentials.json');
 // Refresh when less than 10 minutes remain
 const REFRESH_THRESHOLD_MS = 10 * 60 * 1000;
 
+// ─── 1. Cloud structured output ──────────────────────────────────────────────
+// 云端（--cloud）模式：在 stdout 输出一行机器可读结果 COZE_LAB_RESULT={...}，
+// 供管理后台解析判定（inject/verify/logid/message），不依赖中文文案。
+let CLOUD_MODE = false;
+const cloudResult = { inject: 'skip', verify: 'skip', logid: '', message: '' };
+
+// errorBox 在云端模式下抛此异常（而非 process.exit），由 main 外层统一收尾。
+class CloudAbort extends Error {}
+
+// 从 onboard 失败输出 / verify response body 中提取 server logid。
+// 兼容两种形态：JSON 里的 "logid":"xxx" / detail.logid，以及裸 logid=xxx。
+function extractLogid(text) {
+  if (!text) return '';
+  let m = text.match(/"logid"\s*:\s*"([a-zA-Z0-9]+)"/);
+  if (m) return m[1];
+  m = text.match(/logid[=:\s]+([a-zA-Z0-9]+)/i);
+  return m ? m[1] : '';
+}
+
+// 输出结构化结果行（仅云端模式）。
+function emitCloudResult() {
+  if (!CLOUD_MODE) return;
+  // message 压成单行，避免破坏 COZE_LAB_RESULT 单行约定。
+  const safe = { ...cloudResult, message: String(cloudResult.message || '').replace(/\s+/g, ' ').slice(0, 500) };
+  console.log('COZE_LAB_RESULT=' + JSON.stringify(safe));
+}
+
 // ─── 1. Color helpers ────────────────────────────────────────────────────────
 const C = {
   reset:  '\x1b[0m',
@@ -40,6 +68,10 @@ function box(lines, color) {
 
 function errorBox(lines) {
   box(lines, C.red);
+  // 云端模式下不直接退出，改抛异常，让 main 外层统一输出 COZE_LAB_RESULT 结构化结果。
+  if (CLOUD_MODE) {
+    throw new CloudAbort(lines.join(' '));
+  }
   process.exit(1);
 }
 
@@ -3457,7 +3489,7 @@ async function _refreshToken(refreshTok) {
         const body = JSON.stringify({ grant_type: "refresh_token", client_id: _CLIENT_ID, refresh_token: refreshTok });
         const req = https.request(\`\${_COZE_API}/api/permission/oauth2/token\`, {
             method: "POST",
-            headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) },
+            headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body), "x-tt-env": "ppe_cozelab", "x-use-ppe": "1" },
         }, (res) => {
             let buf = "";
             res.on("data", c => buf += c);
@@ -3591,6 +3623,8 @@ export class CozeloopExporter {
             headers: {
                 "Authorization": authorization,
                 "cozeloop-workspace-id": workspaceId,
+                "x-tt-env": "ppe_cozelab",
+                "x-use-ppe": "1",
             },
         });
         this.provider = new BasicTracerProvider({ resource });
@@ -4111,6 +4145,8 @@ function parseArgs() {
     if (arg === '--login')   { args['login']   = true; continue; }
     if (arg === '--status')  { args['status']  = true; continue; }
     if (arg === '--refresh') { args['refresh'] = true; continue; }
+    if (arg === '--verify')  { args['verify']  = true; continue; }
+    if (arg === '--cloud')   { args['cloud']   = true; continue; }
     const m = arg.match(/^--([^=]+)=(.+)$/);
     if (m) args[m[1]] = m[2];
   }
@@ -4119,26 +4155,72 @@ function parseArgs() {
 
 const VALID_AGENTS = ['claude-code', 'codex', 'openclaw'];
 
+// resolveAgent 读 ~/.coze/agents/<agentId>/config.json，返回 { framework, workspace, agentId, root }。
+// 目录或 config 不存在、framework 非法时直接报错退出。
+function resolveAgent(agentId) {
+  const root = path.join(os.homedir(), '.coze', 'agents', agentId);
+  const configPath = path.join(root, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    errorBox([
+      `ERROR: agent "${agentId}" 不存在`,
+      '',
+      `未找到 ${configPath}`,
+      '请确认 agentId 正确，或先用 coze-bridge 创建该 agent。',
+    ]);
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    errorBox([`ERROR: 解析 ${configPath} 失败`, '', e.message]);
+  }
+  const framework = cfg.framework;
+  if (!VALID_AGENTS.includes(framework)) {
+    errorBox([
+      `ERROR: agent "${agentId}" 的 framework="${framework}" 不受支持`,
+      '',
+      `支持的类型: ${VALID_AGENTS.join(', ')}`,
+    ]);
+  }
+  return { framework, workspace: cfg.workspace || '', agentId, root };
+}
+
 function validateArgs(args) {
   if (args['logout'])  return { logout:  true };
   if (args['login'])   return { login:   true };
   if (args['status'])  return { status:  true };
   if (args['refresh']) return { refresh: true };
+  if (args['verify'])  return { verify:  true, pairCode: args['pair-code'] };
+
+  // 优先 --agent-id：读 ~/.coze/agents/<id>/config.json 的 framework 自动路由。
+  if (args['agent-id']) {
+    const resolved = resolveAgent(args['agent-id']);
+    return {
+      agent: resolved.framework,
+      agentId: resolved.agentId,
+      workspace: resolved.workspace,
+      agentRoot: resolved.root,
+      'codex-home': args['codex-home'],
+      pairCode: args['pair-code'],
+      cloud: !!args['cloud'],
+    };
+  }
 
   if (!args['agent']) {
     errorBox([
-      'ERROR: --agent is required',
+      'ERROR: --agent 或 --agent-id 至少提供一个',
       '',
       'Usage:',
-      '  --agent=claude-code',
-      '  --agent=codex',
-      '  --agent=openclaw',
+      '  --agent=claude-code | codex | openclaw   (全局配置)',
+      '  --agent-id=<id>                          (按 ~/.coze/agents/<id> 的 framework 自动路由)',
       '',
       'Other commands:',
       '  --status   Show authorization status',
       '  --login    Login (Device Code flow)',
       '  --refresh  Force refresh access token',
       '  --logout   Clear cached credentials',
+      '  --verify   Send a test trace to verify the reporting pipeline',
+      '             可带 --pair-code=<值> 写入 trace metadata（缺省自动生成），供查询方回查',
     ]);
   }
   if (!VALID_AGENTS.includes(args['agent'])) {
@@ -4151,7 +4233,7 @@ function validateArgs(args) {
       '  --agent=openclaw',
     ]);
   }
-  return { agent: args['agent'] };
+  return { agent: args['agent'], 'codex-home': args['codex-home'], pairCode: args['pair-code'], cloud: !!args['cloud'] };
 }
 
 // ─── 4. Agent detection ──────────────────────────────────────────────────────
@@ -4297,7 +4379,7 @@ function checkVersionWhitelist(agent, version) {
     'Trace reporting may not work correctly.',
     'Please upgrade and re-run:',
     `  ${UPGRADE_CMD[agent]}`,
-    `  npx @cozeloop/onboard --agent=${agent} ...`,
+    `  npx coze_lab --agent=${agent} ...`,
   ]);
 }
 
@@ -4339,22 +4421,33 @@ function mergeJson(filepath, mergeFn) {
   return mergeFn(existing);
 }
 
-function writeClaudeCodeHook(patToken, workspaceId, pythonCmd) {
+// writeClaudeCodeHook 配置 Claude Code 的 hook。
+// configBaseDir 缺省 process.cwd()（全局/项目级）；传入 agent 的 workspace 则 per-agent：
+// settings.json + 凭证写进 <configBaseDir>/.claude，仅该 agent（以此为 cwd 启动）生效。
+// cloud=true 时不把明文 token 写进 settings.local.json —— 云端 hook 运行时直接读
+// 环境变量 COZE_API_TOKEN（见 scripts/claude-code/cozeloop_hook.py 的 get_fresh_token）。
+function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cloud) {
   const hooksDir    = path.join(os.homedir(), '.claude', 'hooks');
   const hookScript  = path.join(hooksDir, 'cozeloop_hook.py');
-  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
-  const localSettingsPath = path.join(process.cwd(), '.claude', 'settings.local.json');
-
-  // 1. Write Python hook scripts (trace + refresh)
+  const baseDir     = configBaseDir || process.cwd();
+  // per-agent 时 settings.json 写进 agent 的 .claude；全局时仍写 ~/.claude/settings.json。
+  const claudeDir   = configBaseDir
+    ? path.join(baseDir, '.claude')
+    : path.join(os.homedir(), '.claude');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  const localSettingsPath = path.join(baseDir, '.claude', 'settings.local.json');
+
+  // 1. Write Python hook scripts (trace + refresh) — 脚本放全局 ~/.claude/hooks，可共享
   ensureDir(hooksDir);
   writeHookScript(hookScript, readScript('claude-code/cozeloop_hook.py'));
   const refreshScript = path.join(hooksDir, 'cozeloop_refresh.py');
   writeHookScript(refreshScript, readScript('shared/cozeloop_refresh.py'));
 
-  // 2. Merge global settings.json — Stop (trace) + UserPromptSubmit (refresh)
-  const hookCmd    = `${pythonCmd} ~/.claude/hooks/cozeloop_hook.py`;
-  const refreshCmd = `${pythonCmd} ~/.claude/hooks/cozeloop_refresh.py`;
+  // 2. Merge settings.json — Stop (trace) + UserPromptSubmit (refresh)。用绝对路径。
+  const hookCmd    = `${pythonCmd} ${hookScript}`;
+  const refreshCmd = `${pythonCmd} ${refreshScript}`;
 
+  ensureDir(claudeDir);
   const settings = mergeJson(settingsPath, (existing) => {
     if (!existing.hooks) existing.hooks = {};
 
@@ -4379,14 +4472,23 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd) {
   } catch (e) {
     errorBox([`ERROR: Cannot write ${settingsPath}`, '', e.message]);
   }
-  ok(`Global hook registered in ${settingsPath}`);
+  ok(`Hook registered in ${settingsPath}`);
 
-  // 3. Write project-level credentials
-  ensureDir(path.join(process.cwd(), '.claude'));
+  // 3. Write credentials into <baseDir>/.claude/settings.local.json
+  ensureDir(path.join(baseDir, '.claude'));
   const localSettings = mergeJson(localSettingsPath, (existing) => {
     if (!existing.env) existing.env = {};
     existing.env.COZELOOP_WORKSPACE_ID = workspaceId;
-    existing.env.COZELOOP_API_TOKEN    = patToken;
+    // 云端：token 由 sandbox 注入到环境变量 COZE_API_TOKEN，hook 运行时直接读，
+    // 不在配置文件落明文 token。本地：写入 OAuth 拿到的 token。
+    if (cloud) {
+      delete existing.env.COZELOOP_API_TOKEN;
+    } else {
+      existing.env.COZELOOP_API_TOKEN = patToken;
+    }
+    // PPE 泳道：cozeloop SDK 读这两个环境变量，自动注入 x-tt-env / x-use-ppe header
+    existing.env.x_tt_env  = PPE_TT_ENV;
+    existing.env.x_use_ppe = PPE_USE_PPE;
     return existing;
   });
   try {
@@ -4400,11 +4502,16 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd) {
   return { hookScript, settingsPath, localSettingsPath };
 }
 
-function writeCodexHook(token, workspaceId, pythonCmd) {
-  const hooksDir   = path.join(os.homedir(), '.codex', 'hooks');
+// 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）。
+function writeCodexHook(token, workspaceId, pythonCmd, codexHome, cloud) {
+  const home       = codexHome || path.join(os.homedir(), '.codex');
+  const hooksDir   = path.join(home, 'hooks');
   const hookScript = path.join(hooksDir, 'cozeloop_hook.py');
   const envFile    = path.join(hooksDir, 'cozeloop.env');
-  const hooksJson  = path.join(os.homedir(), '.codex', 'hooks.json');
+  const hooksJson  = path.join(home, 'hooks.json');
 
   // 1. Write Python hook scripts (trace + refresh)
   // Token is read from ~/.cozeloop/credentials.json at runtime
@@ -4414,11 +4521,18 @@ function writeCodexHook(token, workspaceId, pythonCmd) {
   writeHookScript(refreshScript, readScript('shared/cozeloop_refresh.py'));
 
   // 2. Write env file with chmod 600
-  const envContent = [
+  //    云端（cloud）：不落明文 token，hook 运行时从环境变量 COZE_API_TOKEN 读取。
+  const envLines = [
     `COZELOOP_WORKSPACE_ID=${workspaceId}`,
-    `COZELOOP_API_TOKEN=${token}`,
-    'TRACE_TO_COZELOOP=true',
-  ].join('\n') + '\n';
+  ];
+  if (!cloud) {
+    envLines.push(`COZELOOP_API_TOKEN=${token}`);
+  }
+  envLines.push('TRACE_TO_COZELOOP=true');
+  // PPE 泳道：cozeloop SDK 读这两个环境变量，自动注入 x-tt-env / x-use-ppe header
+  envLines.push(`x_tt_env=${PPE_TT_ENV}`);
+  envLines.push(`x_use_ppe=${PPE_USE_PPE}`);
+  const envContent = envLines.join('\n') + '\n';
   try {
     fs.writeFileSync(envFile, envContent, { mode: 0o600 });
   } catch (e) {
@@ -4427,8 +4541,9 @@ function writeCodexHook(token, workspaceId, pythonCmd) {
   ok(`Credentials written to ${envFile} (chmod 600)`);
 
   // 3. Merge hooks.json — Stop (trace) + SessionStart (refresh)
-  const hookCmd    = `set -a && . ~/.codex/hooks/cozeloop.env && set +a && ${pythonCmd} ~/.codex/hooks/cozeloop_hook.py`;
-  const refreshCmd = `${pythonCmd} ~/.codex/hooks/cozeloop_refresh.py`;
+  //    命令用绝对路径（CODEX_HOME 不一定是 ~/.codex）。
+  const hookCmd    = `set -a && . ${envFile} && set +a && ${pythonCmd} ${hookScript}`;
+  const refreshCmd = `${pythonCmd} ${refreshScript}`;
 
   const hooks = mergeJson(hooksJson, (existing) => {
     if (!existing.hooks) existing.hooks = {};
@@ -4455,12 +4570,16 @@ function writeCodexHook(token, workspaceId, pythonCmd) {
     errorBox([`ERROR: Cannot write ${hooksJson}`, '', e.message]);
   }
   ok(`Hook registered in ${hooksJson}`);
-  warn('Codex hook trust: 首次运行 Codex 时会提示信任 hook，请选择"信任"以启用 trace 上报。');
+  warn('Codex hook trust: 首次启动 Codex 会提示 "Hooks need review"。在该提示按 t（Trust all and continue），或在会话内运行 /hooks 后按 t，即可一次性信任全部 hook 启用 trace 上报。');
 
   return { hookScript, envFile, hooksJson };
 }
 
-function writeOpenClawHook(token, workspaceId) {
+// writeOpenClawHook 配置 OpenClaw 的 cozeloop-trace 插件（全局装在 ~/.openclaw）。
+// agentId 非空时并入 plugins.entries[...].config.traceAgentIds allowlist —— 插件运行时
+// 用 resolveAgentIdFromHookCtx 取当前 agentId，仅 allowlist 内的 agent 才上报 trace。
+// allowlist 为空（本地全局模式）= 全部放行，向后兼容。
+function writeOpenClawHook(token, workspaceId, agentId) {
   const configPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
   const pluginDir  = path.join(os.homedir(), '.cozeloop', 'openclaw-plugin');
 
@@ -4538,12 +4657,25 @@ function writeOpenClawHook(token, workspaceId) {
     existing.plugins.entries[PLUGIN].enabled = true;
     // hooks.allowConversationAccess required for 2026.5+ to access session content
     existing.plugins.entries[PLUGIN].hooks = { allowConversationAccess: true };
-    existing.plugins.entries[PLUGIN].config = {
-      authorization: `Bearer ${token}`,
-      endpoint:      'https://api.coze.cn/v1/loop/opentelemetry',
-      workspaceId,
-      debug:         true,
-    };
+    if (!existing.plugins.entries[PLUGIN].config) existing.plugins.entries[PLUGIN].config = {};
+    const pcfg = existing.plugins.entries[PLUGIN].config;
+    pcfg.authorization = `Bearer ${token}`;
+    pcfg.endpoint      = 'https://api.coze.cn/v1/loop/opentelemetry';
+    pcfg.workspaceId   = workspaceId;
+    pcfg.debug         = true;
+    // per-agent trace 放行：把当前 agentId 并入 traceAgentIds（去重、归一为小写，
+    // 与插件侧 resolveAgentIdFromHookCtx 的归一一致）。无 agentId（全局模式）则不动
+    // allowlist —— 空 allowlist 表示全部放行。
+    if (agentId) {
+      const norm = String(agentId).trim().toLowerCase();
+      // 读 existing 时一并归一（小写、去空），与插件侧 resolveAgentIdFromHookCtx 一致，
+      // 防手工编辑混入大写条目导致去重失效。
+      const list = (Array.isArray(pcfg.traceAgentIds) ? pcfg.traceAgentIds : [])
+        .map((s) => String(s).trim().toLowerCase())
+        .filter(Boolean);
+      if (norm && !list.includes(norm)) list.push(norm);
+      pcfg.traceAgentIds = list;
+    }
     return existing;
   });
 
@@ -4553,19 +4685,33 @@ function writeOpenClawHook(token, workspaceId) {
     errorBox([`ERROR: Cannot write ${configPath}`, '', e.message]);
   }
   ok(`OpenClaw plugin configured in ${configPath}`);
+
+  // 自动重启 gateway，让新插件配置立即生效（不依赖 plugins install 的隐式重启）。
+  try {
+    const { execSync } = require('child_process');
+    info('Restarting OpenClaw gateway to apply hook changes...');
+    execSync('openclaw gateway restart', { stdio: 'pipe' });
+    ok('OpenClaw gateway restarted');
+  } catch (e) {
+    warn(`gateway restart 失败，请手动执行: openclaw gateway restart（${e.message}）`);
+  }
+
   return { configPath, pluginDir };
 }
 
 // ─── 8. Auth — Device Code OAuth + token store ───────────────────────────────
 const https = require('https');
+const crypto = require('crypto');
 
-function httpsPost(url, body) {
+function httpsPost(url, body, extraHeaders) {
   return new Promise((resolve, reject) => {
     const data = JSON.stringify(body);
     const u = new URL(url);
     const req = https.request(
       { hostname: u.hostname, path: u.pathname + u.search, method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) } },
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data),
+                   'x-tt-env': PPE_TT_ENV, 'x-use-ppe': PPE_USE_PPE,
+                   ...(extraHeaders || {}) } },
       (res) => {
         let buf = '';
         res.on('data', c => buf += c);
@@ -4579,9 +4725,71 @@ function httpsPost(url, body) {
   });
 }
 
+// 真实发一条最小 OTLP trace 到 CozeLoop，验证上报链路是否打通。
+// 只看 HTTP 状态码（2xx=通），不回查 trace 是否落库——回查由外部查询方完成。
+// pairCode 写进 span 的 pair_code attribute，供查询方按该字段过滤回查；缺省自动生成。
+// 不在函数内退出，退出行为交给调用方（主流程 Step 6 / 独立命令 --verify）。
+async function verifyTraceReport(token, workspaceId, pairCode) {
+  const traceId = crypto.randomBytes(16).toString('hex'); // 32 hex chars
+  const spanId  = crypto.randomBytes(8).toString('hex');  // 16 hex chars
+  const nowNs   = String(Date.now() * 1_000_000);         // OTLP 要求纳秒 unix 时间（字符串）
+  // 缺省自动生成 12 位 hex 配对码；查询方按 field_name="pair_code" 回查。
+  const pair    = pairCode || crypto.randomBytes(6).toString('hex');
+
+  const otlpBody = {
+    resourceSpans: [{
+      resource: {
+        attributes: [
+          { key: 'service.name', value: { stringValue: 'cozelab-onboard' } },
+        ],
+      },
+      scopeSpans: [{
+        scope: { name: 'cozelab-onboard-selfcheck' },
+        spans: [{
+          traceId,
+          spanId,
+          name: 'cozelab-onboard-selfcheck',
+          kind: 1,
+          startTimeUnixNano: nowNs,
+          endTimeUnixNano: nowNs,
+          status: { code: 1 },
+          attributes: [
+            { key: 'pair_code', value: { stringValue: pair } },
+          ],
+        }],
+      }],
+    }],
+  };
+
+  let res;
+  try {
+    res = await httpsPost(
+      `${COZE_API}/v1/loop/opentelemetry/v1/traces`,
+      otlpBody,
+      { Authorization: `Bearer ${token}`, 'cozeloop-workspace-id': workspaceId },
+    );
+  } catch (e) {
+    warn(`trace 上报失败: ${e.message}`);
+    return { success: false, status: 0, body: e.message, traceId, pairCode: pair };
+  }
+
+  const success = res.status >= 200 && res.status < 300;
+  if (success) {
+    ok(`trace 上报成功 (traceId=${traceId}, pair_code=${pair})`);
+    info(`查询方可用 pair_code=${pair} 在 CozeLoop 回查确认该 trace 已落库。`);
+  } else {
+    warn(`trace 上报失败: HTTP ${res.status}`);
+    const snippet = (res.body || '').slice(0, 300);
+    if (snippet) console.log(snippet);
+  }
+  return { success, status: res.status, body: res.body, traceId, pairCode: pair };
+}
+
 function httpsGet(url, headers) {
   return new Promise((resolve, reject) => {
-    const req = https.get(url, { headers }, (res) => {
+    // 合并 PPE 泳道 header
+    const h = { ...(headers || {}), 'x-tt-env': PPE_TT_ENV, 'x-use-ppe': PPE_USE_PPE };
+    const req = https.get(url, { headers: h }, (res) => {
       let buf = '';
       res.on('data', c => buf += c);
       res.on('end', () => resolve({ status: res.statusCode, body: buf }));
@@ -4834,22 +5042,11 @@ function authStatus() {
   box(lines, statusColor);
 }
 
-// ── Verify token is usable ────────────────────────────────────────────────
-async function verifyWorkspace(token) {
-  info('验证 Token 有效性...');
-  // Token validity is guaranteed by the Device Code OAuth flow.
-  // We skip a separate API call here since the OAuth app may not have
-  // Account.listWorkspace permission — the token itself is the proof.
-  if (!token) return null;
-  ok(`Token 有效，工作空间 ${WORKSPACE_ID} 确认。`);
-  return token;
-}
-
 // ─── 9. Main ─────────────────────────────────────────────────────────────────
 const NEXT_STEP = {
-  'claude-code': 'Start a new Claude Code session to begin tracing.',
-  'codex':       'Start a new Codex session to begin tracing.',
-  'openclaw':    'Restart OpenClaw to begin tracing.',
+  'claude-code': 'Hook 已写入。Claude Code 会自动热重载 hooks，当前会话即刻生效，无需 /new 或重启。',
+  'codex':       'Hook 已写入。Codex 在会话启动时加载 hook，当前会话不会即时生效；请重开 Codex 会话（已配置 SessionStart hook，新会话自动加载）。',
+  'openclaw':    'OpenClaw gateway 已自动重启，trace 即刻生效。',
 };
 
 async function main() {
@@ -4914,24 +5111,53 @@ async function main() {
     return;
   }
 
-  const { agent } = args;
+  if (args.verify) {
+    info('验证 trace 上报链路...');
+    const token = await getValidToken();   // 无凭证会自动走登录/刷新
+    console.log('');
+    const result = await verifyTraceReport(token, WORKSPACE_ID, args.pairCode);
+    process.exit(result.success ? 0 : 1);
+  }
 
-  // Step 1: Authorize — TEMP(test): 跳过 OAuth，直接使用写死 token
-  // Step 2: Verify token works — TEMP(test): 一并跳过
-  info('Step 1/5: 使用写死 token（已跳过 OAuth）...');
-  let token = HARDCODED_TOKEN;
-  console.log('');
+  const { agent } = args;
+  // 云端模式：开启结构化输出 + errorBox 抛异常（而非 exit）。
+  CLOUD_MODE = !!args.cloud;
+  // per-agent 路由时 agent 的 workspace（claude-code 用它做配置根目录）。
+  const agentWorkspace = args.workspace || '';
+  if (args.agentId) {
+    info(`目标 agent: ${args.agentId} (framework=${agent}, workspace=${agentWorkspace || 'N/A'})`);
+    console.log('');
+  }
 
-  info('Step 2/5: 跳过工作空间权限验证（测试模式）...');
+  // Step 1: Authorize.
+  //   云端（--cloud）：token 取自环境变量 COZE_API_TOKEN，跳过 OAuth / credentials.json。
+  //   本地：load cached → refresh → device code。
+  let token;
+  if (args.cloud) {
+    info('Step 1/5: 云端模式，从环境变量 COZE_API_TOKEN 读取 token...');
+    token = process.env.COZE_API_TOKEN;
+    if (!token) {
+      errorBox([
+        'ERROR: --cloud 模式要求环境变量 COZE_API_TOKEN',
+        '',
+        '云端 sandbox 应在进程环境中注入 COZE_API_TOKEN。',
+        '未检测到该变量，无法配置 trace 上报。',
+      ]);
+    }
+    ok('已从环境变量读取 COZE_API_TOKEN');
+  } else {
+    info('Step 1/5: 检查授权状态...');
+    token = await getValidToken();
+  }
   console.log('');
 
-  // Step 3: Detect agent binary
-  info('Step 3/5: Detecting agent...');
+  // Step 2: Detect agent binary
+  info('Step 2/5: Detecting agent...');
   const version = detectAgent(agent);
   console.log('');
 
-  // Step 4: Environment checks
-  info('Step 4/5: Checking environment...');
+  // Step 3: Environment checks
+  info('Step 3/5: Checking environment...');
   let pythonCmd = null;
   if (agent !== 'openclaw') {
     pythonCmd = checkPython();
@@ -4940,29 +5166,48 @@ async function main() {
   checkVersionWhitelist(agent, version);
   console.log('');
 
-  // Step 5: Write hook configuration
-  info('Step 5/5: Writing hook configuration...');
+  // Step 4: Write hook configuration
+  info('Step 4/5: Writing hook configuration...');
+  let written = {};
   if (agent === 'claude-code') {
-    writeClaudeCodeHook(token, WORKSPACE_ID, pythonCmd);
+    // per-agent 路由时把配置写进 agent 的 workspace（仅该 agent 生效）。
+    // 云端按 agentId 路由但 workspace 为空会导致 settings.json 落 ~/.claude、
+    // settings.local.json 落进程 cwd —— per-agent 隔离失效。此时显式报错。
+    if (args.agentId && !agentWorkspace) {
+      errorBox([
+        `ERROR: agent "${args.agentId}" 的 config.json 缺少 workspace 字段`,
+        '',
+        'claude-code per-agent 配置需要明确的 workspace 目录，',
+        '否则 hook 配置会落到全局/进程目录，无法做到 per-agent 隔离。',
+      ]);
+    }
+    written = writeClaudeCodeHook(token, WORKSPACE_ID, pythonCmd, args.agentId ? agentWorkspace : undefined, args.cloud);
   } else if (agent === 'codex') {
-    writeCodexHook(token, WORKSPACE_ID, pythonCmd);
+    // CODEX_HOME 来源优先级：--codex-home= > 环境变量 CODEX_HOME > ~/.codex（缺省）。
+    const codexHome = args['codex-home'] || process.env.CODEX_HOME || undefined;
+    if (codexHome) info(`Codex 配置目录: ${codexHome}`);
+    written = writeCodexHook(token, WORKSPACE_ID, pythonCmd, codexHome, args.cloud);
   } else {
-    writeOpenClawHook(token, WORKSPACE_ID);
+    // openclaw：云端用 traceAgentIds allowlist 做 per-agent 放行。
+    written = writeOpenClawHook(token, WORKSPACE_ID, args.agentId) || {};
   }
+  // 走到这里说明 detectAgent / 环境检查 / 写 hook 配置全部成功 → 注入成功。
+  cloudResult.inject = 'ok';
   console.log('');
 
-  // Success summary
+  // Success summary（用实际写入路径，per-agent / 自定义 CODEX_HOME 时也准确）
   const summaryLines = [
     `Agent:       ${agent} v${version}`,
   ];
+  if (args.agentId) summaryLines.push(`Agent ID:    ${args.agentId}`);
   if (agent === 'claude-code') {
-    summaryLines.push(`Hook script: ~/.claude/hooks/cozeloop_hook.py`);
-    summaryLines.push(`Config:      ~/.claude/settings.json`);
-    summaryLines.push(`Credentials: .claude/settings.local.json`);
+    summaryLines.push(`Hook script: ${written.hookScript || '~/.claude/hooks/cozeloop_hook.py'}`);
+    summaryLines.push(`Config:      ${written.settingsPath || '~/.claude/settings.json'}`);
+    summaryLines.push(`Credentials: ${written.localSettingsPath || '.claude/settings.local.json'}`);
   } else if (agent === 'codex') {
-    summaryLines.push(`Hook script: ~/.codex/hooks/cozeloop_hook.py`);
-    summaryLines.push(`Config:      ~/.codex/hooks.json`);
-    summaryLines.push(`Credentials: ~/.codex/hooks/cozeloop.env`);
+    summaryLines.push(`Hook script: ${written.hookScript || '~/.codex/hooks/cozeloop_hook.py'}`);
+    summaryLines.push(`Config:      ${written.hooksJson || '~/.codex/hooks.json'}`);
+    summaryLines.push(`Credentials: ${written.envFile || '~/.codex/hooks/cozeloop.env'}`);
   } else {
     summaryLines.push(`Config:      ~/.openclaw/openclaw.json`);
   }
@@ -4979,9 +5224,52 @@ async function main() {
   info('确保 CozeLoop Token 具备 Trace ingest 权限，否则 hook 触发但上报会失败。');
   console.log('');
 
+  // Step 5: Verify trace reporting end-to-end
+  info('Step 5/5: 验证 trace 上报链路...');
+  const verifyResult = await verifyTraceReport(token, WORKSPACE_ID, args.pairCode);
+  if (verifyResult.success) {
+    cloudResult.verify = 'ok';
+  } else if (CLOUD_MODE) {
+    // 云端：注入已成功，验证失败不阻断（放行），记录结果供后台弹 warning。
+    cloudResult.verify = 'fail';
+    cloudResult.logid = extractLogid(verifyResult.body) || cloudResult.logid;
+    cloudResult.message = `trace 上报自检失败 HTTP ${verifyResult.status}: ${(verifyResult.body || '').slice(0, 200)}`;
+    warn('trace 上报自检失败，但 hook 配置已写入（云端放行）。');
+    console.log('');
+    emitCloudResult();
+    successBox(summaryLines);
+    return;
+  } else {
+    errorBox([
+      'ERROR: trace 上报自检失败',
+      '',
+      `HTTP ${verifyResult.status}`,
+      (verifyResult.body || '').slice(0, 300),
+      '',
+      'hook 配置已写入，但上报链路未打通。',
+      '请确认 CozeLoop Token 具备 Trace ingest 权限，再重试。',
+    ]);   // errorBox 内部 process.exit(1)
+  }
+  console.log('');
+
+  emitCloudResult();
   successBox(summaryLines);
 }
 
 main().catch(e => {
+  // 云端模式：失败时输出结构化结果（含 logid），exit 非 0 但带 COZE_LAB_RESULT 行。
+  if (CLOUD_MODE) {
+    if (cloudResult.inject !== 'ok') {
+      // 写 hook 配置前的任何失败 → 注入失败。
+      cloudResult.inject = 'fail';
+    } else if (cloudResult.verify === 'skip') {
+      // 注入已成功，但验证阶段异常崩溃（未走到正常的 ok/fail 判定）→ 记为验证失败。
+      cloudResult.verify = 'fail';
+    }
+    if (!cloudResult.message) cloudResult.message = e && e.message ? e.message : 'unexpected failure';
+    if (!cloudResult.logid) cloudResult.logid = extractLogid(cloudResult.message);
+    emitCloudResult();
+    process.exit(1);
+  }
   errorBox(['ERROR: Unexpected failure', '', e.message]);
 });

package/package.json

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

package/scripts/claude-code/cozeloop_hook.py

@@ -224,7 +224,8 @@ def get_fresh_token() -> Optional[str]:
             if new_token:
                 return new_token
             debug_log("Refresh failed, falling back to env var.")
-    return os.environ.get("COZELOOP_API_TOKEN")
+    # Cloud sandbox: token lives in COZE_API_TOKEN (no credentials.json / refresh).
+    return os.environ.get("COZELOOP_API_TOKEN") or os.environ.get("COZE_API_TOKEN")
 
 # -------------------------------------------------------------------------
 
@@ -431,6 +432,29 @@ def _group_subagent_steps(progress_msgs: List[Dict[str, Any]]) -> List[Dict[str,
     return steps
 
 
+def _parse_ts(msg):
+    """从 transcript msg 的 timestamp 字段解析出 datetime（带时区）。失败返回 None。
+
+    Claude Code transcript 每条 user/assistant 消息都带 ISO8601 timestamp
+    （如 "2026-06-01T13:51:55.450Z"）。建 span 时用它做 start_time，
+    避免回放时所有 span 挤在几毫秒内、duration 全是几毫秒。
+    """
+    if not isinstance(msg, dict):
+        return None
+    ts = msg.get("timestamp")
+    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 group_messages_into_turns(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     """Group messages into conversation turns (user -> assistant -> tool_results).
 
@@ -793,13 +817,31 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
     client = cozeloop.new_client(**client_kwargs)
 
     try:
-        with client.start_span(name="claude_code_request", span_type="main") as root_span:
+        # 整体时间范围：第一条 user 消息 → 最后一条 assistant 消息（真实 transcript 时间）
+        _all_ts = []
+        for _t in turns:
+            _u = _parse_ts(_t.get("user_message"))
+            if _u:
+                _all_ts.append(_u)
+            for _s in _t.get("steps", []):
+                _a = _parse_ts(_s.get("assistant_message"))
+                if _a:
+                    _all_ts.append(_a)
+        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="claude_code_request", span_type="main", start_time=root_start_dt) as root_span:
             root_span.set_runtime(Runtime(library="claude-code"))
             root_tags = {
                 "thread_id": session_id,
                 "total_turns": len(turns),
                 "source": "claude_code"
             }
+            # 真实耗时写 tag（SDK finish 不支持显式结束时间，duration 用 tag 兜底）
+            if root_start_dt is not None and root_end_dt is not None:
+                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,
             }
@@ -836,14 +878,29 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
                     steps = turn.get("steps", [])
                     total_steps = len(steps)
 
-                    with client.start_span(name=f"turn_{i}", span_type="main") as turn_span:
+                    # turn 真实时间：start=user 消息时间，end=最后一个 step 的 assistant 时间
+                    turn_start_dt = _parse_ts(turn.get("user_message"))
+                    turn_end_dt = None
+                    for _s in steps:
+                        _a = _parse_ts(_s.get("assistant_message"))
+                        if _a:
+                            turn_end_dt = _a
+                    if turn_start_dt is None:
+                        turn_start_dt = turn_end_dt
+
+                    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="claude-code"))
-                        turn_span.set_tags({
+                        _turn_tags = {
                             "thread_id": session_id,
                             "turn_index": i,
                             "total_steps": total_steps,
                             "source": "claude_code",
-                        })
+                        }
+                        if turn_start_dt is not None and turn_end_dt is not None:
+                            _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)
 
                         # Extract user input for this turn
                         user_message = turn.get("user_message", {}).get("message", {})
@@ -861,10 +918,23 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
                             raw_content = assistant_message_obj.get("content", [])
                             model_name = assistant_message_obj.get("model", "claude-code")
 
+                            # step 真实时间：start=本 step assistant 时间；end=下一 step assistant 时间（即本次模型调用+工具的耗时），无下一 step 则用 turn_end
+                            step_start_dt = _parse_ts(assistant_msg)
+                            if j + 1 < len(steps):
+                                step_end_dt = _parse_ts(steps[j + 1].get("assistant_message")) or turn_end_dt
+                            else:
+                                step_end_dt = turn_end_dt
+
                             # --- Create model span for this step ---
-                            with client.start_span(name=f"model_call_{j}", span_type="model") as model_span:
+                            with client.start_span(name=f"model_call_{j}", span_type="model", start_time=step_start_dt) as model_span:
                                 model_span.set_runtime(Runtime(library="claude-code"))
                                 model_span.set_model_name(model_name)
+                                if step_start_dt is not None and step_end_dt is not None:
+                                    model_span.set_tags({
+                                        "real_start_ms": _ts_ms(step_start_dt),
+                                        "real_end_ms": _ts_ms(step_end_dt),
+                                        "latency_ms": _ts_ms(step_end_dt) - _ts_ms(step_start_dt),
+                                    })
 
                                 # Set input: accumulated context up to this point
                                 model_span.set_input(ModelInput(
@@ -958,7 +1028,7 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
                                 span_type = "agent" if is_agent else "tool"
                                 span_name = f"agent_{tool_name}" if is_agent else f"tool_{tool_name}"
 
-                                with client.start_span(name=span_name, span_type=span_type) as tool_span:
+                                with client.start_span(name=span_name, span_type=span_type, start_time=step_start_dt) as tool_span:
                                     tool_span.set_runtime(Runtime(library="claude-code"))
                                     tags = {
                                         "tool_name": tool_name,

package/scripts/codex/cozeloop_hook.py

@@ -197,7 +197,8 @@ def get_fresh_token():
             new_token = _refresh_token(creds["refresh_token"])
             if new_token:
                 return new_token
-    return os.environ.get("COZELOOP_API_TOKEN")
+    # Cloud sandbox: token lives in COZE_API_TOKEN (no credentials.json / refresh).
+    return os.environ.get("COZELOOP_API_TOKEN") or os.environ.get("COZE_API_TOKEN")
 # -------------------------------------------------------------------------
 
 # --- SDK Import ---
@@ -415,6 +416,28 @@ 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 group_messages_into_turns(entries: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     """Group raw JSONL entries into conversation turns.
 
@@ -437,6 +460,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":
@@ -645,13 +671,30 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
     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:
+            _u = _parse_ts(_t.get("user_message"))
+            if _u:
+                _all_ts.append(_u)
+            for _a in _t.get("assistant_messages", []):
+                _ad = _parse_ts(_a)
+                if _ad:
+                    _all_ts.append(_ad)
+        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_tags = {
                 "thread_id": session_id,
                 "total_turns": len(turns),
                 "source": "codex_cli",
             }
+            if root_start_dt is not None and root_end_dt is not None:
+                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,
             }
@@ -689,20 +732,49 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
             # 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 = _parse_ts(turn.get("user_message"))
+                    turn_end_dt = None
+                    for _a in turn.get("assistant_messages", []):
+                        _ad = _parse_ts(_a)
+                        if _ad:
+                            turn_end_dt = _ad
+                    if turn_start_dt is None:
+                        turn_start_dt = turn_end_dt
+
+                    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:
+                            _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 = None
+                            for _a in turn.get("assistant_messages", []):
+                                _model_start_dt = _parse_ts(_a)
+                                if _model_start_dt:
+                                    break
+                            if _model_start_dt is None:
+                                _model_start_dt = turn_start_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 turn_end_dt is not None:
+                                    model_span.set_tags({
+                                        "real_start_ms": _ts_ms(_model_start_dt),
+                                        "real_end_ms": _ts_ms(turn_end_dt),
+                                        "latency_ms": _ts_ms(turn_end_dt) - _ts_ms(_model_start_dt),
+                                    })
 
                                 # Build input messages: history + current turn input
                                 turn_input = turn.get("input_messages", [])
@@ -770,7 +842,7 @@ 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:
+                            with client.start_span(name=f"tool_{tool_name}", span_type="tool", start_time=turn_start_dt) as tool_span:
                                 tool_span.set_runtime(Runtime(library="codex-cli"))
                                 tool_span.set_tags({
                                     "tool_name": tool_name,
@@ -794,7 +866,7 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                             agent_id = sc.get("agent_id") or "unknown"
                             nickname = sc.get("nickname") or agent_id
 
-                            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=turn_start_dt) as subagent_span:
                                 subagent_span.set_runtime(Runtime(library="codex-cli"))
                                 subagent_span.set_tags({
                                     "agent_id": agent_id,

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

@@ -36,7 +36,7 @@ async function _refreshToken(refreshTok) {
         const body = JSON.stringify({ grant_type: "refresh_token", client_id: _CLIENT_ID, refresh_token: refreshTok });
         const req = https.request(`${_COZE_API}/api/permission/oauth2/token`, {
             method: "POST",
-            headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) },
+            headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body), "x-tt-env": "ppe_cozelab", "x-use-ppe": "1" },
         }, (res) => {
             let buf = "";
             res.on("data", c => buf += c);
@@ -170,6 +170,8 @@ export class CozeloopExporter {
             headers: {
                 "Authorization": authorization,
                 "cozeloop-workspace-id": workspaceId,
+                "x-tt-env": "ppe_cozelab",
+                "x-use-ppe": "1",
             },
         });
         this.provider = new BasicTracerProvider({ resource });

package/scripts/openclaw/dist/index.js

@@ -446,6 +446,32 @@ function resolveChannelId(ctx, eventFrom, defaultValue = "system/unknown") {
 let lastUserChannelId;
 let lastUserTraceContext;
 let lastOpenclawSessionId;
+// Session-level coze-context cache. In a Coze session only the FIRST user
+// message carries the <coze-context> block; /loop follow-ups and later turns
+// do not. We cache the most recently seen context (per openclaw session id, plus
+// a global last-seen fallback) so that ensureRootSpan can still attach the
+// trace to the right Coze session on those later turns instead of dropping it.
+const cozeContextBySession = new Map();
+let lastCozeContext;
+function rememberCozeContext(input, sessionId) {
+    const parsed = parseCozeContext(input);
+    if (Object.keys(parsed).length === 0)
+        return parsed;
+    lastCozeContext = parsed;
+    if (sessionId)
+        cozeContextBySession.set(sessionId, parsed);
+    return parsed;
+}
+function resolveCozeContext(input, sessionId) {
+    // Prefer context parsed from this turn's input; fall back to the per-session
+    // cache, then the global last-seen context.
+    const fromInput = parseCozeContext(input);
+    if (Object.keys(fromInput).length > 0)
+        return fromInput;
+    if (sessionId && cozeContextBySession.has(sessionId))
+        return cozeContextBySession.get(sessionId);
+    return lastCozeContext || {};
+}
 // Active agent context: set in before_agent_start, cleared in agent_end.
 // All hooks between these two (llm_input, llm_output, tool calls, messages)
 // use this to ensure every span lands in the same Trace.
@@ -485,6 +511,31 @@ const cozeloopTracePlugin = {
             enabledHooks: pluginConfig.enabledHooks,
         };
         const exporter = new CozeloopExporter(api, config);
+        // per-agent trace 放行：traceAgentIds 为 onboard 写入的 allowlist（小写归一）。
+        // 非空时，仅 allowlist 内的 agentId 上报 trace；为空 / 未配置则全部放行（本地全局模式）。
+        const traceAgentIds = Array.isArray(pluginConfig.traceAgentIds)
+            ? pluginConfig.traceAgentIds.map((s) => String(s).trim().toLowerCase()).filter(Boolean)
+            : [];
+        const isAgentAllowed = (hookCtx) => {
+            if (traceAgentIds.length === 0)
+                return true; // 空 allowlist = 全部放行
+            const agentId = resolveAgentIdFromHookCtx(hookCtx || {});
+            const allowed = traceAgentIds.includes(agentId);
+            if (!allowed && config.debug) {
+                api.logger.info(`[CozeloopTrace] agent "${agentId}" not in traceAgentIds, skip trace`);
+            }
+            return allowed;
+        };
+        // 包裹 api.on：带 hookCtx 的 hook 在 agentId 不在 allowlist 时直接跳过，
+        // 不进入任何上报逻辑。gateway_start/stop 等无 hookCtx 的生命周期 hook 不拦截。
+        const rawOn = api.on.bind(api);
+        const on = (name, handler) => {
+            rawOn(name, async (event, hookCtx) => {
+                if (hookCtx !== undefined && !isAgentAllowed(hookCtx))
+                    return;
+                return handler(event, hookCtx);
+            });
+        };
         const contextByChannelId = new Map();
         const contextByRunId = new Map();
         const shouldHookEnabled = (hookName) => {
@@ -761,6 +812,14 @@ const cozeloopTracePlugin = {
         });
         if (shouldHookEnabled("gateway_start")) {
             api.on("gateway_start", async (event) => {
+                // gateway_start 是进程级事件、无 agent 归属。云端 per-agent 模式
+                // （traceAgentIds 非空）下不上报这条无归属 span，避免越过 allowlist。
+                if (traceAgentIds.length > 0) {
+                    if (config.debug) {
+                        api.logger.info("[CozeloopTrace] traceAgentIds set, skip gateway_start span");
+                    }
+                    return;
+                }
                 const now = Date.now();
                 const { ctx, channelId } = getOrCreateContext("system/gateway", undefined, "gateway_start");
                 const span = createSpan(ctx, channelId, "gateway_start", "gateway", now, now, {
@@ -774,7 +833,7 @@ const cozeloopTracePlugin = {
             });
         }
         if (shouldHookEnabled("session_start")) {
-            api.on("session_start", async (event, hookCtx) => {
+            on("session_start", async (event, hookCtx) => {
                 // Refresh token if expiring soon (< 10 min)
                 await exporter.refreshAuthIfNeeded();
                 const rawChannelId = resolveChannelId(hookCtx, event.sessionId);
@@ -791,7 +850,7 @@ const cozeloopTracePlugin = {
             });
         }
         if (shouldHookEnabled("message_received")) {
-            api.on("message_received", async (event, hookCtx) => {
+            on("message_received", async (event, hookCtx) => {
                 const rawChannelId = resolveChannelId(hookCtx, event.from || event.metadata?.senderId);
                 if (config.debug) {
                     api.logger.info(`[CozeloopTrace] message_received hookCtx: ${JSON.stringify({ channelId: hookCtx.channelId, sessionKey: hookCtx.sessionKey, conversationId: hookCtx.conversationId })}, event.from=${event.from}`);
@@ -814,6 +873,9 @@ const cozeloopTracePlugin = {
                         lastUserTraceContext = ctx;
                         ctx.userInput = event.content;
                         lastUserInput = event.content;
+                        // Cache any coze-context as soon as we see the user input,
+                        // so later /loop turns (which carry none) can inherit it.
+                        rememberCozeContext(event.content, ctx.openclawSessionId || lastOpenclawSessionId);
                         if (config.debug) {
                             api.logger.info(`[CozeloopTrace] Saved user context: channelId=${channelId}, traceId=${ctx.traceId}`);
                         }
@@ -829,7 +891,7 @@ const cozeloopTracePlugin = {
             });
         }
         if (shouldHookEnabled("message_sending")) {
-            api.on("message_sending", async (event, hookCtx) => {
+            on("message_sending", async (event, hookCtx) => {
                 if (lastUserTraceContext) {
                     lastUserTraceContext.lastOutput = event.content;
                     if (config.debug) {
@@ -847,7 +909,7 @@ const cozeloopTracePlugin = {
             });
         }
         if (shouldHookEnabled("message_sent")) {
-            api.on("message_sent", async (event, hookCtx) => {
+            on("message_sent", async (event, hookCtx) => {
                 if (event.content && event.success) {
                     if (lastUserTraceContext) {
                         lastUserTraceContext.lastOutput = event.content;
@@ -870,7 +932,7 @@ const cozeloopTracePlugin = {
         let lastLlmStartTime = undefined;
         let lastLlmSpanId = undefined;
         if (shouldHookEnabled("llm_input")) {
-            api.on("llm_input", async (event, hookCtx) => {
+            on("llm_input", async (event, hookCtx) => {
                 const rawChannelId = resolveChannelId(hookCtx);
                 if (config.debug) {
                     api.logger.info(`[CozeloopTrace] llm_input hookCtx: ${JSON.stringify({ channelId: hookCtx.channelId, sessionKey: hookCtx.sessionKey, conversationId: hookCtx.conversationId })}, event.runId=${event.runId}`);
@@ -895,6 +957,9 @@ const cozeloopTracePlugin = {
                         lastUserInput = event.prompt;
                     }
                 }
+                // Cache coze-context from the prompt too (covers sessions where no
+                // message_received fired), so /loop follow-ups can inherit it.
+                rememberCozeContext(event.prompt, ctx.openclawSessionId || lastOpenclawSessionId);
                 // Fallback: ensure root + agent spans exist in case before_agent_start
                 // was not fired (older OpenClaw versions or resumed sessions).
                 const channelIdForSpans = activeAgentChannelId || rawChannelId;
@@ -958,7 +1023,7 @@ const cozeloopTracePlugin = {
             });
         }
         if (shouldHookEnabled("llm_output")) {
-            api.on("llm_output", async (event, hookCtx) => {
+            on("llm_output", async (event, hookCtx) => {
                 const rawChannelId = resolveChannelId(hookCtx);
                 if (config.debug) {
                     api.logger.info(`[CozeloopTrace][DEBUG] llm_output event.usage=${JSON.stringify(event.usage)}`);
@@ -1054,7 +1119,7 @@ const cozeloopTracePlugin = {
             });
         }
         if (shouldHookEnabled("before_tool_call")) {
-            api.on("before_tool_call", async (event, hookCtx) => {
+            on("before_tool_call", async (event, hookCtx) => {
                 const rawChannelId = resolveChannelId(hookCtx);
                 if (config.debug) {
                     api.logger.info(`[CozeloopTrace] before_tool_call hookCtx: ${JSON.stringify({ channelId: hookCtx.channelId, sessionKey: hookCtx.sessionKey, conversationId: hookCtx.conversationId })}, toolName=${event.toolName}`);
@@ -1075,7 +1140,7 @@ const cozeloopTracePlugin = {
             });
         }
         if (shouldHookEnabled("after_tool_call")) {
-            api.on("after_tool_call", async (event, hookCtx) => {
+            on("after_tool_call", async (event, hookCtx) => {
                 if (config.debug) {
                     api.logger.info(`[CozeloopTrace] after_tool_call hookCtx: ${JSON.stringify({ channelId: hookCtx.channelId, sessionKey: hookCtx.sessionKey, conversationId: hookCtx.conversationId })}, toolName=${event.toolName}`);
                 }
@@ -1162,13 +1227,46 @@ const cozeloopTracePlugin = {
                 traceFinalized = false;
             }, 200);
         };
+        // OpenClaw runtime 周期性发送的心跳轮询消息，不是真实对话，整条 trace 丢弃。
+        const HEARTBEAT_INPUT = "[OpenClaw heartbeat poll]";
+        const isHeartbeatInput = (input) => {
+            if (typeof input === "string") {
+                return input.trim() === HEARTBEAT_INPUT;
+            }
+            // content 可能是 [{type:'text', text:'...'}] 形式
+            if (Array.isArray(input)) {
+                return input.some((p) => p && typeof p === "object"
+                    && typeof p.text === "string" && p.text.trim() === HEARTBEAT_INPUT);
+            }
+            return false;
+        };
         // Helper: ensure root openclaw_request span is started for a given context.
         // Must be called before creating the agent span so that the exporter's
         // currentRootContext is set and the agent span becomes a proper child.
         const ensureRootSpan = async (ctx, channelId) => {
-            // Only trace sessions that carry coze-context — no context means this
-            // is not a Coze-originated session and we skip it entirely.
-            if (!Object.keys(parseCozeContext(ctx.userInput)).length) {
+            // 心跳轮询消息：不是真实对话，整条 trace 不上报（沿用下方“无 coze-context 即 return”的同款范式）。
+            const heartbeatInput = ctx.userInput
+                || lastUserTraceContext?.userInput || lastUserInput;
+            if (isHeartbeatInput(heartbeatInput)) {
+                if (config.debug) {
+                    api.logger.info(`[CozeloopTrace] skip heartbeat poll trace, traceId=${ctx.traceId}`);
+                }
+                return;
+            }
+            // Resolve coze-context with SESSION-LEVEL inheritance: only the first
+            // user message of a Coze session carries the <coze-context> block, so
+            // /loop follow-ups and later turns have none. Fall back to the per-
+            // session cache (and global last-seen) instead of dropping the trace.
+            // Only skip when NO context has ever been seen for this session.
+            const ocSessionId = ctx.openclawSessionId || lastOpenclawSessionId;
+            rememberCozeContext(ctx.userInput, ocSessionId);
+            let cozeCtx = resolveCozeContext(ctx.userInput, ocSessionId);
+            if (Object.keys(cozeCtx).length === 0) {
+                // Try the fallback user inputs too before giving up.
+                const fallbackInput = lastUserTraceContext?.userInput || lastUserInput;
+                cozeCtx = resolveCozeContext(fallbackInput, ocSessionId);
+            }
+            if (Object.keys(cozeCtx).length === 0) {
                 return;
             }
             // Check both: rootSpanStartTime indicates we created a root span before,
@@ -1207,7 +1305,7 @@ const cozeloopTracePlugin = {
                     "run.id": ctx.runId,
                     "turn.id": ctx.turnId,
                     "openclaw.channel_id": channelId,
-                    ...parseCozeContext(ctx.userInput),
+                    ...cozeCtx,
                 },
                 input: ctx.userInput,
                 traceId: ctx.traceId,
@@ -1237,7 +1335,7 @@ const cozeloopTracePlugin = {
                     "run.id": ctx.runId,
                     "turn.id": ctx.turnId,
                     "openclaw.channel_id": channelId,
-                    ...parseCozeContext(ctx.userInput),
+                    ...resolveCozeContext(ctx.userInput, ctx.openclawSessionId || lastOpenclawSessionId),
                 },
                 traceId: ctx.traceId,
                 spanId: ctx.agentSpanId,
@@ -1252,7 +1350,7 @@ const cozeloopTracePlugin = {
             }
         };
         if (shouldHookEnabled("before_agent_start")) {
-            api.on("before_agent_start", async (event, hookCtx) => {
+            on("before_agent_start", async (event, hookCtx) => {
                 const rawChannelId = resolveChannelId(hookCtx);
                 const agentId = hookCtx.agentId || event.agentId || "main";
                 if (config.debug) {
@@ -1270,7 +1368,7 @@ const cozeloopTracePlugin = {
             });
         }
         if (shouldHookEnabled("agent_end")) {
-            api.on("agent_end", async (event, hookCtx) => {
+            on("agent_end", async (event, hookCtx) => {
                 const rawChannelId = resolveChannelId(hookCtx);
                 if (config.debug) {
                     api.logger.info(`[CozeloopTrace] agent_end hookCtx: ${JSON.stringify({ channelId: hookCtx.channelId, sessionKey: hookCtx.sessionKey, conversationId: hookCtx.conversationId })}`);
@@ -1290,7 +1388,7 @@ const cozeloopTracePlugin = {
         // versions), finalize the trace here so that agent + root spans get ended
         // and exported.
         if (shouldHookEnabled("session_end")) {
-            api.on("session_end", async (event, hookCtx) => {
+            on("session_end", async (event, hookCtx) => {
                 const rawChannelId = resolveChannelId(hookCtx, event.sessionId);
                 if (config.debug) {
                     api.logger.info(`[CozeloopTrace] session_end: ${rawChannelId}`);