openclaw-openagent 1.0.0 → 1.0.2

package/dist/src/runtime/account.js

@@ -0,0 +1,491 @@
+/**
+ * AccountRuntime — All per-account state and lifecycle
+ *
+ * Owns the lifecycle of a single active account:
+ *   1. StateStore (SQLite)
+ *   2. CredentialManager (auth token lifecycle)
+ *   3. TIMClient (SDK connection)
+ *   4. Message pipeline: channelRuntime dispatch (via process-message.ts)
+ *
+ * Supports "half-alive" mode: when agent is not yet claimed,
+ * start() succeeds without TIM connection. Tools trigger
+ * lazy connection via ensureConnected().
+ *
+ * v3.2.0: Replaced shell-out executor pipeline with channelRuntime dispatch.
+ * See docs/audit/004-messaging-pipeline-v3.1.4.md for migration context.
+ *
+ * v3.9.0: 引入 AgentTransport 双轨抽象。
+ *   - transport='oasn'（默认）：走 OASN HTTP API，不再创建 TIMClient
+ *   - transport='tim'（显式配置回退）：保留原 TIMClient + CredentialManager 路径
+ *   两条路径在 start() 内按 config.transport 字段分发；旧路径在阶段 4 上层切换完毕后再删除。
+ *   详见 docs/specs/2026-06-16-oasn-transport-abstraction-design.md §5.2
+ */
+import { logger } from '../util/logger.js';
+import { CredentialManager, CredentialError } from '../auth/credential-manager.js';
+import { StateStore } from '../state/store.js';
+import { createPendingInvocationStore } from '../state/pending-invocation-store.js';
+import { TIMClient } from '../tim/client.js';
+import * as channels from '../tim/channels.js';
+import * as messages from '../tim/messages.js';
+import { initC2CHandler } from '../tim/c2c.js';
+import { resolveOpenagentChannelRuntime } from './plugin-runtime.js';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { processOneMessage } from '../messaging/process-message.js';
+import { processC2CRequest } from '../messaging/process-c2c-request.js';
+import { createTransport } from '../transport/factory.js';
+import { isUnconfiguredOasnApiBase } from '../auth/config.js';
+export class AccountRuntime {
+    accountId;
+    // Sub-modules (accessible by tools via registry)
+    store = null;
+    client = null;
+    /**
+     * v3.9+ 双轨抽象：统一 transport 接口。
+     *
+     *   - transport='tim' 下：内部仍持有 TIMClient（this.client）作为 SDK 直连；
+     *     transport 实例额外提供能力接口，便于阶段 4 上层调用
+     *   - transport='oasn' 下：this.client 始终为 null，所有调用走 transport
+     *
+     * 阶段 4 完成后，上层将不再直接访问 this.client，只使用 this.transport。
+     */
+    transport = null;
+    credentialManager = null;
+    _transportType = 'oasn';
+    _claimStatus = 'unknown';
+    _claimUrl = '';
+    _claimExpiresAt = '';
+    _caAccessToken;
+    _statusPollTimer = null;
+    _running = false;
+    _config = null;
+    _cfg = null;
+    _connectingPromise = null;
+    constructor(accountId) {
+        this.accountId = accountId;
+    }
+    get isRunning() { return this._running; }
+    get config() { return this._config; }
+    /** v3.9+ 当前账号选择的 transport 类型（'oasn' | 'tim'） */
+    get transportType() { return this._transportType; }
+    get claimStatus() { return this._claimStatus; }
+    get claimUrl() { return this._claimUrl; }
+    get claimExpiresAt() { return this._claimExpiresAt; }
+    get caAccessToken() { return this._caAccessToken; }
+    get isOasnClaimed() { return this._transportType !== 'oasn' || this._claimStatus === 'claimed'; }
+    /**
+     * Account startup with half-alive support.
+     *
+     * If agent is claimed: full startup (StateStore + TIM + pipeline).
+     * If agent is unclaimed: half-alive (StateStore only, _running = true).
+     *   Tools will trigger lazy connection via ensureConnected().
+     *
+     * IMPORTANT: This method NEVER throws for unclaimed/credential errors.
+     * It must return normally so channel.ts reaches the blocking await Promise,
+     * preventing OpenClaw auto-restart.
+     *
+     * @param cfg - Full OpenClaw config object, needed for channelRuntime APIs
+     */
+    async start(account, _pipelineConfig, cfg) {
+        this._config = account;
+        this._cfg = cfg || {};
+        this._transportType = account.transport;
+        this._claimStatus = account.status;
+        this._claimUrl = account.claimUrl;
+        try {
+            // ── Phase 1: StateStore (always) ──
+            logger.info(`[runtime] Starting account '${this.accountId}': init StateStore`);
+            this.store = new StateStore();
+            await this.store.init(this.accountId);
+            // ── Phase 2: 按 transport 分发凭证管理 ──
+            // OASN 路径：api_key 直接作为 Bearer，不走 CredentialManager（无缓存/冷却）。
+            // TIM  路径：保留原有 CredentialManager（apiKey → auth.ai-talk.live → UserSig）。
+            if (this._transportType === 'tim') {
+                this.credentialManager = new CredentialManager(account.agentId, account.apiKey);
+                logger.info(`[runtime] CredentialManager created for agent ${account.agentId} (transport=tim)`);
+            }
+            else {
+                logger.info(`[runtime] transport=oasn: skipping CredentialManager (api_key used as Bearer directly)`);
+            }
+            // ── Phase 3: 建立 transport 连接 ──
+            try {
+                if (this._transportType === 'oasn') {
+                    await this._connectOASN();
+                    logger.info(`[runtime] Account '${this.accountId}' started: OASN transport ready`);
+                }
+                else {
+                    await this._connectTIM();
+                    logger.info(`[runtime] Account '${this.accountId}' started: fully connected (transport=tim)`);
+                }
+            }
+            catch (err) {
+                if (err instanceof CredentialError) {
+                    // Unclaimed or cooldown: enter half-alive state（仅 TIM）
+                    logger.warn(`[runtime] Account '${this.accountId}' started in half-alive mode (${err.reason}: ${err.message})`);
+                }
+                else {
+                    // Unexpected error during connect: still go half-alive, don't crash
+                    logger.error(`[runtime] Account '${this.accountId}' transport connect failed, entering half-alive: ${err.message}`);
+                }
+            }
+            this._running = true;
+        }
+        catch (err) {
+            // Only StateStore init failure reaches here
+            logger.error(`[runtime] Account '${this.accountId}' start failed: ${err.message}`);
+            await this._cleanup();
+            throw err;
+        }
+    }
+    /**
+     * OASN 连接路径（v3.9+）。
+     *
+     * 与 _connectTIM 不同：
+     *   - 无 WebSocket，ready() 只校验 api_key 有效性（GET /api/agent-cards/{agent_id}）
+     *   - 不需要 channelRuntime 接管 'message' / 'c2c_request' 事件（OASN ClientAgent 不接收外来 Invocation）
+     *   - 'credential_expired' 事件由 OasnTransport 在 401 时触发，处理：清 transport + 标记 half-alive
+     */
+    async _connectOASN() {
+        if (!this._config)
+            throw new Error('Account config not set');
+        if (!this.store)
+            throw new Error('StateStore not initialized');
+        logger.info(`[runtime] Connecting OASN transport for ${this.accountId} `
+            + `api_base=${this._config.apiBase} access_api_base=${this._config.accessApiBase}`);
+        if (isUnconfiguredOasnApiBase(this._config.apiBase)) {
+            throw new Error('OASN api_base is not configured; set channels.openagent.api_base or accounts.default.api_base');
+        }
+        // §11.1：把 StateStore 包装成 PendingInvocationStore，注入到 OasnTransport。
+        // 这样 sendTask 时会按 toolCallId 在 SQLite 里查/写 idempotency_key 与 invocation_id，
+        // 进程崩溃重启后 listUnsettledInvocations() 可定位未结调用做续轮询。
+        const pendingStore = createPendingInvocationStore(this.store);
+        const transport = await createTransport({
+            transportType: 'oasn',
+            apiBase: this._config.apiBase,
+            accessApiBase: this._config.accessApiBase,
+            agentId: this._config.agentId,
+            accountId: this.accountId,
+            pendingStore,
+        });
+        // §11.5 凭证撤销路径
+        transport.on('credential_expired', () => {
+            logger.error(`[runtime] OASN credential_expired for ${this.accountId} - clearing transport`);
+            // 不直接清 config 里的 api_key —— 持久层清理由上层（plugin-ui / register 工具）决定
+            // 但本地 transport 已不可用，标记为待重连
+            this.transport = null;
+            this._claimStatus = 'credential_expired';
+            this._caAccessToken = undefined;
+            this._stopOasnStatusPolling();
+            this._saveOasnAccountConfig({ status: 'credential_expired' });
+        });
+        // 拼装 OASN 凭证：identity=agent_id, token=api_key, expiresAt=0（不过期）。
+        // 首次注册由 openclaw-plugin-openagent-cli 安装器负责；runtime 不创建新 ClientAgent。
+        const agentId = this._config.agentId;
+        const apiKey = this._config.apiKey;
+        if (!agentId || !apiKey) {
+            throw new Error('OASN account is not configured; run openclaw-plugin-openagent-cli install to register this device');
+        }
+        const creds = {
+            identity: agentId,
+            token: apiKey,
+            expiresAt: 0,
+        };
+        await transport.ready(creds);
+        await this._syncOasnStatus(transport);
+        this._scheduleOasnStatusPolling(transport);
+        // §11.1 持久化已通过 factory 的 pendingStore 注入完成 —— OasnInvocation 内部在
+        // sendTask/waitForTaskResult 流程里直接读写 store，AccountRuntime 这一层无需再介入。
+        // （原先将 createPendingInvocationStore 作为 TODO 留在外部组合，阶段 4 已收敛到工厂）
+        this.transport = transport;
+    }
+    /**
+     * 将 OASN 账号状态持久化到 OpenClaw 配置文件。
+     *
+     * 写入位置：~/.openclaw/openclaw.json → channels.openagent.accounts.{accountId}
+     * 采用 merge 策略。CA access_token 永远只留在 runtime 内存，不写入配置。
+     */
+    _saveOasnAccountConfig(updates) {
+        try {
+            const configPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+            if (!fs.existsSync(configPath)) {
+                logger.warn(`[runtime] Config file not found: ${configPath}, skipping credential persistence`);
+                return;
+            }
+            const raw = fs.readFileSync(configPath, 'utf-8');
+            const cfg = JSON.parse(raw);
+            // 确保路径存在：channels.openagent.accounts.{accountId}
+            cfg.channels = cfg.channels || {};
+            cfg.channels.openagent = cfg.channels.openagent || {};
+            cfg.channels.openagent.accounts = cfg.channels.openagent.accounts || {};
+            const accId = this._config?.accountId || 'default';
+            cfg.channels.openagent.accounts[accId] = cfg.channels.openagent.accounts[accId] || {};
+            const acc = cfg.channels.openagent.accounts[accId];
+            for (const [key, value] of Object.entries(updates)) {
+                if (value === undefined || key === 'access_token' || key === 'accessToken' || key === 'agent_card')
+                    continue;
+                acc[key] = value;
+            }
+            fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+            logger.info(`[runtime] OASN account config persisted to ${configPath} (keys=${Object.keys(updates).join(',')})`);
+        }
+        catch (err) {
+            logger.warn(`[runtime] Failed to persist OASN account config: ${err.message}`);
+        }
+    }
+    async _syncOasnStatus(transport) {
+        const agentId = this._config?.agentId;
+        if (!agentId)
+            return null;
+        const status = await transport.getAgentStatus(agentId);
+        this._claimStatus = status.status;
+        this._caAccessToken = status.access_token;
+        this._config = this._config
+            ? { ...this._config, status: status.status }
+            : this._config;
+        this._saveOasnAccountConfig({ status: status.status });
+        logger.info(`[runtime] OASN status synced: agent_id=${agentId} status=${status.status} access_token=${status.access_token ? 'present' : 'absent'}`);
+        return status;
+    }
+    _scheduleOasnStatusPolling(transport) {
+        this._stopOasnStatusPolling();
+        if (this._transportType !== 'oasn' || this._claimStatus === 'claimed' || this._claimStatus === 'credential_expired') {
+            return;
+        }
+        this._statusPollTimer = setTimeout(() => {
+            void this._syncOasnStatus(transport)
+                .then(() => {
+                if (this._claimStatus !== 'claimed' && this._claimStatus !== 'credential_expired' && this.transport === transport) {
+                    this._scheduleOasnStatusPolling(transport);
+                }
+            })
+                .catch((err) => {
+                logger.warn(`[runtime] OASN status polling failed: ${err.message}`);
+                if (this.transport === transport)
+                    this._scheduleOasnStatusPolling(transport);
+            });
+        }, 30_000);
+    }
+    _stopOasnStatusPolling() {
+        if (!this._statusPollTimer)
+            return;
+        clearTimeout(this._statusPollTimer);
+        this._statusPollTimer = null;
+    }
+    assertOasnInvocationAllowed() {
+        if (this._transportType === 'oasn' && this._claimStatus !== 'claimed') {
+            throw new Error(`OASN ClientAgent is not claimed yet (status=${this._claimStatus}). Complete claim before calling remote agents.`);
+        }
+    }
+    /**
+     * Connect TIM and wire the channelRuntime dispatch pipeline.
+     * Called by start() and ensureConnected().
+     */
+    async _connectTIM() {
+        if (!this.credentialManager)
+            throw new Error('CredentialManager not initialized');
+        if (!this._config)
+            throw new Error('Account config not set');
+        const credentials = await this.credentialManager.getCredentials();
+        logger.info(`[runtime] Connecting TIM SDK for ${this.accountId}`);
+        this.client = new TIMClient();
+        await this.client.connect(credentials);
+        // Initialize C2C message handler for remote agent communication
+        initC2CHandler(this.client);
+        // Listen for UserSig expiry
+        this.client.on('credential_expired', () => {
+            logger.warn(`[runtime] Received credential_expired for ${this.accountId}, invalidating + reconnecting`);
+            this.credentialManager.invalidate();
+            // Attempt to reconnect with fresh credentials
+            void this._connectTIM().catch((err) => {
+                logger.error(`[runtime] Reconnect after UserSig expiry failed: ${err.message}`);
+            });
+        });
+        // ── channelRuntime dispatch pipeline ──
+        // Replaces: Collector → Aggregator → Scheduler → Executor (shell-out)
+        // With:     processOneMessage → channelRuntime.reply.dispatchReplyFromConfig
+        try {
+            const channelRuntime = await resolveOpenagentChannelRuntime({});
+            this.client.on('message', (rawMsg) => {
+                void processOneMessage(rawMsg, {
+                    accountId: this.accountId,
+                    selfUserId: this.client.agentId,
+                    config: this._cfg || {},
+                    channelRuntime,
+                    sendMessage: async (chId, text, atUserList) => {
+                        await messages.sendMessage(this.client, chId, text, atUserList);
+                    },
+                    getChannelSkill: async (chId) => {
+                        return channels.getChannelSkill(this.client, chId);
+                    },
+                    getGroupName: async (chId) => {
+                        return channels.getGroupName(this.client, chId);
+                    },
+                    getGroupCustomField: async (chId, key) => {
+                        return channels.getGroupCustomField(this.client, chId, key);
+                    },
+                    getGroupMembers: async (chId) => {
+                        const members = await channels.getMembers(this.client, chId);
+                        return members.map(m => ({ id: m.id, nick: m.nick }));
+                    },
+                    log: logger,
+                }).catch((err) => {
+                    logger.error(`[runtime] processOneMessage failed: ${err.message}`);
+                });
+            });
+            // ── C2C remote agent request handler (T3) ──
+            // When another agent sends a task request via C2C, dispatch it through
+            // the same channelRuntime pipeline. Mirrors the 'message' listener above.
+            // @see docs/products/orchestrator/specs/T3-remote-handler.md
+            this.client.on('c2c_request', (event) => {
+                void processC2CRequest(event, {
+                    accountId: this.accountId,
+                    selfUserId: this.client.agentId,
+                    config: this._cfg || {},
+                    channelRuntime,
+                }).catch((err) => {
+                    logger.error(`[runtime] processC2CRequest failed: ${err.message}`);
+                });
+            });
+            logger.info(`[runtime] TIM connected + channelRuntime pipeline wired for ${this.accountId}`);
+        }
+        catch (err) {
+            // channelRuntime resolution failed — fall through to half-alive
+            // TIM is connected but AI dispatch won't work
+            logger.error(`[runtime] channelRuntime resolution failed: ${err.message}`);
+            logger.warn(`[runtime] TIM connected but AI dispatch unavailable for ${this.accountId}`);
+        }
+    }
+    /**
+     * Ensure TIM is connected before executing a tool operation.
+     * If not connected, attempts lazy connection.
+     *
+     * v3.9+：OASN 路径下走 _connectOASN()；TIM 路径维持原行为。
+     *
+     * @throws CredentialError — propagated to tool, which returns a user-friendly message
+     */
+    async ensureConnected() {
+        if (this._transportType === 'oasn') {
+            if (this.transport?.isReady)
+                return;
+            if (this._connectingPromise) {
+                logger.debug(`[runtime] ensureConnected: waiting for in-progress OASN connection`);
+                return this._connectingPromise;
+            }
+            logger.info(`[runtime] ensureConnected: OASN transport not ready, initiating lazy connect for ${this.accountId}`);
+            this._connectingPromise = this._connectOASN();
+            try {
+                await this._connectingPromise;
+            }
+            finally {
+                this._connectingPromise = null;
+            }
+            return;
+        }
+        // TIM 路径（原逻辑保留）
+        if (this.client?.isReady)
+            return;
+        // Prevent concurrent connect attempts
+        if (this._connectingPromise) {
+            logger.debug(`[runtime] ensureConnected: waiting for in-progress connection`);
+            return this._connectingPromise;
+        }
+        logger.info(`[runtime] ensureConnected: TIM not ready, initiating lazy connect for ${this.accountId}`);
+        this._connectingPromise = this._connectTIM();
+        try {
+            await this._connectingPromise;
+        }
+        finally {
+            this._connectingPromise = null;
+        }
+    }
+    /**
+     * Graceful shutdown of all modules.
+     */
+    async stop() {
+        logger.info(`[runtime] Stopping account '${this.accountId}'`);
+        await this._cleanup();
+        logger.info(`[runtime] Account '${this.accountId}' stopped`);
+    }
+    async _cleanup() {
+        this._running = false;
+        this._stopOasnStatusPolling();
+        if (this.client) {
+            await this.client.disconnect();
+            this.client = null;
+        }
+        if (this.transport) {
+            try {
+                await this.transport.dispose();
+            }
+            catch (err) {
+                logger.warn(`[runtime] transport.dispose error: ${err.message}`);
+            }
+            this.transport = null;
+        }
+        if (this.store) {
+            this.store.close();
+            this.store = null;
+        }
+    }
+    // ── Strategy + status queries (used by ops-tools) ──
+    /**
+     * @deprecated Pipeline batching is now handled by channelRuntime.
+     * Retained for backward compatibility with openagent_set_strategy tool.
+     */
+    updateStrategy(_config) {
+        logger.debug('[runtime] updateStrategy called (no-op: batching handled by channelRuntime)');
+        return {
+            batchWindowMs: _config.batchWindowMs || 20_000,
+            maxBatchSize: _config.maxBatchSize || 20,
+        };
+    }
+    /**
+     * @deprecated Scheduler queue no longer exists in channelRuntime mode.
+     */
+    get schedulerQueueSize() {
+        return 0;
+    }
+    // ── Delegated SDK operations (used by tools) ──
+    // All operations go through ensureConnected() for lazy connection.
+    async listChannels() {
+        await this.ensureConnected();
+        return channels.listChannels(this.client);
+    }
+    async searchChannels(keyword) {
+        await this.ensureConnected();
+        return channels.searchChannels(this.client, keyword);
+    }
+    async joinChannel(channelId) {
+        await this.ensureConnected();
+        return channels.joinChannel(this.client, channelId);
+    }
+    async leaveChannel(channelId) {
+        await this.ensureConnected();
+        return channels.leaveChannel(this.client, channelId);
+    }
+    async getMembers(channelId) {
+        await this.ensureConnected();
+        return channels.getMembers(this.client, channelId);
+    }
+    async createChannel(name, description, skill) {
+        await this.ensureConnected();
+        return channels.createChannel(this.client, name, description, skill);
+    }
+    async getChannelSkill(channelId) {
+        await this.ensureConnected();
+        return channels.getChannelSkill(this.client, channelId);
+    }
+    async setChannelSkill(channelId, skill) {
+        await this.ensureConnected();
+        return channels.setChannelSkill(this.client, channelId, skill);
+    }
+    async sendMessage(channelId, text) {
+        await this.ensureConnected();
+        return messages.sendMessage(this.client, channelId, text);
+    }
+    async fetchMessages(channelId, count) {
+        await this.ensureConnected();
+        return messages.fetchMessages(this.client, channelId, count);
+    }
+}

package/dist/src/runtime/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runtime — Module barrel export
+ */
+export { RuntimeRegistry, registry } from './registry.js';
+export { AccountRuntime } from './account.js';

package/dist/src/runtime/index.js

@@ -0,0 +1,6 @@
+/**
+ * Runtime — Module barrel export
+ */
+export { RuntimeRegistry, registry } from './registry.js';
+export { AccountRuntime } from './account.js';
+// guard.ts removed — unhandled rejections fixed at source in ws-frame.ts

package/dist/src/runtime/plugin-runtime.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Plugin Runtime — channelRuntime acquisition and readiness gate
+ *
+ * Mirrors the pattern established by openclaw-weixin v2.1.1 runtime.ts:
+ *   1. register() stores the PluginRuntime via setOpenagentPluginRuntime()
+ *   2. startAccount() resolves channelRuntime via resolveOpenagentChannelRuntime()
+ *      with a three-level fallback: ctx-injected → global → async wait
+ *
+ * Reference: docs/reference/plugins/openclaw-weixin/src/runtime.ts
+ */
+import type { PluginRuntime } from 'openclaw/plugin-sdk/core';
+export type PluginChannelRuntime = PluginRuntime['channel'];
+/**
+ * Store the PluginRuntime received during register().
+ * Called once from index.ts register().
+ */
+export declare function setOpenagentPluginRuntime(next: PluginRuntime): void;
+/**
+ * Synchronous getter — throws if not initialized.
+ * Use only when you are certain register() has completed.
+ */
+export declare function getOpenagentPluginRuntime(): PluginRuntime;
+/**
+ * Async polling wait for the runtime to become available.
+ * Used during startAccount() if register() hasn't completed yet.
+ */
+export declare function waitForOpenagentPluginRuntime(timeoutMs?: number): Promise<PluginRuntime>;
+/**
+ * Resolve PluginRuntime['channel'] with three-level fallback:
+ *
+ *   1. Gateway-injected channelRuntime on ctx (new OpenClaw versions)
+ *   2. Module-global from register()
+ *   3. Async wait for register() to complete
+ *
+ * This matches openclaw-weixin's resolveWeixinChannelRuntime() exactly.
+ */
+export declare function resolveOpenagentChannelRuntime(params: {
+    channelRuntime?: PluginChannelRuntime;
+    waitTimeoutMs?: number;
+}): Promise<PluginChannelRuntime>;

package/dist/src/runtime/plugin-runtime.js

@@ -0,0 +1,72 @@
+/**
+ * Plugin Runtime — channelRuntime acquisition and readiness gate
+ *
+ * Mirrors the pattern established by openclaw-weixin v2.1.1 runtime.ts:
+ *   1. register() stores the PluginRuntime via setOpenagentPluginRuntime()
+ *   2. startAccount() resolves channelRuntime via resolveOpenagentChannelRuntime()
+ *      with a three-level fallback: ctx-injected → global → async wait
+ *
+ * Reference: docs/reference/plugins/openclaw-weixin/src/runtime.ts
+ */
+import { logger } from '../util/logger.js';
+// ── Module-level singleton ──
+let pluginRuntime = null;
+// ── Public API ──
+/**
+ * Store the PluginRuntime received during register().
+ * Called once from index.ts register().
+ */
+export function setOpenagentPluginRuntime(next) {
+    pluginRuntime = next;
+    logger.info('[plugin-runtime] setOpenagentPluginRuntime called, runtime set');
+}
+/**
+ * Synchronous getter — throws if not initialized.
+ * Use only when you are certain register() has completed.
+ */
+export function getOpenagentPluginRuntime() {
+    if (!pluginRuntime) {
+        throw new Error('OpenAgent PluginRuntime not initialized');
+    }
+    return pluginRuntime;
+}
+// ── Async wait ──
+const WAIT_INTERVAL_MS = 100;
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Async polling wait for the runtime to become available.
+ * Used during startAccount() if register() hasn't completed yet.
+ */
+export async function waitForOpenagentPluginRuntime(timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const start = Date.now();
+    while (!pluginRuntime) {
+        if (Date.now() - start > timeoutMs) {
+            throw new Error('OpenAgent PluginRuntime initialization timeout');
+        }
+        await new Promise((resolve) => setTimeout(resolve, WAIT_INTERVAL_MS));
+    }
+    return pluginRuntime;
+}
+// ── Three-level fallback resolver ──
+/**
+ * Resolve PluginRuntime['channel'] with three-level fallback:
+ *
+ *   1. Gateway-injected channelRuntime on ctx (new OpenClaw versions)
+ *   2. Module-global from register()
+ *   3. Async wait for register() to complete
+ *
+ * This matches openclaw-weixin's resolveWeixinChannelRuntime() exactly.
+ */
+export async function resolveOpenagentChannelRuntime(params) {
+    if (params.channelRuntime) {
+        logger.debug('[plugin-runtime] channelRuntime from gateway context');
+        return params.channelRuntime;
+    }
+    if (pluginRuntime) {
+        logger.debug('[plugin-runtime] channelRuntime from register() global');
+        return pluginRuntime.channel;
+    }
+    logger.warn('[plugin-runtime] no channelRuntime on ctx and no global runtime yet; waiting for register()');
+    const pr = await waitForOpenagentPluginRuntime(params.waitTimeoutMs ?? DEFAULT_TIMEOUT_MS);
+    return pr.channel;
+}

package/dist/src/runtime/registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * RuntimeRegistry — Strict single-active-account enforcement
+ *
+ * Prevents concurrent accounts from running.
+ * Registry.register() throws if another account is already active.
+ * This replaces the old shared.js singleton pattern.
+ *
+ * See §1.1 of refactoring-plan.md.
+ */
+import type { AccountRuntime } from './account.js';
+export declare class RuntimeRegistry {
+    private _active;
+    /**
+     * Register an AccountRuntime as the active instance.
+     * @throws Error if another account is already active
+     */
+    register(runtime: AccountRuntime): void;
+    /**
+     * Unregister the active runtime.
+     */
+    unregister(runtime: AccountRuntime): void;
+    /**
+     * Get the currently active runtime.
+     * Returns null if no account is running.
+     */
+    getActive(): AccountRuntime | null;
+    /**
+     * Get the default (only) runtime.
+     * In single-active-account mode, this is the same as getActive().
+     */
+    getDefault(): AccountRuntime | null;
+    /**
+     * Check if any account is currently running.
+     */
+    hasActive(): boolean;
+}
+/**
+ * Global registry instance.
+ * Shared by channel adapter, tools, and hooks.
+ */
+export declare const registry: RuntimeRegistry;