openclaw-openagent 1.0.0 → 1.0.2

package/dist/src/state/store.js

@@ -0,0 +1,535 @@
+/**
+ * State Store — SQLite persistence via sql.js (pure WASM)
+ *
+ * Persists channel state and message dedup records.
+ * sql.js operates in-memory; explicit persist() writes to disk.
+ * No native compilation needed (unlike better-sqlite3).
+ *
+ * v3: All tables use (account_id, channel_id) composite key.
+ * See §0.4 of refactoring-plan.md for field semantics.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { logger } from '../util/logger.js';
+const DB_PATH = path.join(os.homedir(), '.openclaw', 'openagent.db');
+// ── StateStore ──
+export class StateStore {
+    db = null;
+    accountId = 'default';
+    _seenCount = 0;
+    /**
+     * Initialize the SQLite database.
+     * Must be called before any other methods.
+     *
+     * @param currentAccountId - The account ID of the currently starting account.
+     *   Used for schema migration: old data without account_id will be assigned this ID.
+     */
+    async init(currentAccountId) {
+        this.accountId = currentAccountId || 'default';
+        const initSqlJs = (await import('sql.js')).default;
+        const SQL = await initSqlJs();
+        // Load existing DB file if present
+        if (fs.existsSync(DB_PATH)) {
+            const buffer = fs.readFileSync(DB_PATH);
+            this.db = new SQL.Database(buffer);
+        }
+        else {
+            this.db = new SQL.Database();
+        }
+        this._migrate();
+        return this;
+    }
+    _migrate() {
+        if (!this.db)
+            return;
+        // Detect old schema (no account_id column)
+        const hasAccountId = this._tableHasColumn('channel_state', 'account_id');
+        if (hasAccountId) {
+            // Already v3 schema — ensure all tables exist
+            this._createV3Tables();
+        }
+        else {
+            // Old v2 schema detected — migrate
+            this._migrateFromV2();
+        }
+    }
+    _tableHasColumn(table, column) {
+        if (!this.db)
+            return false;
+        try {
+            const stmt = this.db.prepare(`PRAGMA table_info(${table})`);
+            while (stmt.step()) {
+                const row = stmt.getAsObject();
+                if (row['name'] === column) {
+                    stmt.free();
+                    return true;
+                }
+            }
+            stmt.free();
+        }
+        catch {
+            // Table doesn't exist
+        }
+        return false;
+    }
+    _tableExists(table) {
+        if (!this.db)
+            return false;
+        try {
+            const stmt = this.db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`);
+            stmt.bind([table]);
+            const exists = stmt.step();
+            stmt.free();
+            return exists;
+        }
+        catch {
+            return false;
+        }
+    }
+    _migrateFromV2() {
+        if (!this.db)
+            return;
+        logger.info(`[state] Migrating v2 schema to v3 (account_id='${this.accountId}')`);
+        // 1. Rename old tables
+        if (this._tableExists('channel_state')) {
+            this.db.run('ALTER TABLE channel_state RENAME TO _v2_channel_state');
+        }
+        if (this._tableExists('seen_messages')) {
+            this.db.run('ALTER TABLE seen_messages RENAME TO _v2_seen_messages');
+        }
+        if (this._tableExists('channel_skills')) {
+            this.db.run('ALTER TABLE channel_skills RENAME TO _v2_channel_skills');
+        }
+        if (this._tableExists('channel_purpose')) {
+            this.db.run('ALTER TABLE channel_purpose RENAME TO _v2_channel_purpose');
+        }
+        // 2. Create v3 tables
+        this._createV3Tables();
+        // 3. Copy old data with current account_id
+        if (this._tableExists('_v2_channel_state')) {
+            this.db.run(`
+        INSERT INTO channel_state (account_id, channel_id, channel_name, joined, last_visit, last_reply, last_msg_seq, created_at, updated_at)
+        SELECT ?, channel_id, channel_name, joined, last_visit, last_reply, last_msg_seq, created_at, updated_at
+        FROM _v2_channel_state
+      `, [this.accountId]);
+        }
+        if (this._tableExists('_v2_seen_messages')) {
+            this.db.run(`
+        INSERT INTO seen_messages (account_id, message_id, channel_id, seen_at)
+        SELECT ?, message_id, channel_id, seen_at
+        FROM _v2_seen_messages
+      `, [this.accountId]);
+        }
+        if (this._tableExists('_v2_channel_skills')) {
+            this.db.run(`
+        INSERT INTO channel_skills (account_id, channel_id, skill_content, updated_at)
+        SELECT ?, channel_id, skill_content, updated_at
+        FROM _v2_channel_skills
+      `, [this.accountId]);
+        }
+        if (this._tableExists('_v2_channel_purpose')) {
+            this.db.run(`
+        INSERT INTO channel_purpose (account_id, channel_id, purpose, updated_at)
+        SELECT ?, channel_id, purpose, updated_at
+        FROM _v2_channel_purpose
+      `, [this.accountId]);
+        }
+        // 4. Drop old tables
+        this.db.run('DROP TABLE IF EXISTS _v2_channel_state');
+        this.db.run('DROP TABLE IF EXISTS _v2_seen_messages');
+        this.db.run('DROP TABLE IF EXISTS _v2_channel_skills');
+        this.db.run('DROP TABLE IF EXISTS _v2_channel_purpose');
+        this.persist();
+        logger.info('[state] Migration complete');
+    }
+    _createV3Tables() {
+        if (!this.db)
+            return;
+        this.db.run(`
+      CREATE TABLE IF NOT EXISTS channel_state (
+        account_id   TEXT NOT NULL,
+        channel_id   TEXT NOT NULL,
+        channel_name TEXT NOT NULL DEFAULT '',
+        joined       INTEGER NOT NULL DEFAULT 0,
+        last_visit   INTEGER NOT NULL DEFAULT 0,
+        last_reply   INTEGER NOT NULL DEFAULT 0,
+        last_msg_seq INTEGER NOT NULL DEFAULT 0,
+        created_at   INTEGER NOT NULL DEFAULT 0,
+        updated_at   INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (account_id, channel_id)
+      )
+    `);
+        this.db.run(`
+      CREATE TABLE IF NOT EXISTS seen_messages (
+        account_id TEXT NOT NULL,
+        message_id TEXT NOT NULL,
+        channel_id TEXT NOT NULL,
+        seen_at    INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (account_id, message_id)
+      )
+    `);
+        this.db.run(`
+      CREATE TABLE IF NOT EXISTS channel_skills (
+        account_id    TEXT NOT NULL,
+        channel_id    TEXT NOT NULL,
+        skill_content TEXT NOT NULL DEFAULT '',
+        updated_at    INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (account_id, channel_id)
+      )
+    `);
+        this.db.run(`
+      CREATE TABLE IF NOT EXISTS channel_purpose (
+        account_id TEXT NOT NULL,
+        channel_id TEXT NOT NULL,
+        purpose    TEXT NOT NULL DEFAULT '',
+        updated_at INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (account_id, channel_id)
+      )
+    `);
+        // §11.1 OASN invocation 幂等持久化。
+        // tool_call_id 作为主键 —— 它对应 LLM 一次工具调用，全局唯一。
+        // status 索引便于启动时筛非终态记录续轮询。
+        this.db.run(`
+      CREATE TABLE IF NOT EXISTS pending_invocations (
+        account_id      TEXT NOT NULL,
+        tool_call_id    TEXT NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        invocation_id   TEXT,
+        session_id      TEXT,
+        target_agent_id TEXT,
+        status          TEXT NOT NULL DEFAULT 'pending',
+        created_at      INTEGER NOT NULL DEFAULT 0,
+        updated_at      INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (account_id, tool_call_id)
+      )
+    `);
+        this.db.run(`
+      CREATE INDEX IF NOT EXISTS idx_pending_invocations_status
+      ON pending_invocations (account_id, status)
+    `);
+        this.db.run(`
+      CREATE INDEX IF NOT EXISTS idx_pending_invocations_invocation
+      ON pending_invocations (account_id, invocation_id)
+    `);
+    }
+    // ── Write to disk ──
+    persist() {
+        try {
+            if (!this.db)
+                return;
+            const data = this.db.export();
+            fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
+            fs.writeFileSync(DB_PATH, Buffer.from(data));
+        }
+        catch (err) {
+            logger.error(`[state] persist error: ${err.message}`);
+        }
+    }
+    // ── Channel State ──
+    /**
+     * Get all joined channels for the current account.
+     */
+    getJoinedChannels() {
+        if (!this.db)
+            return [];
+        const stmt = this.db.prepare('SELECT * FROM channel_state WHERE account_id = ? AND joined = 1');
+        stmt.bind([this.accountId]);
+        const results = [];
+        while (stmt.step())
+            results.push(stmt.getAsObject());
+        stmt.free();
+        return results;
+    }
+    getJoinedChannelIds() {
+        return this.getJoinedChannels().map(c => c.channel_id);
+    }
+    getChannel(channelId) {
+        if (!this.db)
+            return null;
+        const stmt = this.db.prepare('SELECT * FROM channel_state WHERE account_id = ? AND channel_id = ?');
+        stmt.bind([this.accountId, channelId]);
+        const result = stmt.step() ? stmt.getAsObject() : null;
+        stmt.free();
+        return result;
+    }
+    /**
+     * Mark a channel as joined.
+     * Authoritative writer: openagent_join_channel tool (on success).
+     */
+    markJoined(channelId, channelName) {
+        if (!this.db)
+            return;
+        const now = Date.now();
+        this.db.run(`INSERT INTO channel_state (account_id, channel_id, channel_name, joined, last_visit, created_at, updated_at)
+       VALUES (?, ?, ?, 1, ?, ?, ?)
+       ON CONFLICT(account_id, channel_id) DO UPDATE SET joined=1, channel_name=?, updated_at=?`, [this.accountId, channelId, channelName || '', now, now, now, channelName || '', now]);
+        this.persist();
+    }
+    /**
+     * Mark a channel as left.
+     * Authoritative writer: openagent_leave_channel tool (on success).
+     */
+    markLeft(channelId) {
+        if (!this.db)
+            return;
+        this.db.run('UPDATE channel_state SET joined=0, updated_at=? WHERE account_id=? AND channel_id=?', [Date.now(), this.accountId, channelId]);
+        this.persist();
+    }
+    /**
+     * Update last_visit timestamp for a channel.
+     * Authoritative writer: Collector — on ingest() accepting a message.
+     */
+    updateLastVisit(channelId) {
+        if (!this.db)
+            return;
+        const now = Date.now();
+        this.db.run('UPDATE channel_state SET last_visit=?, updated_at=? WHERE account_id=? AND channel_id=?', [now, now, this.accountId, channelId]);
+        this.persist();
+    }
+    /**
+     * Update last_reply timestamp for a channel.
+     * Authoritative writer: openagent_send_message tool — on sendMessage() success.
+     */
+    updateLastReply(channelId) {
+        if (!this.db)
+            return;
+        const now = Date.now();
+        this.db.run('UPDATE channel_state SET last_reply=?, updated_at=? WHERE account_id=? AND channel_id=?', [now, now, this.accountId, channelId]);
+        this.persist();
+    }
+    /**
+     * Update last_msg_seq for a channel.
+     * Authoritative writer: Collector — on ingest() taking msg.sequence.
+     */
+    updateLastMsgSeq(channelId, seq) {
+        if (!this.db)
+            return;
+        this.db.run('UPDATE channel_state SET last_msg_seq=?, updated_at=? WHERE account_id=? AND channel_id=?', [seq, Date.now(), this.accountId, channelId]);
+        this.persist();
+    }
+    // ── Message Dedup (Collector use) ──
+    hasSeen(messageId) {
+        if (!this.db)
+            return false;
+        const stmt = this.db.prepare('SELECT 1 FROM seen_messages WHERE account_id=? AND message_id=?');
+        stmt.bind([this.accountId, messageId]);
+        const found = stmt.step();
+        stmt.free();
+        return found;
+    }
+    markSeen(messageId, channelId) {
+        if (!this.db)
+            return;
+        this.db.run('INSERT OR IGNORE INTO seen_messages (account_id, message_id, channel_id, seen_at) VALUES (?, ?, ?, ?)', [this.accountId, messageId, channelId, Date.now()]);
+        // Batch persist: seen_messages are written frequently
+        this._seenCount += 1;
+        if (this._seenCount % 100 === 0)
+            this.persist();
+    }
+    // ── Channel Skills ──
+    getSkill(channelId) {
+        if (!this.db)
+            return null;
+        const stmt = this.db.prepare('SELECT skill_content FROM channel_skills WHERE account_id = ? AND channel_id = ?');
+        stmt.bind([this.accountId, channelId]);
+        const result = stmt.step() ? stmt.getAsObject() : null;
+        stmt.free();
+        return result?.['skill_content'] || null;
+    }
+    setSkill(channelId, skillContent) {
+        if (!this.db)
+            return;
+        const now = Date.now();
+        this.db.run(`INSERT INTO channel_skills (account_id, channel_id, skill_content, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(account_id, channel_id) DO UPDATE SET skill_content=?, updated_at=?`, [this.accountId, channelId, skillContent, now, skillContent, now]);
+        this.persist();
+    }
+    getAllSkills() {
+        if (!this.db)
+            return [];
+        const stmt = this.db.prepare('SELECT channel_id, skill_content FROM channel_skills WHERE account_id = ?');
+        stmt.bind([this.accountId]);
+        const results = [];
+        while (stmt.step()) {
+            const row = stmt.getAsObject();
+            results.push({
+                channel_id: row['channel_id'],
+                skill_content: row['skill_content'],
+            });
+        }
+        stmt.free();
+        return results;
+    }
+    // ── Channel Purpose ──
+    getPurpose(channelId) {
+        if (!this.db)
+            return null;
+        const stmt = this.db.prepare('SELECT purpose FROM channel_purpose WHERE account_id = ? AND channel_id = ?');
+        stmt.bind([this.accountId, channelId]);
+        const result = stmt.step() ? stmt.getAsObject() : null;
+        stmt.free();
+        return result?.['purpose'] || null;
+    }
+    setPurpose(channelId, purpose) {
+        if (!this.db)
+            return;
+        const now = Date.now();
+        this.db.run(`INSERT INTO channel_purpose (account_id, channel_id, purpose, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(account_id, channel_id) DO UPDATE SET purpose=?, updated_at=?`, [this.accountId, channelId, purpose, now, purpose, now]);
+        this.persist();
+    }
+    removePurpose(channelId) {
+        if (!this.db)
+            return;
+        this.db.run('DELETE FROM channel_purpose WHERE account_id = ? AND channel_id = ?', [this.accountId, channelId]);
+        this.persist();
+    }
+    /**
+     * Clean up old dedup records (older than 24h)
+     */
+    cleanupSeen() {
+        if (!this.db)
+            return;
+        const cutoff = Date.now() - 86_400_000;
+        this.db.run('DELETE FROM seen_messages WHERE account_id = ? AND seen_at < ?', [this.accountId, cutoff]);
+        this.persist();
+    }
+    /**
+     * Close the database connection
+     */
+    close() {
+        if (this.db) {
+            this.persist(); // Final persist
+            this.db.close();
+            this.db = null;
+        }
+    }
+    // ═════════════════════════════════════════════════════════════════
+    // §11.1 OASN pending_invocations CRUD（OasnInvocation.PendingInvocationStore 适配）
+    //
+    // 设计依据：docs/specs/2026-06-16-oasn-transport-abstraction-design.md §11.1
+    //
+    // 表内字段 account_id 用 this.accountId 自动注入，调用方无需关心多账号隔离。
+    // ═════════════════════════════════════════════════════════════════
+    /**
+     * 查 tool_call_id 是否有未完成记录。命中 → 复用其 idempotency_key 防止重复创建 Invocation。
+     *
+     * 仅当 status 为非终态（pending/accepted/queued/running）时返回，避免幂等键被复用到新调用上。
+     */
+    getPendingInvocation(toolCallId) {
+        if (!this.db)
+            return null;
+        const stmt = this.db.prepare(`SELECT idempotency_key, invocation_id, status
+       FROM pending_invocations
+       WHERE account_id = ? AND tool_call_id = ?`);
+        stmt.bind([this.accountId, toolCallId]);
+        let row = null;
+        if (stmt.step())
+            row = stmt.getAsObject();
+        stmt.free();
+        if (!row)
+            return null;
+        const status = String(row['status']);
+        if (this._isTerminalStatus(status))
+            return null;
+        const result = {
+            idempotency_key: String(row['idempotency_key']),
+        };
+        const invId = row['invocation_id'];
+        if (typeof invId === 'string' && invId.length > 0)
+            result.invocation_id = invId;
+        return result;
+    }
+    /**
+     * 插入或更新一条 pending 记录。
+     *
+     * 调用时机：
+     *   - sendTask 之前（尚无 invocation_id，status='pending'）
+     *   - POST /api/invocations 返回后（回填 invocation_id + status）
+     */
+    upsertPendingInvocation(record) {
+        if (!this.db)
+            return;
+        const now = Date.now();
+        this.db.run(`INSERT INTO pending_invocations
+         (account_id, tool_call_id, idempotency_key, invocation_id, session_id, target_agent_id, status, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(account_id, tool_call_id) DO UPDATE SET
+         invocation_id   = COALESCE(excluded.invocation_id, pending_invocations.invocation_id),
+         session_id      = COALESCE(excluded.session_id, pending_invocations.session_id),
+         target_agent_id = COALESCE(excluded.target_agent_id, pending_invocations.target_agent_id),
+         status          = excluded.status,
+         updated_at      = excluded.updated_at`, [
+            this.accountId,
+            record.tool_call_id,
+            record.idempotency_key,
+            record.invocation_id ?? null,
+            record.session_id ?? null,
+            record.target_agent_id ?? null,
+            record.status,
+            now,
+            now,
+        ]);
+        this.persist();
+    }
+    /**
+     * 终态标记。透过 invocation_id 查找（OasnInvocation 在终态回调时只持有 invocation_id）。
+     */
+    markPendingInvocationTerminal(invocationId, status) {
+        if (!this.db)
+            return;
+        this.db.run(`UPDATE pending_invocations
+       SET status = ?, updated_at = ?
+       WHERE account_id = ? AND invocation_id = ?`, [status, Date.now(), this.accountId, invocationId]);
+        this.persist();
+    }
+    /**
+     * §11.2 abort 标记。
+     *
+     * 服务端没有 cancel API，本地只能记录"已放弃跟踪"，便于排查 / 配额对账。
+     */
+    markPendingInvocationAbandoned(invocationId) {
+        this.markPendingInvocationTerminal(invocationId, 'abandoned');
+    }
+    /**
+     * 列出非终态记录（启动时续轮询用）。
+     *
+     * 返回顺序：按 created_at 升序，先创建的先续。
+     */
+    listUnsettledInvocations() {
+        if (!this.db)
+            return [];
+        const stmt = this.db.prepare(`SELECT tool_call_id, idempotency_key, invocation_id, session_id, target_agent_id, status, created_at, updated_at
+       FROM pending_invocations
+       WHERE account_id = ?
+         AND status NOT IN ('succeeded','failed','timed_out','cancelled','abandoned')
+       ORDER BY created_at ASC`);
+        stmt.bind([this.accountId]);
+        const results = [];
+        while (stmt.step()) {
+            const row = stmt.getAsObject();
+            results.push({
+                tool_call_id: row['tool_call_id'],
+                idempotency_key: row['idempotency_key'],
+                invocation_id: row['invocation_id'] ?? null,
+                session_id: row['session_id'] ?? null,
+                target_agent_id: row['target_agent_id'] ?? null,
+                status: row['status'],
+                created_at: Number(row['created_at']),
+                updated_at: Number(row['updated_at']),
+            });
+        }
+        stmt.free();
+        return results;
+    }
+    _isTerminalStatus(status) {
+        return status === 'succeeded'
+            || status === 'failed'
+            || status === 'timed_out'
+            || status === 'cancelled'
+            || status === 'abandoned';
+    }
+}

package/dist/src/tim/c2c.d.ts

@@ -0,0 +1,83 @@
+/**
+ * TIM C2C — Agent-to-Agent direct messaging
+ *
+ * Provides C2C (peer-to-peer) communication for remote agent orchestration.
+ * Used by openagent_call_remote_agent tool (T2) to send requests and await replies.
+ *
+ * Architecture:
+ * - sendC2CCustomMessage: sends a TIM CustomMessage via CONV_C2C
+ * - waitForC2CReply: registers a pending request, resolves when reply arrives
+ * - initC2CHandler: listens for client 'c2c_message' events, dispatches to pending requests
+ *
+ * @see docs/products/orchestrator/specs/T1-c2c-infra.md
+ * @see docs/products/orchestrator/openagent-teams-architecture.md §3.3.3
+ */
+import type { TIMClient } from './client.js';
+/** C2C message payload types for the OpenAgent orchestration protocol */
+export type C2CMessagePayload = {
+    type: 'openagent_task_request';
+    request_id: string;
+    task: string;
+    session_mode: string;
+} | {
+    type: 'openagent_task_progress';
+    request_id: string;
+    content: string;
+} | {
+    type: 'openagent_task_result';
+    request_id: string;
+    status: 'complete' | 'error';
+    content: string;
+    /** T4: number of TIMFileElem messages sent before this result. 0 or absent = no files. */
+    file_count?: number;
+};
+/** Result returned by waitForC2CReply when the remote agent completes */
+export interface C2CReplyResult {
+    status: 'complete' | 'error';
+    content: string;
+    /** T4: local file paths after saveMediaBuffer (populated from pending TIMFileElem messages) */
+    mediaUrls?: string[];
+}
+/** Options for waitForC2CReply */
+export interface WaitForC2CReplyOptions {
+    timeoutMs: number;
+    signal?: AbortSignal;
+    onProgress?: (content: string) => void;
+}
+/**
+ * Send a C2C custom message to a remote agent.
+ *
+ * Uses TIM SDK createCustomMessage + CONV_C2C.
+ * Protocol payload is JSON-serialized into the custom message `data` field.
+ *
+ * Timeout pattern matches messages.ts sendMessage (10s SDK-call guard).
+ * @see src/tim/messages.ts L61-87
+ *
+ * @param userId - Target agent's TIM userId
+ * @param payload - Structured message payload (request/progress/result)
+ */
+export declare function sendC2CCustomMessage(userId: string, payload: C2CMessagePayload): Promise<void>;
+/**
+ * Wait for a C2C reply matching a specific requestId.
+ *
+ * Registers a pending entry in the registry. When c2cMessageHandler receives
+ * a matching message, it dispatches to the entry's callbacks:
+ * - task_progress → onProgress(content)
+ * - task_result → resolve({ status, content })
+ *
+ * @param requestId - UUID to match replies against
+ * @param options - Timeout, abort signal, and progress callback
+ */
+export declare function waitForC2CReply(requestId: string, options: WaitForC2CReplyOptions): Promise<C2CReplyResult>;
+/**
+ * Initialize the C2C message handler.
+ *
+ * Listens for 'c2c_message' events from TIMClient and dispatches to:
+ * - pendingRequests registry (for progress/result → T2's waitForC2CReply)
+ * - 'c2c_request' event (for incoming task requests → T3's handler)
+ *
+ * Must be called after TIMClient.connect() succeeds.
+ *
+ * @param client - Connected TIMClient instance
+ */
+export declare function initC2CHandler(client: TIMClient): void;