openclaw-openagent 1.0.9 → 1.0.12

package/src/plugin-ui/modules/remote-agent/tool-card-model.js

@@ -15,6 +15,73 @@ function _clInferToolCardKind(card) {
   return 'call';
 }
 
+function _clPickAgentDescription(source) {
+  if (!source) return '';
+  var keys = [
+    'agent_bio',
+    'agentBio',
+    'bio',
+    'description',
+    'desc',
+    'agent_description',
+    'agentDescription',
+    'MOM',
+    'mom',
+    'introduction',
+    'summary'
+  ];
+  for (var i = 0; i < keys.length; i++) {
+    var value = source[keys[i]];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+}
+
+function _clIsFailureStatusValue(value) {
+  var normalized = String(value || '').trim().toLowerCase();
+  return normalized === 'failed'
+    || normalized === 'failure'
+    || normalized === 'error'
+    || normalized === 'errored'
+    || normalized === 'rejected'
+    || normalized === 'cancelled'
+    || normalized === 'canceled';
+}
+
+function _clLooksLikeRemoteFailureText(text) {
+  var value = String(text || '').trim();
+  if (!value || value.length > 300) return false;
+  return /(^|[，。；\s])(调用失败|执行失败|任务失败|远端服务目前连不上|远端服务.*不可用|两次都返回了调用失败)([，。；\s]|$)/.test(value);
+}
+
+function _clInferToolCardError(card, chunks, rawText) {
+  if (chunks && chunks.some(function(c) { return c && c.type === 'error'; })) return true;
+  if (!card) return _clLooksLikeRemoteFailureText(rawText);
+  if (card.isError === true || card.error === true) return true;
+  if (_clIsFailureStatusValue(card.status)
+      || _clIsFailureStatusValue(card.state)
+      || _clIsFailureStatusValue(card.resultStatus)) {
+    return true;
+  }
+  if (card.error && typeof card.error === 'object') return true;
+  return _clLooksLikeRemoteFailureText(rawText);
+}
+
+function _clApplyAgentIdentityToModel(model) {
+  if (!model || typeof CL === 'undefined' || !CL || typeof CL.getAgentIdentity !== 'function') return model;
+  var identity = CL.getAgentIdentity(model.agentId, model.agentName);
+  if (!identity) return model;
+  model.agentId = model.agentId || identity.id || identity.agent_id;
+  if (!model.agentName || model.agentName === 'Remote Agent') {
+    model.agentName = identity.name || model.agentName;
+  }
+  model.agentAvatar = model.agentAvatar || identity.avatar || identity.avatar_url || identity.avatarUrl || null;
+  if (!model.agentBio) {
+    model.agentBio = _clPickAgentDescription(identity);
+  }
+  return model;
+}
+
 function _clParseToolCardModel(card) {
   var inferredKind = _clInferToolCardKind(card);
 
@@ -23,6 +90,8 @@ function _clParseToolCardModel(card) {
   var agentId = args.agent_id || args.agentId || null;
   var agentName = args.agent_name || args.agentName || agentId || 'Remote Agent';
   var agentAvatar = args.agent_avatar || args.agentAvatar || args.avatar || args.avatar_url || args.avatarUrl || null;
+  var agentBio = _clPickAgentDescription(args);
+  var agentStars = args.agent_stars || args.agentStars || args.stars || args.claws || '3.2万';
   var taskText = args.task || args.message || args.instruction || '';
 
   // 从 text 解析思考步骤 / 最终文本
@@ -32,22 +101,27 @@ function _clParseToolCardModel(card) {
     rawText: rawText
   });
   var hasOutput = inferredKind === 'result' && rawText.trim().length > 0;
-  var isError = chunks.some(function(c) { return c.type === 'error'; });
+  var isError = _clInferToolCardError(card, chunks, rawText);
 
   var model = {
     agentId: agentId,
     agentName: agentName,
     agentAvatar: agentAvatar,
+    agentBio: agentBio,
+    agentStars: agentStars,
     taskText: taskText,
     toolCallId: card.toolCallId || '',
-    status: hasOutput ? 'completed' : 'executing',
+    status: isError ? 'failed' : (hasOutput ? 'completed' : 'executing'),
     rawText: rawText,
+    text: rawText,
+    outputText: rawText,
     chunks: chunks,
     isError: isError,
     inferredKind: inferredKind,
   };
+  _clApplyAgentIdentityToModel(model);
 
-  console.log('[cl-model] parsed:', 'agent=' + agentName,
+  console.log('[cl-model] parsed:', 'agent=' + model.agentName,
     'status=' + model.status,
     'chunks=' + chunks.length,
     'error=' + isError);

package/src/plugin-ui/postinstall-deploy.cjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Best-effort deploy for npm install/upgrade.
+ *
+ * The browser cache strategy depends on Control UI index.html carrying the
+ * latest openagent-override.js?v=<hash>. Running the override builder here
+ * updates reachable OpenClaw Control UI directories immediately after the npm
+ * package changes, without making npm install fail if OpenClaw is not present.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function log(message) {
+  console.log('[openagent postinstall] ' + message);
+}
+
+function main() {
+  if (process.env.OPENAGENT_SKIP_POSTINSTALL_DEPLOY === '1') {
+    log('skipped by OPENAGENT_SKIP_POSTINSTALL_DEPLOY=1');
+    return;
+  }
+
+  const buildScript = path.join(__dirname, 'build.cjs');
+  if (!fs.existsSync(buildScript)) {
+    log('build script not found, skipped');
+    return;
+  }
+
+  const result = spawnSync(process.execPath, [buildScript], {
+    cwd: path.join(__dirname, '..', '..'),
+    env: {
+      ...process.env,
+      OPENAGENT_POSTINSTALL_DEPLOY: '1',
+    },
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    log('deploy skipped: ' + result.error.message);
+    return;
+  }
+  if (result.status !== 0) {
+    log('deploy exited with code ' + result.status + ' (ignored)');
+    return;
+  }
+
+  log('deployed latest Control UI override where reachable');
+}
+
+main();

package/src/plugin-ui/ui-extension-loader/index.ts

@@ -17,7 +17,7 @@ import { restoreFile } from './backup.js';
 import { UI_EXTENSIONS } from './registry-regex.js';
 import { REMOVED_UI_EXTENSIONS } from './removed-extensions.js';
 import type { ManifestData } from './manifest.js';
-import type { UIExtension } from './types.js';
+import type { UIExtension, UIExtensionContext } from './types.js';
 import type { RemovedUIExtension, RemovedRevertResult } from './removed-extensions.js';
 
 // ── 注入策略：正则模式链（无需 .map，21 版本全仿真验证通过）──────────────────
@@ -53,7 +53,7 @@ function needsChange(
  * 4. 共享文件扩展按组处理：任何一个变更 → 恢复 backup → 重新 apply 全组
  * 5. 写入新 manifest
  */
-export async function loadUIExtensions(): Promise<void> {
+export async function loadUIExtensions(context: UIExtensionContext = {}): Promise<void> {
   const controlUiDir = resolveControlUiDir();
 
   if (!controlUiDir) {
@@ -134,7 +134,7 @@ export async function loadUIExtensions(): Promise<void> {
     }
 
     logger.debug(`[ui-ext] ${ext.id}: apply v${ext.version}`);
-    if (safeApply(ext, controlUiDir)) {
+    if (safeApply(ext, controlUiDir, context)) {
       newExtensions[ext.id] = { version: ext.version };
       applied++;
     }
@@ -200,7 +200,7 @@ export async function loadUIExtensions(): Promise<void> {
     // 重新 apply 全组中所有应保留的扩展
     for (const ext of group) {
       logger.debug(`[ui-ext] ${ext.id}: apply v${ext.version} (group rebuild)`);
-      if (safeApply(ext, controlUiDir)) {
+      if (safeApply(ext, controlUiDir, context)) {
         newExtensions[ext.id] = { version: ext.version };
         applied++;
       }
@@ -249,9 +249,9 @@ export async function unloadUIExtensions(): Promise<void> {
 
 // ── Helpers ──────────────────────────────────────────────────────────────
 
-function safeApply(ext: UIExtension, controlUiDir: string): boolean {
+function safeApply(ext: UIExtension, controlUiDir: string, context: UIExtensionContext): boolean {
   try {
-    return ext.apply(controlUiDir);
+    return ext.apply(controlUiDir, context);
   } catch (err) {
     logger.error(`[ui-ext] Failed to apply '${ext.id}': ${(err as Error).message}`);
     return false;

package/src/plugin-ui/ui-extension-loader/registry-regex.ts

@@ -13,15 +13,87 @@ import { logger } from '../../util/logger.js';
 import { findFileByPrefix } from './locator.js';
 import { backupFile, restoreFile } from './backup.js';
 import { makeMarker, hasMarker } from './types.js';
-import type { UIExtension } from './types.js';
+import type { UIExtension, UIExtensionContext } from './types.js';
 
 // ── 常量 ──────────────────────────────────────────────────────────────────
 
 const OVERRIDE_ASSET_URL = new URL('../assets/openagent-override.js', import.meta.url);
+const ICON_ASSET_URL = new URL('../assets/icon.png', import.meta.url);
+const BG_ASSET_URL = new URL('../assets/bg.png', import.meta.url);
+const HOST_ADAPTER_URLS: Record<string, URL> = {
+  'oc-2026-04': new URL('../adapters/oc-2026-04.js', import.meta.url),
+  'oc-2026-05': new URL('../adapters/oc-2026-05.js', import.meta.url),
+  'oc-2026-06': new URL('../adapters/oc-2026-06.js', import.meta.url),
+  'oc-unknown': new URL('../adapters/oc-unknown.js', import.meta.url),
+};
+const HOST_ADAPTER_START = '/*__OPENAGENT_HOST_ADAPTER_START__*/';
+const HOST_ADAPTER_END = '/*__OPENAGENT_HOST_ADAPTER_END__*/';
+const HOST_ADAPTER_BLOCK_RE = /\/\*__OPENAGENT_HOST_ADAPTER_START__\*\/[\s\S]*?\/\*__OPENAGENT_HOST_ADAPTER_END__\*\//;
+const BUILD_ID_TOKEN = "buildId: '__OPENAGENT_BUILD_ID__'";
+const BUILD_ID_ASSIGNMENT_RE = /buildId:\s*(?:"[^"]*"|'[^']*')/;
+
+function normalizeHostVersion(hostVersion: string | undefined): string {
+  const value = String(hostVersion || '').trim();
+  if (!value || value === 'unknown') return '';
+  const match = value.match(/20\d{2}\.\d{1,2}\.\d{1,2}(?:-[A-Za-z0-9._-]+)?/);
+  return match ? match[0] : '';
+}
+
+function resolveHostAdapterId(hostVersion: string | undefined): string {
+  const version = normalizeHostVersion(hostVersion);
+  const parts = version.split('.');
+  const year = Number.parseInt(parts[0], 10);
+  const month = Number.parseInt(parts[1], 10);
+  if (year === 2026 && month === 4) return 'oc-2026-04';
+  if (year === 2026 && month === 5) return 'oc-2026-05';
+  if (year === 2026 && month === 6) return 'oc-2026-06';
+  return 'oc-unknown';
+}
+
+function getHostAdapterBlock(hostVersion: string | undefined): string {
+  let adapterId = resolveHostAdapterId(hostVersion);
+  let adapterUrl = HOST_ADAPTER_URLS[adapterId];
+  if (!adapterUrl || !existsSync(adapterUrl)) {
+    adapterId = 'oc-unknown';
+    adapterUrl = HOST_ADAPTER_URLS[adapterId];
+  }
+  const adapterSource = readFileSync(adapterUrl, 'utf-8').trimEnd();
+  return [
+    HOST_ADAPTER_START,
+    `// HOST ADAPTER: ${adapterId}`,
+    adapterSource,
+    HOST_ADAPTER_END,
+  ].join('\n');
+}
+
+function injectHostAdapter(source: string, hostVersion: string | undefined): string {
+  const block = getHostAdapterBlock(hostVersion);
+  return HOST_ADAPTER_BLOCK_RE.test(source)
+    ? source.replace(HOST_ADAPTER_BLOCK_RE, block)
+    : source;
+}
+
+function injectBuildId(source: string): string {
+  const normalized = source.replace(BUILD_ID_ASSIGNMENT_RE, BUILD_ID_TOKEN);
+  const buildId = createHash('sha256').update(normalized).digest('hex').slice(0, 12);
+  return normalized.replace(BUILD_ID_TOKEN, `buildId: ${JSON.stringify(buildId)}`);
+}
+
+function getOverrideAssetContent(context?: UIExtensionContext): string {
+  let source = readFileSync(OVERRIDE_ASSET_URL, 'utf-8');
+  const hostVersion = normalizeHostVersion(context?.hostVersion);
+  if (hostVersion) {
+    source = source.replace(
+      "hostVersion: '__OPENCLAW_HOST_VERSION__'",
+      `hostVersion: ${JSON.stringify(hostVersion)}`,
+    );
+  }
+  return injectBuildId(injectHostAdapter(source, hostVersion));
+}
 
-function getOverrideAssetHash(): string {
+function getOverrideAssetHash(context?: UIExtensionContext): string {
   return createHash('sha256')
-    .update(readFileSync(OVERRIDE_ASSET_URL))
+    .update(getOverrideAssetContent(context))
     .digest('hex')
     .slice(0, 12);
 }
@@ -107,22 +179,43 @@ const overrideScript: UIExtension = {
   version: 1,
   alwaysApply: true,
 
-  apply(controlUiDir: string): boolean {
+  apply(controlUiDir: string, context?: UIExtensionContext): boolean {
     if (!existsSync(OVERRIDE_ASSET_URL)) {
       logger.warn('[ui-ext:regex] override-script: asset missing');
       return false;
     }
     const dest = join(controlUiDir, 'openagent-override.js');
+    const srcContent = getOverrideAssetContent(context);
     if (existsSync(dest)) {
-      const srcContent = readFileSync(OVERRIDE_ASSET_URL, 'utf-8');
       const destContent = readFileSync(dest, 'utf-8');
       if (srcContent === destContent) {
         logger.debug('[ui-ext:regex] override-script: content unchanged, skip');
         return true;
       }
     }
-    copyFileSync(OVERRIDE_ASSET_URL, dest);
+    writeFileSync(dest, srcContent, 'utf-8');
     logger.info('[ui-ext:regex] override-script: deployed openagent-override.js');
+
+    // Deploy icon.png alongside
+    if (existsSync(ICON_ASSET_URL)) {
+      const iconDest = join(controlUiDir, 'icon.png');
+      try {
+        copyFileSync(ICON_ASSET_URL, iconDest);
+        logger.info('[ui-ext:regex] override-script: deployed icon.png');
+      } catch (err) {
+        logger.warn('[ui-ext:regex] override-script: failed to deploy icon.png');
+      }
+    }
+    if (existsSync(BG_ASSET_URL)) {
+      const bgDest = join(controlUiDir, 'bg.png');
+      try {
+        copyFileSync(BG_ASSET_URL, bgDest);
+        logger.info('[ui-ext:regex] override-script: deployed bg.png');
+      } catch (err) {
+        logger.warn('[ui-ext:regex] override-script: failed to deploy bg.png');
+      }
+    }
+
     return true;
   },
 
@@ -132,6 +225,20 @@ const overrideScript: UIExtension = {
       unlinkSync(dest);
       logger.info('[ui-ext:regex] override-script: removed');
     }
+    const iconDest = join(controlUiDir, 'icon.png');
+    if (existsSync(iconDest)) {
+      try {
+        unlinkSync(iconDest);
+        logger.info('[ui-ext:regex] override-script: removed icon.png');
+      } catch {}
+    }
+    const bgDest = join(controlUiDir, 'bg.png');
+    if (existsSync(bgDest)) {
+      try {
+        unlinkSync(bgDest);
+        logger.info('[ui-ext:regex] override-script: removed bg.png');
+      } catch {}
+    }
   },
 };
 
@@ -139,10 +246,10 @@ const overrideScript: UIExtension = {
 
 const htmlScriptTag: UIExtension = {
   id: 'html-script-tag',
-  version: 4,
+  version: 5,
   alwaysApply: true,
 
-  apply(controlUiDir: string): boolean {
+  apply(controlUiDir: string, context?: UIExtensionContext): boolean {
     const indexPath = join(controlUiDir, 'index.html');
     if (!existsSync(indexPath)) {
       logger.warn('[ui-ext:regex] html-script-tag: index.html not found');
@@ -150,12 +257,23 @@ const htmlScriptTag: UIExtension = {
     }
     let html = readFileSync(indexPath, 'utf-8');
     const htmlMarker = `<!--openagent:${this.id}-->`;
-    const overrideHash = getOverrideAssetHash();
-    const scriptTag = `${htmlMarker}<script src="./openagent-override.js?v=${overrideHash}"></script>`;
+    const markerPattern = /(?:\/\*openagent:html-script-tag\*\/|<!--openagent:html-script-tag-->)/;
+    const overrideHash = getOverrideAssetHash(context);
+    const hostVersion = normalizeHostVersion(context?.hostVersion);
+    const hostVersionAttr = hostVersion ? ` data-openagent-host-version="${hostVersion}"` : '';
+    const scriptTag = `${htmlMarker}<script src="./openagent-override.js?v=${overrideHash}"${hostVersionAttr}></script>`;
     const markedScriptPattern = /(?:\/\*openagent:html-script-tag\*\/|<!--openagent:html-script-tag-->)<script[^>]*openagent-override[^>]*><\/script>\n?\s*/g;
+    const oldScriptPattern = /<script[^>]*openagent-override[^>]*><\/script>\n?\s*/g;
 
-    if (html.includes(htmlMarker) || hasMarker(html, this.id)) {
-      const nextHtml = html.replace(markedScriptPattern, `${scriptTag}\n    `);
+    if (markerPattern.test(html)) {
+      let nextHtml = html.replace(markedScriptPattern, `${scriptTag}\n    `);
+      if (nextHtml === html && !nextHtml.includes('openagent-override.js')) {
+        nextHtml = nextHtml.replace(markerPattern, `${scriptTag}\n    `);
+      } else if (nextHtml === html && nextHtml.includes('openagent-override.js')) {
+        nextHtml = nextHtml
+          .replace(oldScriptPattern, '')
+          .replace(markerPattern, `${scriptTag}\n    `);
+      }
       if (nextHtml === html) {
         logger.debug('[ui-ext:regex] html-script-tag: already applied');
       } else {
@@ -164,7 +282,6 @@ const htmlScriptTag: UIExtension = {
       }
       return true;
     }
-    const oldScriptPattern = /<script[^>]*openagent-override[^>]*><\/script>\n?\s*/g;
     if (oldScriptPattern.test(html)) {
       html = html.replace(oldScriptPattern, '');
     }
@@ -354,7 +471,7 @@ const toolcardRender: UIExtension = {
             }
             if (toolMessageOk) {
               const toolMessageHook =
-                `${marker}/* openagent-media-aware-tool-message */let __openagentToolMsgCard=null;console.log('[openagent] toolMsg hook: cards='+${cardsVar}.length+' mediaVar='+${mediaVar});if(window.__openagentRenderToolCard){for(let __openagentI=${cardsVar}.length-1;__openagentI>=0&&!__openagentToolMsgCard;__openagentI--){let __openagentCandidate=${cardsVar}[__openagentI];if(__openagentCandidate&&(__openagentCandidate.outputText||__openagentCandidate.text))__openagentToolMsgCard=window.__openagentRenderToolCard(__openagentCandidate,${toolMessageSidebarArg})}for(let __openagentI=0;__openagentI<${cardsVar}.length&&!__openagentToolMsgCard;__openagentI++){__openagentToolMsgCard=window.__openagentRenderToolCard(${cardsVar}[__openagentI],${toolMessageSidebarArg})}}if(__openagentToolMsgCard)return ${toolMessageHtmlVar}\`<div class="\${${chatBubbleClassVar}}">\${__openagentToolMsgCard}</div>\`;`;
+                `${marker}/* openagent-media-aware-tool-message */let __openagentToolMsgCard=null;if(window.__openagentRenderToolCard){for(let __openagentI=${cardsVar}.length-1;__openagentI>=0&&!__openagentToolMsgCard;__openagentI--){let __openagentCandidate=${cardsVar}[__openagentI];if(__openagentCandidate&&(__openagentCandidate.outputText||__openagentCandidate.text))__openagentToolMsgCard=window.__openagentRenderToolCard(__openagentCandidate,${toolMessageSidebarArg})}for(let __openagentI=0;__openagentI<${cardsVar}.length&&!__openagentToolMsgCard;__openagentI++){__openagentToolMsgCard=window.__openagentRenderToolCard(${cardsVar}[__openagentI],${toolMessageSidebarArg})}}if(__openagentToolMsgCard)return ${toolMessageHtmlVar}\`<div class="\${${chatBubbleClassVar}}">\${__openagentToolMsgCard}</div>\`;`;
               const toolMessageInsertAt = toolMessageFn!.bodyStart + toolMessageReturnIdx;
               content = content.substring(0, toolMessageInsertAt) + toolMessageHook + content.substring(toolMessageInsertAt);
               patchedToolMessageWrapper = true;

package/src/plugin-ui/ui-extension-loader/types.ts

@@ -37,7 +37,7 @@ export interface UIExtension {
    * 接收 control-ui 目录路径，内部自行决定改什么文件、怎么改。
    * 返回 true 表示成功，false 表示失败（不写入 manifest，下次重试）。
    */
-  apply: (controlUiDir: string) => boolean;
+  apply: (controlUiDir: string, context?: UIExtensionContext) => boolean;
 
   /**
    * 卸载扩展。
@@ -47,6 +47,10 @@ export interface UIExtension {
   revert: (controlUiDir: string) => void;
 }
 
+export interface UIExtensionContext {
+  hostVersion?: string;
+}
+
 /**
  * OpenAgent 标记前缀，注入的代码旁加此注释以标识修改来源。
  * 格式：/*openagent:<extension-id>* /

package/src/state/store.ts

@@ -67,6 +67,22 @@ export interface PendingInvocationRecord {
   updated_at: number;
 }
 
+/**
+ * 远程 ServiceAgent 会话续传记录。
+ *
+ * 一个 OpenClaw 本地会话里，同一个远程 Agent 的第一次 invocation 会返回
+ * session_id；后续 mode='session' 的调用应带回这个 session_id，才能保留
+ * 远端上下文。account_id + openclaw_session_key + target_agent_id 共同隔离，
+ * 避免不同账号、不同本地聊天、不同远程 Agent 之间串 session。
+ */
+export interface RemoteAgentSessionRecord {
+  openclaw_session_key: string;
+  target_agent_id: string;
+  session_id: string;
+  created_at: number;
+  updated_at: number;
+}
+
 interface SqlJsDatabase {
   run(sql: string, params?: unknown[]): void;
   prepare(sql: string): SqlJsStatement;
@@ -291,6 +307,21 @@ export class StateStore {
       CREATE INDEX IF NOT EXISTS idx_pending_invocations_invocation
       ON pending_invocations (account_id, invocation_id)
     `);
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS remote_agent_sessions (
+        account_id             TEXT NOT NULL,
+        openclaw_session_key   TEXT NOT NULL,
+        target_agent_id        TEXT NOT NULL,
+        session_id             TEXT NOT NULL,
+        created_at             INTEGER NOT NULL DEFAULT 0,
+        updated_at             INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (account_id, openclaw_session_key, target_agent_id)
+      )
+    `);
+    this.db.run(`
+      CREATE INDEX IF NOT EXISTS idx_remote_agent_sessions_updated
+      ON remote_agent_sessions (account_id, updated_at)
+    `);
   }
 
   // ── Write to disk ──
@@ -533,6 +564,55 @@ export class StateStore {
     }
   }
 
+  // ═════════════════════════════════════════════════════════════════
+  // OASN remote_agent_sessions CRUD
+  //
+  // 保存远端 ServiceAgent 返回的 session_id，用于同一 OpenClaw 会话内后续
+  // mode='session' 调用续传。run 模式不读写这张表。
+  // ═════════════════════════════════════════════════════════════════
+
+  getRemoteAgentSession(openclawSessionKey: string, targetAgentId: string): string | null {
+    if (!this.db) return null;
+    const scopeKey = openclawSessionKey.trim();
+    const agentId = targetAgentId.trim();
+    if (!scopeKey || !agentId) return null;
+
+    const stmt = this.db.prepare(
+      `SELECT session_id
+       FROM remote_agent_sessions
+       WHERE account_id = ? AND openclaw_session_key = ? AND target_agent_id = ?`,
+    );
+    stmt.bind([this.accountId, scopeKey, agentId]);
+    const row = stmt.step() ? stmt.getAsObject() : null;
+    stmt.free();
+    const sessionId = row?.['session_id'];
+    return typeof sessionId === 'string' && sessionId.trim() ? sessionId : null;
+  }
+
+  upsertRemoteAgentSession(record: {
+    openclaw_session_key: string;
+    target_agent_id: string;
+    session_id: string;
+  }): void {
+    if (!this.db) return;
+    const scopeKey = record.openclaw_session_key.trim();
+    const agentId = record.target_agent_id.trim();
+    const sessionId = record.session_id.trim();
+    if (!scopeKey || !agentId || !sessionId) return;
+
+    const now = Date.now();
+    this.db.run(
+      `INSERT INTO remote_agent_sessions
+         (account_id, openclaw_session_key, target_agent_id, session_id, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(account_id, openclaw_session_key, target_agent_id) DO UPDATE SET
+         session_id = excluded.session_id,
+         updated_at = excluded.updated_at`,
+      [this.accountId, scopeKey, agentId, sessionId, now, now],
+    );
+    this.persist();
+  }
+
   // ═════════════════════════════════════════════════════════════════
   // §11.1 OASN pending_invocations CRUD（OasnInvocation.PendingInvocationStore 适配）
   //

package/src/transport/oasn/oasn-invocation.ts

@@ -407,15 +407,10 @@ export class OasnInvocation {
       };
     }
 
-    // 失败/超时/取消 —— 文本统一用 user_error.message 兜底
-    const userError = final.userError ?? final.user_error;
-    const inlineResult = final.inlineResult ?? final.inline_result;
-    const visible = final.visibleResult ?? final.visible_result;
-    const message = userError?.message
-      ?? inlineResult?.summary
-      ?? visible?.inlineResultSummary
-      ?? visible?.inline_result_summary
-      ?? `Invocation ended with status=${final.status}`;
+    const message = this._invocationFailureMessage(
+      final,
+      `Invocation ended with status=${final.status}`,
+    );
     return {
       requestId: invocationId,
       status: 'error',
@@ -450,15 +445,55 @@ export class OasnInvocation {
 
   /** 终态错误专用 TransportError，便于上层 catch */
   private _terminalError(final: GetInvocationResponse, handle: TaskHandle): TransportError {
-    const userError = final.userError ?? final.user_error;
-    const code = userError?.code ?? `INVOCATION_${final.status.toUpperCase()}`;
-    const msg = userError?.message ?? `Invocation ${final.status}`;
+    const code = this._invocationFailureCode(final) ?? `INVOCATION_${final.status.toUpperCase()}`;
+    const msg = this._invocationFailureMessage(final, `Invocation ${final.status}`);
     return makeTransportError(code, msg, {
       invocationId: handle.invocationId,
       sessionId: handle.sessionId,
     });
   }
 
+  private _invocationFailureCode(final: GetInvocationResponse): string | undefined {
+    return this._firstText(
+      final.userError?.code,
+      final.user_error?.code,
+      final.userErrorCode,
+      final.user_error_code,
+    );
+  }
+
+  private _invocationFailureMessage(final: GetInvocationResponse, fallback: string): string {
+    const userMessage = this._firstText(
+      final.userError?.message,
+      final.user_error?.message,
+      final.userErrorMessage,
+      final.user_error_message,
+    );
+    if (userMessage) return userMessage;
+
+    const inlineResult = final.inlineResult ?? final.inline_result;
+    const visible = final.visibleResult ?? final.visible_result;
+    const fallbackMessage = this._firstText(
+      inlineResult?.summary,
+      visible?.inlineResultSummary,
+      visible?.inline_result_summary,
+      final.progress?.safeStatusMessage,
+      final.progress?.safe_status_message,
+    );
+    const code = this._invocationFailureCode(final);
+    if (fallbackMessage && code && !fallbackMessage.includes(code)) return `${fallbackMessage} (${code})`;
+    return fallbackMessage ?? code ?? fallback;
+  }
+
+  private _firstText(...values: Array<unknown>): string | undefined {
+    for (const value of values) {
+      if (typeof value !== 'string') continue;
+      const trimmed = value.trim();
+      if (trimmed) return trimmed;
+    }
+    return undefined;
+  }
+
   private _toArtifactRef(art: ArtifactResponse): ArtifactRef {
     return {
       id: art.artifactId ?? art.artifact_id ?? '',

package/src/transport/oasn/oasn-types.ts

@@ -316,8 +316,12 @@ export interface GetInvocationResponse {
   nextPollAfterMs?: number | null;
   next_poll_after_ms?: number | null;
   warnings?: string[];
-  userError?: { code: string; message: string };
-  user_error?: { code: string; message: string };
+  userError?: { code?: string; message?: string | null };
+  user_error?: { code?: string; message?: string | null };
+  userErrorCode?: string;
+  user_error_code?: string;
+  userErrorMessage?: string | null;
+  user_error_message?: string | null;
   createdAt?: string;
   created_at?: string;
   updatedAt?: string;

package/src/types/openclaw-plugin-sdk-media-store.d.ts

@@ -0,0 +1,9 @@
+declare module 'openclaw/plugin-sdk/media-store' {
+  export function saveMediaBuffer(
+    buffer: Buffer,
+    mimeType: string,
+    namespace: string,
+    maxBytes: number,
+    filename?: string,
+  ): Promise<{ id: string }>;
+}