coze_lab 0.1.36 → 0.1.37

package/README.md

@@ -8,8 +8,8 @@ Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to Coz
 # First-time setup — triggers browser OAuth authorization
 npx coze_lab --agent=<type>
 
-# Cloud setup for a managed agent
-npx coze_lab --cloud --agent-id=<agentId>
+# Per-agent setup. Cloud/local is inferred from coze-bridge config.
+npx coze_lab --agent-id=<agentId>
 
 # Auth-only commands (no agent configuration)
 npx coze_lab --login      # Device Code login only
@@ -23,8 +23,8 @@ npx coze_lab --logout     # Clear cached credentials
 | Parameter | Required | Values / Effect |
 |-----------|----------|-----------------|
 | `--agent` | ✓ (for setup) | `claude-code`, `codex`, `openclaw` |
-| `--agent-id` | — | Resolve `~/.coze/agents/<agentId>/config.json` and write per-agent config |
-| `--cloud` | — | Cloud mode: read trace token from env and emit `COZE_LAB_RESULT=...` |
+| `--agent-id` | — | Resolve `~/.coze/agents/<agentId>/config.json` and write per-agent config. `deployType=cloud` enables cloud mode automatically |
+| `--cloud` | — | Backward-compatible override for old callers. New callers should rely on `--agent-id` + config `deployType` |
 | `--codex-home` | — | Override Codex config home for non-cloud/custom runs |
 | `--login` | — | Run the Device Code login flow only |
 | `--status` | — | Print local token status (valid / expiring / expired) |
@@ -56,7 +56,7 @@ npx coze_lab --logout     # Clear cached credentials
 | `codex` | `~/.codex/hooks/cozeloop_hook.py` | `~/.codex/hooks.json` | `~/.codex/hooks/cozeloop.env` |
 | `openclaw` | — (Node.js plugin) | `~/.openclaw/openclaw.json` | inline in config |
 
-For cloud Codex with `--cloud --agent-id=<agentId>`, Codex hooks are written to
+For cloud Codex with `--agent-id=<agentId>` and config `deployType=cloud`, Codex hooks are written to
 `~/.coze/agents/<agentId>/codex-home` by default. The directory is created if it
 does not already exist, so callers do not need to pass `--codex-home` for the
 standard coze-bridge layout.

package/index.js

@@ -11,7 +11,7 @@ const PACKAGE_VERSION = require('./package.json').version;
 const REFRESH_THRESHOLD_MS = 10 * 60 * 1000;
 
 // ─── 1. Cloud structured output ──────────────────────────────────────────────
-// 云端（--cloud）模式：在 stdout 输出一行机器可读结果 COZE_LAB_RESULT={...}，
+// 云端模式：在 stdout 输出一行机器可读结果 COZE_LAB_RESULT={...}，
 // 供管理后台解析判定（inject/verify/logid/message），不依赖中文文案。
 let CLOUD_MODE = false;
 const cloudResult = { version: PACKAGE_VERSION, inject: 'skip', verify: 'skip', logid: '', message: '', token_source: '' };
@@ -156,7 +156,7 @@ function parseArgs() {
 
 const VALID_AGENTS = ['claude-code', 'codex', 'openclaw'];
 
-// resolveAgent 读 ~/.coze/agents/<agentId>/config.json，返回 { framework, workspace, agentId, root }。
+// resolveAgent 读 ~/.coze/agents/<agentId>/config.json，返回 { framework, workspace, deployType, agentId, root }。
 // soft=true 时，config 不存在 / 解析失败 / framework 非法均返回 null（不退出），供云端回退到显式 --agent。
 function resolveAgent(agentId, soft) {
   const root = path.join(os.homedir(), '.coze', 'agents', agentId);
@@ -186,7 +186,8 @@ function resolveAgent(agentId, soft) {
       `支持的类型: ${VALID_AGENTS.join(', ')}`,
     ]);
   }
-  return { framework, workspace: cfg.workspace || '', agentId, root };
+  const deployType = cfg.deployType === 'cloud' ? 'cloud' : 'local';
+  return { framework, workspace: cfg.workspace || '', deployType, agentId, root };
 }
 
 function validateArgs(args) {
@@ -196,28 +197,32 @@ function validateArgs(args) {
   if (args['refresh']) return { refresh: true };
   if (args['verify'])  return { verify:  true, pairCode: args['pair-code'] };
 
-  // --cloud + --agent-id：优先读云端 ~/.coze/agents/<id>/config.json 拿 framework + workspace
-  // （云端 config.json 稳定存在）；读不到再回退到命令行显式 --agent（workspace 在 main 推断）。
-  if (args['cloud'] && args['agent-id']) {
-    const resolved = resolveAgent(args['agent-id'], true /* soft */);
+  // --agent-id：优先读 coze-bridge 的 ~/.coze/agents/<id>/config.json 拿 framework/workspace/deployType。
+  // deployType=cloud 时自动进入云端注入路径；显式 --cloud 仍保留，供 config 缺失时兜底。
+  if (args['agent-id']) {
+    const explicitCloud = !!args['cloud'];
+    const resolved = resolveAgent(args['agent-id'], explicitCloud /* soft */);
     if (resolved) {
+      const cloud = explicitCloud || resolved.deployType === 'cloud';
       return {
         agent: resolved.framework,
         agentId: resolved.agentId,
         workspace: resolved.workspace,
         agentRoot: resolved.root,
+        deployType: resolved.deployType,
         'codex-home': args['codex-home'],
         pairCode: args['pair-code'],
-        cloud: true,
+        cloud,
         force: !!args['force'],
       };
     }
-    // config.json 缺失：回退到显式 --agent
+    // 显式 --cloud 且 config.json 缺失：回退到显式 --agent（workspace 在 main 推断）。
     if (!args['agent'] || !VALID_AGENTS.includes(args['agent'])) {
       errorBox([
         `ERROR: 未找到 agent "${args['agent-id']}" 的 config.json，且未显式指定 --agent`,
         '',
-        '请确认 agentId 正确，或显式拼上 framework：',
+        '新调用方应确认 coze-bridge 已在目标环境写入该 agent config。',
+        '如需兼容旧手工命令，可显式拼上 framework 和 --cloud：',
         `  npx coze_lab --cloud --agent-id=${args['agent-id']} --agent=claude-code|codex|openclaw`,
       ]);
     }
@@ -225,6 +230,7 @@ function validateArgs(args) {
       agent: args['agent'],
       agentId: args['agent-id'],
       workspace: args['workspace'] || '',
+      deployType: 'cloud',
       'codex-home': args['codex-home'],
       pairCode: args['pair-code'],
       cloud: true,
@@ -232,21 +238,6 @@ function validateArgs(args) {
     };
   }
 
-  // 本地 --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'],
-      force: !!args['force'],
-    };
-  }
-
   if (!args['agent']) {
     errorBox([
       'ERROR: --agent 或 --agent-id 至少提供一个',
@@ -377,13 +368,19 @@ function checkPython() {
 const COZELOOP_MIN_SPEC = 'cozeloop>=0.1.28';
 // 探测脚本：import 成功且具备 set_finish_time 能力 → exit 0；否则非 0。
 const COZELOOP_CAPABLE_PROBE = `import cozeloop,sys; sys.exit(0 if hasattr(cozeloop.Span,'set_finish_time') else 3)`;
-function checkCozeloopSdk(pythonCmd) {
+function checkCozeloopSdk(pythonCmd, options = {}) {
+  const cloud = !!options.cloud;
   try {
     execSync(`${pythonCmd} -c "${COZELOOP_CAPABLE_PROBE}"`, { stdio: 'pipe' });
     ok('cozeloop SDK — OK');
     return;
   } catch { /* 未装或版本过旧 — 下面安装/升级 */ }
 
+  if (cloud) {
+    warn(`cozeloop SDK 不可用或版本过旧，云端注入阶段跳过 pip 安装；Hook 运行时会在当前解释器内尝试安装/升级 ${COZELOOP_MIN_SPEC}`);
+    return;
+  }
+
   info(`cozeloop SDK 不可用或版本过旧，正在安装/升级 (pip install -U '${COZELOOP_MIN_SPEC}')...`);
   try {
     execSync(`${pythonCmd} -m pip install --quiet --upgrade '${COZELOOP_MIN_SPEC}'`, { stdio: 'pipe' });
@@ -1128,6 +1125,84 @@ except Exception as e:
   return { success, status: result.code || 0, body, traceId: '', pairCode: pair, apiBaseUrl: apiBase, tokenSource, logid: parsed?.logid || '' };
 }
 
+async function verifyCloudTraceReport(token, workspaceId, pairCode, tokenSource) {
+  const apiBase = getCozeloopSdkApiBaseUrl(true);
+  const tracesUrl = getCozeloopIngestUrlFromBase(apiBase || COZE_API);
+  const traceId = crypto.randomBytes(16).toString('hex');
+  const spanId = crypto.randomBytes(8).toString('hex');
+  const nowMicros = Date.now() * 1000;
+  const pair = pairCode || crypto.randomBytes(6).toString('hex');
+  const ingestBody = {
+    spans: [{
+      started_at_micros: nowMicros,
+      log_id: '',
+      span_id: spanId,
+      parent_id: '0',
+      trace_id: traceId,
+      duration_micros: 1,
+      service_name: '',
+      workspace_id: String(workspaceId),
+      span_name: 'cozelab-onboard-selfcheck',
+      span_type: 'main',
+      status_code: 0,
+      input: 'cozelab-onboard selfcheck',
+      output: 'ok',
+      object_storage: '',
+      system_tags_string: {
+        runtime: JSON.stringify({
+          language: 'nodejs',
+          library: 'coze_lab',
+          scene: process.env.COZELOOP_SCENE || 'custom',
+          loop_sdk_version: `coze_lab@${PACKAGE_VERSION}`,
+        }),
+      },
+      system_tags_long: {},
+      system_tags_double: {},
+      tags_string: {
+        pair_code: pair,
+        source: 'cozelab-onboard',
+        token_source: tokenSource || '',
+      },
+      tags_long: {},
+      tags_double: {},
+      tags_bool: {},
+    }],
+  };
+
+  info(`trace 上报 URL: ${tracesUrl} (cloud fast ingest, api_base_url=${apiBase || '(default)'})`);
+  try {
+    const res = await httpsPost(
+      tracesUrl,
+      ingestBody,
+      {
+        Authorization: `Bearer ${token}`,
+        'User-Agent': `coze_lab/${PACKAGE_VERSION} node/${process.versions.node}`,
+        'X-Coze-Client-User-Agent': JSON.stringify({
+          version: PACKAGE_VERSION,
+          lang: 'nodejs',
+          lang_version: process.versions.node,
+          os_name: process.platform,
+          scene: 'cozeloop',
+          source: 'openapi',
+        }),
+      },
+    );
+    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, apiBaseUrl: apiBase, tokenSource, logid: extractLogid(res.body || '') };
+  } catch (e) {
+    warn(`trace 上报失败: ${e.message}`);
+    return { success: false, status: 0, body: e.message, traceId, pairCode: pair, apiBaseUrl: apiBase, tokenSource, logid: extractLogid(e.message) };
+  }
+}
+
 // 真实发一条最小 OTLP trace 到 CozeLoop，验证上报链路是否打通。
 // 只看 HTTP 状态码（2xx=通），不回查 trace 是否落库——回查由外部查询方完成。
 // pairCode 写进 span 的 pair_code attribute，供查询方按该字段过滤回查；缺省自动生成。
@@ -1203,7 +1278,7 @@ async function verifyTraceReport(token, workspaceId, pairCode, tracesUrl) {
 //            所以额外检测【实际加载的插件是否含刷新逻辑 getRefreshedToken】，无则告警。
 //   - cloud：disableLocalCredentials=true，插件只用写死的 token、不刷新，token 失效需重注入，
 //            刷新能力检测对 cloud 无意义（跳过）。
-async function verifyOpenClawTraceLink(cloud) {
+async function verifyOpenClawTraceLink(cloud, pairCode) {
   const home = resolveHomeDir(cloud);
   const configPath = path.join(home, '.openclaw', 'openclaw.json');
   let pcfg = null;
@@ -1228,7 +1303,7 @@ async function verifyOpenClawTraceLink(cloud) {
   const traceId = crypto.randomBytes(16).toString('hex');
   const spanId = crypto.randomBytes(8).toString('hex');
   const nowMicros = Date.now() * 1000;
-  const pair = crypto.randomBytes(6).toString('hex');
+  const pair = pairCode || crypto.randomBytes(6).toString('hex');
   const ingestBody = {
     spans: [{
       started_at_micros: nowMicros,
@@ -1697,7 +1772,7 @@ async function main() {
         if (cfg?.plugins?.entries?.['openclaw-cozeloop-trace']?.config?.authorization) {
           console.log('');
           info('检测到 openclaw cozeloop-trace 插件，校验其实际 token...');
-          const ocRes = await verifyOpenClawTraceLink(false);
+          const ocRes = await verifyOpenClawTraceLink(false, args.pairCode);
           ocOk = ocRes.success;
         }
       } catch { /* 读不了就跳过 openclaw 校验 */ }
@@ -1721,7 +1796,7 @@ async function main() {
   }
 
   // Step 1: Authorize.
-  //   云端（--cloud）：token 取自 sandbox 注入的环境变量，跳过 OAuth / credentials.json。
+  //   云端模式：token 取自 sandbox 注入的环境变量，跳过 OAuth / credentials.json。
   //     优先使用 COZELOOP_API_TOKEN；兼容使用 COZE_API_TOKEN，并以真实 selfcheck 为准。
   //   本地：load cached → refresh → device code。
   //   注意：workspace_id 始终用写死的 WORKSPACE_ID（团队固定上报 workspace），不读环境。
@@ -1734,7 +1809,7 @@ async function main() {
     tokenSource = tokenInfo.source;
     if (!token) {
       errorBox([
-        'ERROR: --cloud 模式要求环境变量 COZELOOP_API_TOKEN 或 COZE_API_TOKEN',
+        'ERROR: 云端模式要求环境变量 COZELOOP_API_TOKEN 或 COZE_API_TOKEN',
         '',
         '云端 sandbox 应在进程环境中注入可用于 trace ingest 的 token。',
         '未检测到该变量，无法配置 trace 上报。',
@@ -1762,7 +1837,7 @@ async function main() {
   let pythonCmd = null;
   if (agent !== 'openclaw') {
     pythonCmd = checkPython();
-    checkCozeloopSdk(pythonCmd);
+    checkCozeloopSdk(pythonCmd, { cloud: args.cloud });
   }
   checkVersionWhitelist(agent, version);
   console.log('');
@@ -1837,9 +1912,9 @@ async function main() {
   // （插件不读这个临时 token）。openclaw 必须用插件实际配置的 authorization 打 ingest，
   // 才能真实反映运行时上报会不会 401。cloud/local 配置位置一致，统一走这条。
   const verifyResult = agent === 'openclaw'
-    ? await verifyOpenClawTraceLink(args.cloud)
+    ? await verifyOpenClawTraceLink(args.cloud, args.pairCode)
     : args.cloud
-      ? await verifyTraceReportViaSdk(token, WORKSPACE_ID, args.pairCode, pythonCmd || 'python3', tokenSource)
+      ? await verifyCloudTraceReport(token, WORKSPACE_ID, args.pairCode, tokenSource)
       : await verifyTraceReport(token, WORKSPACE_ID, args.pairCode, getOtelTracesUrl(false));
   if (verifyResult.success) {
     cloudResult.verify = 'ok';

package/package.json

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

package/scripts/claude-code/cozeloop_hook.py

@@ -109,6 +109,8 @@ _COZELOOP_CLIENT_ID = "08972682140163281554629748278108.app.coze"
 _COZE_API = "https://api.coze.cn"
 _OTEL_SUFFIX = "/v1/loop/opentelemetry"
 _REFRESH_THRESHOLD = 10 * 60  # refresh when < 10 minutes remain
+_FORCE_REFRESH_COOLDOWN_MS = 60 * 1000
+_REFRESH_LOCK_STALE = 30
 _DEFAULT_WORKSPACE_ID = "7649231955045072915"  # hardcoded spaceID fallback
 
 
@@ -255,6 +257,12 @@ def debug_log(message: str):
 def _get_credentials_path() -> Path:
     return Path.home() / ".cozeloop" / "credentials.json"
 
+def _get_refresh_state_path() -> Path:
+    return Path.home() / ".cozeloop" / "refresh-state.json"
+
+def _get_refresh_lock_path() -> Path:
+    return Path.home() / ".cozeloop" / "refresh-state.lock"
+
 def _load_credentials() -> Optional[Dict]:
     path = _get_credentials_path()
     if not path.exists():
@@ -270,6 +278,55 @@ def _save_credentials(creds: Dict):
     path.write_text(json.dumps(creds, indent=2))
     os.chmod(path, 0o600)
 
+def _load_refresh_state() -> Dict[str, Any]:
+    path = _get_refresh_state_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except Exception:
+        return {}
+
+def _save_refresh_state(patch: Dict[str, Any]):
+    path = _get_refresh_state_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        state = _load_refresh_state()
+        state.update(patch)
+        path.write_text(json.dumps(state, indent=2))
+        os.chmod(path, 0o600)
+    except Exception:
+        pass
+
+def _with_refresh_lock(fn):
+    lock_path = _get_refresh_lock_path()
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    for _ in range(24):
+        fd = None
+        try:
+            fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            try:
+                return fn()
+            finally:
+                try:
+                    os.close(fd)
+                except Exception:
+                    pass
+                try:
+                    lock_path.unlink()
+                except Exception:
+                    pass
+        except FileExistsError:
+            try:
+                if time.time() - lock_path.stat().st_mtime > _REFRESH_LOCK_STALE:
+                    lock_path.unlink()
+                    continue
+            except Exception:
+                pass
+            time.sleep(0.25)
+    hook_log("forced refresh skipped because refresh lock is busy")
+    return None
+
 def _refresh_token(refresh_token: str) -> Optional[str]:
     """Call Coze refresh token API. Returns new access_token or None on failure."""
     try:
@@ -302,6 +359,56 @@ def _refresh_token(refresh_token: str) -> Optional[str]:
         debug_log(f"Token refresh failed: {e}")
     return None
 
+def force_refresh_token_after_upload_failure(reason: str = "upload_failure", current_token: Optional[str] = None) -> Optional[str]:
+    """Force-refresh local credentials after an upload failure, with cross-process throttling."""
+    is_cloud = os.environ.get("COZELAB_ONBOARD_CLOUD", "").lower() in ("1", "true", "yes")
+    if is_cloud:
+        hook_log("upload failure token refresh skipped in cloud mode")
+        return None
+
+    creds = _load_credentials()
+    if not creds or not creds.get("refresh_token"):
+        hook_log("upload failure token refresh skipped; no local refresh_token")
+        return None
+
+    cached = creds.get("access_token")
+    now_ms = int(time.time() * 1000)
+    last_ms = int(_load_refresh_state().get("last_forced_refresh_ms", 0) or 0)
+    if last_ms and now_ms - last_ms < _FORCE_REFRESH_COOLDOWN_MS:
+        if cached and cached != current_token:
+            hook_log("forced refresh throttled; reuse newer cached token")
+            return cached
+        hook_log(f"forced refresh throttled ageMs={now_ms - last_ms}")
+        return None
+
+    def _locked_refresh():
+        locked_creds = _load_credentials()
+        if not locked_creds or not locked_creds.get("refresh_token"):
+            hook_log("forced refresh skipped in lock; credentials missing")
+            return None
+        locked_cached = locked_creds.get("access_token")
+        locked_now_ms = int(time.time() * 1000)
+        locked_last_ms = int(_load_refresh_state().get("last_forced_refresh_ms", 0) or 0)
+        if locked_last_ms and locked_now_ms - locked_last_ms < _FORCE_REFRESH_COOLDOWN_MS:
+            if locked_cached and locked_cached != current_token:
+                hook_log("forced refresh already done by another process; reuse token")
+                return locked_cached
+            hook_log(f"forced refresh skipped in lock ageMs={locked_now_ms - locked_last_ms}")
+            return None
+        _save_refresh_state({
+            "last_forced_refresh_ms": locked_now_ms,
+            "last_reason": (reason or "upload_failure")[:120],
+        })
+        hook_log(f"forced token refresh after upload failure reason={(reason or 'upload_failure')[:120]}")
+        refreshed = _refresh_token(locked_creds["refresh_token"])
+        if refreshed:
+            hook_log("forced token refresh OK")
+        else:
+            hook_log("forced token refresh FAILED")
+        return refreshed
+
+    return _with_refresh_lock(_locked_refresh)
+
 def _normalize_api_base_url(url: str) -> str:
     base = (url or "").strip().rstrip("/")
     if not base:
@@ -960,7 +1067,7 @@ def _build_history_messages(history_turns: List[Dict[str, Any]]) -> list:
 
 # --- CozeLoop Trace Reporting ---
 
-def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history_turns: Optional[List[Dict[str, Any]]] = None):
+def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history_turns: Optional[List[Dict[str, Any]]] = None, retry_on_auth_failure: bool = True):
     """Send conversation turns to CozeLoop.
 
     Span hierarchy:
@@ -1460,6 +1567,12 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
 
     if upload_events:
         debug_log(f"Upload failed, state not advanced. Last failure: {upload_events[-1][:500]}")
+        if retry_on_auth_failure:
+            new_token = force_refresh_token_after_upload_failure(upload_events[-1], token)
+            if new_token:
+                os.environ["COZELOOP_API_TOKEN"] = new_token
+                hook_log("retry upload once after forced token refresh")
+                return send_turns_to_cozeloop(turns, session_id, history_turns, retry_on_auth_failure=False)
         return None
 
     return True

package/scripts/codex/cozeloop_hook.py

@@ -45,6 +45,8 @@ from typing import Optional, List, Dict, Any
 _COZELOOP_CLIENT_ID = "08972682140163281554629748278108.app.coze"
 _COZE_API = "https://api.coze.cn"
 _REFRESH_THRESHOLD = 10 * 60
+_FORCE_REFRESH_COOLDOWN_MS = 60 * 1000
+_REFRESH_LOCK_STALE = 30
 _DEFAULT_WORKSPACE_ID = "7649231955045072915"  # hardcoded spaceID fallback
 _OTEL_SUFFIX = "/v1/loop/opentelemetry"
 
@@ -168,6 +170,12 @@ def _make_finish_event_processor(upload_events: Optional[List[str]] = None):
 def _get_credentials_path() -> Path:
     return Path.home() / ".cozeloop" / "credentials.json"
 
+def _get_refresh_state_path() -> Path:
+    return Path.home() / ".cozeloop" / "refresh-state.json"
+
+def _get_refresh_lock_path() -> Path:
+    return Path.home() / ".cozeloop" / "refresh-state.lock"
+
 def _load_credentials():
     path = _get_credentials_path()
     if not path.exists():
@@ -183,6 +191,55 @@ def _save_credentials(creds):
     path.write_text(json.dumps(creds, indent=2))
     os.chmod(path, 0o600)
 
+def _load_refresh_state():
+    path = _get_refresh_state_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except Exception:
+        return {}
+
+def _save_refresh_state(patch):
+    path = _get_refresh_state_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        state = _load_refresh_state()
+        state.update(patch)
+        path.write_text(json.dumps(state, indent=2))
+        os.chmod(path, 0o600)
+    except Exception:
+        pass
+
+def _with_refresh_lock(fn):
+    lock_path = _get_refresh_lock_path()
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    for _ in range(24):
+        fd = None
+        try:
+            fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            try:
+                return fn()
+            finally:
+                try:
+                    os.close(fd)
+                except Exception:
+                    pass
+                try:
+                    lock_path.unlink()
+                except Exception:
+                    pass
+        except FileExistsError:
+            try:
+                if time.time() - lock_path.stat().st_mtime > _REFRESH_LOCK_STALE:
+                    lock_path.unlink()
+                    continue
+            except Exception:
+                pass
+            time.sleep(0.25)
+    hook_log("forced refresh skipped because refresh lock is busy")
+    return None
+
 def _refresh_token(refresh_tok: str):
     try:
         payload = json.dumps({
@@ -213,6 +270,55 @@ def _refresh_token(refresh_tok: str):
         pass
     return None
 
+def force_refresh_token_after_upload_failure(reason: str = "upload_failure", current_token: Optional[str] = None):
+    is_cloud = os.environ.get("COZELAB_ONBOARD_CLOUD", "").lower() in ("1", "true", "yes")
+    if is_cloud:
+        hook_log("upload failure token refresh skipped in cloud mode")
+        return None
+
+    creds = _load_credentials()
+    if not creds or not creds.get("refresh_token"):
+        hook_log("upload failure token refresh skipped; no local refresh_token")
+        return None
+
+    cached = creds.get("access_token")
+    now_ms = int(time.time() * 1000)
+    last_ms = int(_load_refresh_state().get("last_forced_refresh_ms", 0) or 0)
+    if last_ms and now_ms - last_ms < _FORCE_REFRESH_COOLDOWN_MS:
+        if cached and cached != current_token:
+            hook_log("forced refresh throttled; reuse newer cached token")
+            return cached
+        hook_log(f"forced refresh throttled ageMs={now_ms - last_ms}")
+        return None
+
+    def _locked_refresh():
+        locked_creds = _load_credentials()
+        if not locked_creds or not locked_creds.get("refresh_token"):
+            hook_log("forced refresh skipped in lock; credentials missing")
+            return None
+        locked_cached = locked_creds.get("access_token")
+        locked_now_ms = int(time.time() * 1000)
+        locked_last_ms = int(_load_refresh_state().get("last_forced_refresh_ms", 0) or 0)
+        if locked_last_ms and locked_now_ms - locked_last_ms < _FORCE_REFRESH_COOLDOWN_MS:
+            if locked_cached and locked_cached != current_token:
+                hook_log("forced refresh already done by another process; reuse token")
+                return locked_cached
+            hook_log(f"forced refresh skipped in lock ageMs={locked_now_ms - locked_last_ms}")
+            return None
+        _save_refresh_state({
+            "last_forced_refresh_ms": locked_now_ms,
+            "last_reason": (reason or "upload_failure")[:120],
+        })
+        hook_log(f"forced token refresh after upload failure reason={(reason or 'upload_failure')[:120]}")
+        refreshed = _refresh_token(locked_creds["refresh_token"])
+        if refreshed:
+            hook_log("forced token refresh OK")
+        else:
+            hook_log("forced token refresh FAILED")
+        return refreshed
+
+    return _with_refresh_lock(_locked_refresh)
+
 
 def _normalize_api_base_url(url: str) -> str:
     base = (url or "").strip().rstrip("/")
@@ -965,7 +1071,8 @@ def _make_model_message(role: str, content: str = "", tool_calls: list = None,
 
 
 def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_name: str = "codex",
-                           history_context: Optional[List[Dict[str, Any]]] = None) -> Optional[List[Dict[str, Any]]]:
+                           history_context: Optional[List[Dict[str, Any]]] = None,
+                           retry_on_auth_failure: bool = True) -> Optional[List[Dict[str, Any]]]:
     """Send conversation turns to CozeLoop for tracing.
 
     Span hierarchy:
@@ -1387,6 +1494,18 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
 
     if upload_events:
         hook_log(f"upload failed state not advanced failures={len(upload_events)} detail={upload_events[-1][:500]}")
+        if retry_on_auth_failure:
+            new_token = force_refresh_token_after_upload_failure(upload_events[-1], token)
+            if new_token:
+                os.environ["COZELOOP_API_TOKEN"] = new_token
+                hook_log("retry upload once after forced token refresh")
+                return send_turns_to_cozeloop(
+                    turns,
+                    session_id,
+                    model_name,
+                    history_context,
+                    retry_on_auth_failure=False,
+                )
         return None
 
     return ctx

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

@@ -5,7 +5,7 @@ import { ATTR_SERVICE_NAME, ATTR_SERVICE_INSTANCE_ID } from "@opentelemetry/sema
 import { hostname } from "os";
 import { basename, join } from "path";
 import { createRequire } from "node:module";
-import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from "fs";
+import { readFileSync, writeFileSync, mkdirSync, appendFileSync, openSync, closeSync, unlinkSync, statSync } from "fs";
 import { homedir } from "os";
 import http from "http";
 import https from "https";
@@ -25,7 +25,11 @@ const CLIENT_USER_AGENT = {
 const _CLIENT_ID = "08972682140163281554629748278108.app.coze";
 const _COZE_API  = "https://api.coze.cn";
 const _REFRESH_THRESHOLD_MS = 10 * 60 * 1000;
+const _FORCE_REFRESH_COOLDOWN_MS = 60 * 1000;
+const _REFRESH_LOCK_STALE_MS = 30 * 1000;
 const _CREDS_PATH = join(homedir(), ".cozeloop", "credentials.json");
+const _REFRESH_STATE_PATH = join(homedir(), ".cozeloop", "refresh-state.json");
+const _REFRESH_LOCK_PATH = join(homedir(), ".cozeloop", "refresh-state.lock");
 
 function _loadCreds() {
     try { return JSON.parse(readFileSync(_CREDS_PATH, "utf8")); }
@@ -39,6 +43,60 @@ function _saveCreds(c) {
     } catch { /* non-fatal */ }
 }
 
+function _loadRefreshState() {
+    try { return JSON.parse(readFileSync(_REFRESH_STATE_PATH, "utf8")); }
+    catch { return {}; }
+}
+
+function _saveRefreshState(patch) {
+    try {
+        mkdirSync(join(homedir(), ".cozeloop"), { recursive: true });
+        const state = { ..._loadRefreshState(), ...patch };
+        writeFileSync(_REFRESH_STATE_PATH, JSON.stringify(state, null, 2), { mode: 0o600 });
+    } catch { /* non-fatal */ }
+}
+
+function _authorizationFromCreds(creds) {
+    return creds?.access_token ? `Bearer ${creds.access_token}` : null;
+}
+
+function _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function _withRefreshLock(logFile, fn) {
+    mkdirSync(join(homedir(), ".cozeloop"), { recursive: true });
+    for (let i = 0; i < 24; i++) {
+        let fd = null;
+        try {
+            fd = openSync(_REFRESH_LOCK_PATH, "wx", 0o600);
+            try {
+                return await fn();
+            }
+            finally {
+                try { if (fd !== null) closeSync(fd); } catch { /* ignore */ }
+                try { unlinkSync(_REFRESH_LOCK_PATH); } catch { /* ignore */ }
+            }
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST") {
+                fileLog(logFile, `[auth] refresh lock error=${err?.message || err}`);
+                return null;
+            }
+            try {
+                const ageMs = Date.now() - statSync(_REFRESH_LOCK_PATH).mtimeMs;
+                if (ageMs > _REFRESH_LOCK_STALE_MS) {
+                    unlinkSync(_REFRESH_LOCK_PATH);
+                    continue;
+                }
+            } catch { /* ignore */ }
+            await _sleep(250);
+        }
+    }
+    fileLog(logFile, "[auth] refresh lock busy; skip forced refresh");
+    return null;
+}
+
 async function _refreshToken(refreshTok) {
     return new Promise((resolve) => {
         const body = JSON.stringify({ grant_type: "refresh_token", client_id: _CLIENT_ID, refresh_token: refreshTok });
@@ -72,8 +130,65 @@ async function _refreshToken(refreshTok) {
     });
 }
 
+async function _forceRefreshToken(currentAuthorization, opts = {}) {
+    const logFile = opts.logFile;
+    const creds = _loadCreds();
+    if (!creds?.refresh_token) {
+        fileLog(logFile, "[auth] upload failed but no local refresh_token is available");
+        return null;
+    }
+
+    const cachedAuth = _authorizationFromCreds(creds);
+    const now = Date.now();
+    const state = _loadRefreshState();
+    const lastForced = Number(state.last_forced_refresh_ms || 0);
+    if (lastForced && now - lastForced < _FORCE_REFRESH_COOLDOWN_MS) {
+        if (cachedAuth && cachedAuth !== currentAuthorization) {
+            fileLog(logFile, `[auth] forced refresh throttled; reuse newer cached token tokenLength=${cachedAuth.length}`);
+            return cachedAuth;
+        }
+        fileLog(logFile, `[auth] forced refresh throttled ageMs=${now - lastForced}`);
+        return null;
+    }
+
+    return _withRefreshLock(logFile, async () => {
+        const lockedCreds = _loadCreds();
+        if (!lockedCreds?.refresh_token) {
+            fileLog(logFile, "[auth] forced refresh skipped; credentials disappeared");
+            return null;
+        }
+        const lockedCachedAuth = _authorizationFromCreds(lockedCreds);
+        const lockedState = _loadRefreshState();
+        const lockedLastForced = Number(lockedState.last_forced_refresh_ms || 0);
+        const lockedNow = Date.now();
+        if (lockedLastForced && lockedNow - lockedLastForced < _FORCE_REFRESH_COOLDOWN_MS) {
+            if (lockedCachedAuth && lockedCachedAuth !== currentAuthorization) {
+                fileLog(logFile, `[auth] forced refresh already done by another process; reuse tokenLength=${lockedCachedAuth.length}`);
+                return lockedCachedAuth;
+            }
+            fileLog(logFile, `[auth] forced refresh skipped in lock ageMs=${lockedNow - lockedLastForced}`);
+            return null;
+        }
+
+        _saveRefreshState({
+            last_forced_refresh_ms: lockedNow,
+            last_reason: String(opts.reason || "upload_failure").slice(0, 120),
+        });
+        fileLog(logFile, `[auth] forced token refresh after local upload failure reason=${String(opts.reason || "upload_failure").slice(0, 120)}`);
+        const newToken = await _refreshToken(lockedCreds.refresh_token);
+        if (!newToken) {
+            fileLog(logFile, "[auth] forced token refresh FAILED");
+            return null;
+        }
+        const freshAuth = `Bearer ${newToken}`;
+        fileLog(logFile, `[auth] forced token refresh OK tokenLength=${freshAuth.length}`);
+        return freshAuth;
+    });
+}
+
 async function getRefreshedToken(currentAuthorization, opts = {}) {
     if (opts.disableLocalCredentials) return currentAuthorization;
+    if (opts.force) return _forceRefreshToken(currentAuthorization, opts);
     const creds = _loadCreds();
     if (!creds) return currentAuthorization; // no creds file, keep as-is
     const remaining = (creds.expires_at ?? 0) - Date.now();
@@ -287,6 +402,7 @@ class CozeloopIngestExporter {
         this.logFile = config.logFile;
         this.workspaceId = config.workspaceId;
         this.serviceName = config.serviceName;
+        this.onAuthFailure = config.onAuthFailure;
         this.shutdownRequested = false;
         fileLog(this.logFile, `[ingest] exporter ready url=${this.url} workspaceId=${this.workspaceId}`);
     }
@@ -310,7 +426,43 @@ class CozeloopIngestExporter {
                 serviceName: this.serviceName,
             })),
         };
-        fileLog(this.logFile, `[ingest] POST url=${this.url} spans=${body.spans.length}`);
+        try {
+            await this.postBody(body, false);
+        }
+        catch (err) {
+            const freshAuth = await this.refreshAuthorizationAfterFailure(err);
+            if (!freshAuth) {
+                throw err;
+            }
+            this.headers = { ...this.headers, Authorization: freshAuth };
+            fileLog(this.logFile, `[ingest] retry after token refresh url=${this.url} spans=${body.spans.length}`);
+            try {
+                await this.postBody(body, true);
+            }
+            catch (retryErr) {
+                throw new Error(`retry after token refresh failed: ${retryErr?.message || retryErr}`);
+            }
+        }
+    }
+    async refreshAuthorizationAfterFailure(err) {
+        if (typeof this.onAuthFailure !== "function")
+            return null;
+        fileLog(this.logFile, `[auth] local upload failure triggers refresh attempt err=${String(err?.message || err).slice(0, 300)}`);
+        try {
+            const current = this.headers?.Authorization || "";
+            const fresh = await this.onAuthFailure(current, err);
+            if (fresh && fresh !== current) {
+                return fresh;
+            }
+            fileLog(this.logFile, "[auth] no newer authorization available for retry");
+        }
+        catch (refreshErr) {
+            fileLog(this.logFile, `[auth] refresh attempt threw error=${refreshErr?.message || refreshErr}`);
+        }
+        return null;
+    }
+    async postBody(body, retry) {
+        fileLog(this.logFile, `[ingest] ${retry ? "RETRY " : ""}POST url=${this.url} spans=${body.spans.length}`);
         const res = await postJson(this.url, body, this.headers);
         if (res.status < 200 || res.status >= 300) {
             const snippet = String(res.body || "").slice(0, 300);
@@ -331,7 +483,7 @@ class CozeloopIngestExporter {
                 }
             }
         }
-        fileLog(this.logFile, `[ingest] OK HTTP ${res.status} spans=${body.spans.length}`);
+        fileLog(this.logFile, `[ingest] OK HTTP ${res.status} spans=${body.spans.length}${retry ? " retry=1" : ""}`);
     }
     async forceFlush() {
         return;
@@ -416,6 +568,20 @@ export class CozeloopExporter {
             this.config.authorization = "";
         }
     }
+    async refreshAuthAfterUploadFailure(currentAuthorization, err) {
+        const fresh = await getRefreshedToken(currentAuthorization || this.config.authorization, {
+            disableLocalCredentials: this.config.disableLocalCredentials,
+            force: true,
+            reason: err?.message || "upload_failure",
+            logFile: this.config.logFile,
+        });
+        if (fresh && fresh !== currentAuthorization) {
+            this.api.logger.info("[CozeloopTrace] Token refreshed after upload failure; retrying export...");
+            this.config.authorization = fresh;
+            return fresh;
+        }
+        return null;
+    }
     async ensureInitialized() {
         if (this.initialized)
             return;
@@ -443,6 +609,7 @@ export class CozeloopExporter {
             logFile: this.config.logFile,
             workspaceId,
             serviceName: this.config.serviceName,
+            onAuthFailure: (currentAuthorization, err) => this.refreshAuthAfterUploadFailure(currentAuthorization, err),
             headers: {
                 "Authorization": authorization,
                 "User-Agent": `openclaw-cozeloop-trace/${PLUGIN_VERSION} node/${process.versions.node}`,

package/scripts/openclaw/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-cozeloop-trace",
   "name": "OpenClaw CozeLoop Trace",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Report OpenClaw execution traces to CozeLoop via OpenTelemetry",
   "type": "plugin",
   "entry": "./dist/index.js",

package/scripts/openclaw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cozeloop/openclaw-cozeloop-trace",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "OpenClaw Plugin for reporting traces to CozeLoop via OpenTelemetry",
   "type": "module",
   "main": "dist/index.js",