openclaw-openagent 1.0.11 → 1.0.13

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,17 +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 getOverrideAssetHash(): string {
+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(context?: UIExtensionContext): string {
   return createHash('sha256')
-    .update(readFileSync(OVERRIDE_ASSET_URL))
+    .update(getOverrideAssetContent(context))
     .digest('hex')
     .slice(0, 12);
 }
@@ -109,21 +179,21 @@ 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
@@ -179,7 +249,7 @@ const htmlScriptTag: UIExtension = {
   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');
@@ -188,8 +258,10 @@ const htmlScriptTag: UIExtension = {
     let html = readFileSync(indexPath, 'utf-8');
     const htmlMarker = `<!--openagent:${this.id}-->`;
     const markerPattern = /(?:\/\*openagent:html-script-tag\*\/|<!--openagent:html-script-tag-->)/;
-    const overrideHash = getOverrideAssetHash();
-    const scriptTag = `${htmlMarker}<script src="./openagent-override.js?v=${overrideHash}"></script>`;
+    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;
 

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/proxy/auth-proxy.ts

@@ -19,6 +19,7 @@ import fs from 'node:fs';
 import nodePath from 'node:path';
 import { logger } from '../util/logger.js';
 import { registry } from '../runtime/registry.js';
+import { getOpenagentUpdateStatus } from '../runtime/update-checker.js';
 import { isUnconfiguredOasnApiBase } from '../auth/config.js';
 import { resolveOasnRelativeUrl } from '../util/url-resolver.js';
 
@@ -100,6 +101,10 @@ export function createAuthProxyHandler() {
     if (targetPath.startsWith('/media/')) {
       return serveLocalMedia(targetPath, res);
     }
+    if (targetPath === '/update-status') {
+      writeJson(res, 200, getOpenagentUpdateStatus() as unknown as Record<string, unknown>);
+      return true;
+    }
     // v3.9+ 双轨抽象：上游按当前 transport 切换（OASN → api.oasn.ai；TIM → auth.ai-talk.live）
     const method = req.method ?? 'GET';
     const rt = registry.getDefault();

package/src/runtime/update-checker.ts

@@ -0,0 +1,286 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { logger } from '../util/logger.js';
+
+const PLUGIN_PACKAGE = 'openclaw-openagent';
+const CLI_PACKAGE = 'openclaw-openagent-cli';
+const DEFAULT_DIST_TAG = 'latest';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const CHECK_DELAY_MS = 3_000;
+
+export type OpenagentUpdatePolicy = 'notify' | 'auto' | 'off';
+
+export type OpenagentUpdateStatus = {
+  checked: boolean;
+  checking: boolean;
+  currentVersion: string;
+  latestVersion: string;
+  distTag: string;
+  updateAvailable: boolean;
+  policy: OpenagentUpdatePolicy;
+  installCommand: string;
+  autoUpdateStarted: boolean;
+  lastCheckedAt?: string;
+  error?: string;
+};
+
+type UpdateConfig = {
+  policy: OpenagentUpdatePolicy;
+  distTag: string;
+  channel: string;
+};
+
+let checkerStarted = false;
+
+const updateStatus: OpenagentUpdateStatus = {
+  checked: false,
+  checking: false,
+  currentVersion: '',
+  latestVersion: '',
+  distTag: DEFAULT_DIST_TAG,
+  updateAvailable: false,
+  policy: 'notify',
+  installCommand: `npx -y ${CLI_PACKAGE}`,
+  autoUpdateStarted: false,
+};
+
+export function getOpenagentUpdateStatus(): OpenagentUpdateStatus {
+  return { ...updateStatus };
+}
+
+export function startOpenagentUpdateChecker(): void {
+  if (checkerStarted) return;
+  checkerStarted = true;
+  setTimeout(() => {
+    void runOpenagentUpdateCheck().catch((err) => {
+      updateStatus.checked = true;
+      updateStatus.checking = false;
+      updateStatus.error = (err as Error).message;
+      updateStatus.lastCheckedAt = new Date().toISOString();
+      logger.warn(`[update-check] failed: ${(err as Error).message}`);
+    });
+  }, CHECK_DELAY_MS).unref?.();
+}
+
+export async function runOpenagentUpdateCheck(): Promise<OpenagentUpdateStatus> {
+  const config = resolveUpdateConfig();
+  updateStatus.policy = config.policy;
+  updateStatus.distTag = config.distTag;
+  updateStatus.installCommand = buildInstallCommand(config);
+  updateStatus.currentVersion = resolveCurrentVersion();
+
+  if (config.policy === 'off') {
+    updateStatus.checked = true;
+    updateStatus.checking = false;
+    updateStatus.updateAvailable = false;
+    updateStatus.lastCheckedAt = new Date().toISOString();
+    logger.info('[update-check] disabled by policy');
+    return getOpenagentUpdateStatus();
+  }
+
+  updateStatus.checking = true;
+  updateStatus.error = undefined;
+  try {
+    const latestVersion = await fetchDistTagVersion(config.distTag);
+    updateStatus.latestVersion = latestVersion;
+    updateStatus.updateAvailable = compareVersions(latestVersion, updateStatus.currentVersion) > 0;
+    updateStatus.checked = true;
+    updateStatus.checking = false;
+    updateStatus.lastCheckedAt = new Date().toISOString();
+
+    if (!updateStatus.updateAvailable) {
+      logger.info(`[update-check] up to date: ${PLUGIN_PACKAGE}@${updateStatus.currentVersion}`);
+      return getOpenagentUpdateStatus();
+    }
+
+    logger.warn(
+      `[update-check] new ${PLUGIN_PACKAGE} version available: `
+      + `${updateStatus.currentVersion} -> ${latestVersion}. Run: ${updateStatus.installCommand}`,
+    );
+
+    if (config.policy === 'auto') {
+      startAutoUpdate(config);
+    }
+    return getOpenagentUpdateStatus();
+  } catch (err) {
+    updateStatus.checked = true;
+    updateStatus.checking = false;
+    updateStatus.error = (err as Error).message;
+    updateStatus.lastCheckedAt = new Date().toISOString();
+    throw err;
+  }
+}
+
+function resolveUpdateConfig(): UpdateConfig {
+  const fileConfig = readOpenagentConfig();
+  const envPolicy = normalizePolicy(process.env.OPENAGENT_UPDATE_POLICY);
+  const autoUpdateEnv = readBool(process.env.OPENAGENT_AUTO_UPDATE ?? process.env.OPENAGENT_PLUGIN_AUTO_UPDATE);
+  const checkEnabledEnv = readBool(process.env.OPENAGENT_UPDATE_CHECK);
+  const configPolicy = normalizePolicy(readString(fileConfig, 'update_policy', 'updatePolicy'));
+  const configAutoUpdate = readBool(readString(fileConfig, 'auto_update', 'autoUpdate'));
+  const configUpdateCheck = readBool(readString(fileConfig, 'update_check', 'updateCheck'));
+
+  let policy: OpenagentUpdatePolicy = configPolicy || 'notify';
+  if (configAutoUpdate === true) policy = 'auto';
+  if (configUpdateCheck === false) policy = 'off';
+  if (envPolicy) policy = envPolicy;
+  if (autoUpdateEnv === true) policy = 'auto';
+  if (checkEnabledEnv === false) policy = 'off';
+
+  const distTag = normalizeDistTag(
+    process.env.OPENAGENT_UPDATE_DIST_TAG
+    || readString(fileConfig, 'update_dist_tag', 'updateDistTag')
+    || process.env.OPENAGENT_PLUGIN_DIST_TAG
+    || DEFAULT_DIST_TAG,
+  );
+  const channel = normalizeDistTag(
+    process.env.OPENAGENT_UPDATE_CHANNEL
+    || readString(fileConfig, 'update_channel', 'updateChannel')
+    || process.env.OPENAGENT_PLUGIN_CHANNEL
+    || '',
+  );
+
+  return {
+    policy,
+    distTag: channel || distTag,
+    channel,
+  };
+}
+
+function startAutoUpdate(config: UpdateConfig): void {
+  if (updateStatus.autoUpdateStarted) return;
+  updateStatus.autoUpdateStarted = true;
+
+  const npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  const args = ['-y', CLI_PACKAGE, 'update'];
+  if (config.channel) {
+    args.push('--channel', config.channel);
+  } else if (config.distTag && config.distTag !== DEFAULT_DIST_TAG) {
+    args.push('--dist-tag', config.distTag);
+  }
+
+  logger.warn(`[update-check] auto update started: ${npxBin} ${args.join(' ')}`);
+  const child = spawn(npxBin, args, {
+    detached: true,
+    stdio: 'ignore',
+    env: process.env,
+  });
+  child.unref();
+}
+
+function buildInstallCommand(config: UpdateConfig): string {
+  const parts = ['npx', '-y', CLI_PACKAGE, 'update'];
+  if (config.channel) {
+    parts.push('--channel', config.channel);
+  } else if (config.distTag && config.distTag !== DEFAULT_DIST_TAG) {
+    parts.push('--dist-tag', config.distTag);
+  }
+  return parts.join(' ');
+}
+
+async function fetchDistTagVersion(distTag: string): Promise<string> {
+  if (process.env.OPENAGENT_UPDATE_TEST_VERSION) {
+    return process.env.OPENAGENT_UPDATE_TEST_VERSION;
+  }
+  const registry = (process.env.OPENAGENT_UPDATE_REGISTRY || DEFAULT_REGISTRY).replace(/\/+$/, '');
+  const url = `${registry}/${encodeURIComponent(PLUGIN_PACKAGE)}/${encodeURIComponent(distTag)}`;
+  const res = await fetch(url, {
+    headers: { Accept: 'application/json' },
+    signal: AbortSignal.timeout(5_000),
+  });
+  if (!res.ok) {
+    throw new Error(`npm registry ${res.status} for ${PLUGIN_PACKAGE}@${distTag}`);
+  }
+  const data = await res.json() as { version?: unknown };
+  const version = typeof data.version === 'string' ? data.version : '';
+  if (!version) throw new Error(`npm registry response missing version for ${PLUGIN_PACKAGE}@${distTag}`);
+  return version;
+}
+
+function resolveCurrentVersion(): string {
+  const packageJson = findPackageJson();
+  if (!packageJson) return '0.0.0';
+  try {
+    const data = JSON.parse(fs.readFileSync(packageJson, 'utf8')) as { version?: unknown };
+    return typeof data.version === 'string' ? data.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function findPackageJson(): string | null {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i += 1) {
+    const candidate = path.join(dir, 'package.json');
+    try {
+      const data = JSON.parse(fs.readFileSync(candidate, 'utf8')) as { name?: unknown };
+      if (data.name === PLUGIN_PACKAGE) return candidate;
+    } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function readOpenagentConfig(): Record<string, unknown> {
+  const stateDir = process.env.OPENCLAW_STATE_DIR || path.join(os.homedir(), '.openclaw');
+  const configPath = path.join(stateDir, 'openclaw.json');
+  try {
+    const root = JSON.parse(fs.readFileSync(configPath, 'utf8')) as {
+      channels?: { openagent?: Record<string, unknown> };
+    };
+    return root.channels?.openagent || {};
+  } catch {
+    return {};
+  }
+}
+
+function readString(obj: Record<string, unknown>, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    if (typeof value === 'boolean') return value ? 'true' : 'false';
+  }
+  return '';
+}
+
+function readBool(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value;
+  const text = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!text) return null;
+  if (['1', 'true', 'yes', 'on', 'auto'].includes(text)) return true;
+  if (['0', 'false', 'no', 'off', 'notify'].includes(text)) return false;
+  return null;
+}
+
+function normalizePolicy(value: unknown): OpenagentUpdatePolicy | '' {
+  const text = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (text === 'auto' || text === 'notify' || text === 'off') return text;
+  return '';
+}
+
+function normalizeDistTag(value: unknown): string {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) return '';
+  return /^[A-Za-z0-9._-]+$/.test(text) ? text : '';
+}
+
+export function compareVersions(a: string, b: string): number {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return 0;
+}
+
+function parseVersion(version: string): [number, number, number] {
+  const match = String(version || '').match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return [0, 0, 0];
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}

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 适配）
   //