openclaw-openagent 1.0.1 → 1.0.2

package/dist/src/tim/c2c.js

@@ -0,0 +1,318 @@
+/**
+ * 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 { logger } from '../util/logger.js';
+import { registry } from '../runtime/registry.js';
+/**
+ * All pending requests waiting for C2C replies.
+ * Key: requestId (UUID), Value: callbacks + timeout handle.
+ *
+ * Memory safety: every entry is guaranteed to be deleted via one of three paths:
+ * 1. Normal completion (task_result received) → clearTimeout + delete + resolve
+ * 2. Timeout (timeoutMs expired) → delete + reject
+ * 3. Abort (signal.abort) → clearTimeout + delete + reject
+ */
+const pendingRequests = new Map();
+const pendingFiles = new Map();
+const fileWaiters = new Map();
+/** Max time to wait for late-arriving TIMFileElem messages (10 min). */
+const FILE_WAIT_TIMEOUT_MS = 10 * 60_000;
+// ── sendC2CCustomMessage ──
+/**
+ * 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 async function sendC2CCustomMessage(userId, payload) {
+    const rt = registry.getDefault();
+    if (!rt || !rt.isRunning || !rt.client) {
+        throw new Error('OpenAgent not connected');
+    }
+    const chat = rt.client._chat;
+    const types = rt.client._types;
+    if (!chat || !rt.client.isReady) {
+        throw new Error('TIM SDK not initialized');
+    }
+    const message = chat.createCustomMessage({
+        to: userId,
+        conversationType: types.CONV_C2C,
+        payload: {
+            data: JSON.stringify(payload),
+            description: payload.type,
+            extension: '',
+        },
+    });
+    logger.info(`[tim/c2c] Sending C2C: to=${userId} type=${payload.type}`);
+    // 10s SDK-call guard — same pattern as messages.ts L64-69
+    // If SDK hangs (dead WebSocket), this prevents the Tool from blocking forever.
+    let timeoutHandle;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => reject(new Error(`sendC2CCustomMessage timeout (10s) to=${userId}`)), 10_000);
+    });
+    try {
+        await Promise.race([chat.sendMessage(message), timeoutPromise]);
+        logger.info(`[tim/c2c] C2C sent OK: to=${userId} type=${payload.type}`);
+    }
+    catch (err) {
+        const code = err?.code;
+        logger.error(`[tim/c2c] C2C send failed: code=${code} msg=${err.message} to=${userId}`);
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+// ── waitForC2CReply ──
+/**
+ * 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 function waitForC2CReply(requestId, options) {
+    return new Promise((resolve, reject) => {
+        // Timeout: auto-reject + cleanup after timeoutMs
+        const timeoutHandle = setTimeout(() => {
+            pendingRequests.delete(requestId);
+            reject(new Error(`C2C reply timeout (${options.timeoutMs}ms) requestId=${requestId}`));
+        }, options.timeoutMs);
+        // Abort signal: reject + cleanup on user cancel
+        if (options.signal) {
+            options.signal.addEventListener('abort', () => {
+                clearTimeout(timeoutHandle);
+                pendingRequests.delete(requestId);
+                reject(new Error(`C2C reply aborted requestId=${requestId}`));
+            }, { once: true });
+        }
+        // Register pending entry
+        pendingRequests.set(requestId, {
+            onProgress: options.onProgress,
+            resolve,
+            reject,
+            timeoutHandle,
+        });
+        logger.info(`[tim/c2c] Registered pending request: requestId=${requestId} timeout=${options.timeoutMs}ms`);
+    });
+}
+// ── C2C Message Handler ──
+/**
+ * Parse a raw C2C message payload into a OpenAgent protocol message.
+ * Returns null if the message is not a OpenAgent protocol message.
+ */
+function parseC2CPayload(raw) {
+    // TIM CustomMessage payload: { data: string, description: string, extension: string }
+    const p = raw.payload;
+    if (!p?.data)
+        return null;
+    try {
+        const parsed = JSON.parse(p.data);
+        // Validate: must be a OpenAgent protocol message with request_id
+        if (typeof parsed.type !== 'string' || !parsed.type.startsWith('openagent_task_')) {
+            return null;
+        }
+        if (typeof parsed.request_id !== 'string') {
+            logger.warn(`[tim/c2c] C2C message missing request_id: type=${parsed.type}`);
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        // Not a JSON payload or parse error → not a OpenAgent message
+        return null;
+    }
+}
+/**
+ * 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 function initC2CHandler(client) {
+    client.on('c2c_message', async (raw) => {
+        try {
+            // T4: Check for TIMFileElem before parsing as CustomMessage
+            // MSG_FILE messages have a different payload structure (fileUrl, fileName, fileSize)
+            // and won't pass parseC2CPayload. We accumulate them for later retrieval.
+            if (raw.type === 'TIMFileElem') {
+                handleC2CFileMessage(raw);
+                return;
+            }
+            const payload = parseC2CPayload(raw);
+            if (!payload)
+                return; // Not a OpenAgent protocol message
+            const requestId = payload.request_id;
+            switch (payload.type) {
+                case 'openagent_task_progress': {
+                    const pending = pendingRequests.get(requestId);
+                    if (!pending) {
+                        logger.debug(`[tim/c2c] No pending request for progress requestId=${requestId}`);
+                        return;
+                    }
+                    logger.debug(`[tim/c2c] Progress for requestId=${requestId}: ${payload.content.slice(0, 80)}`);
+                    pending.onProgress?.(payload.content);
+                    break;
+                }
+                case 'openagent_task_result': {
+                    const pending = pendingRequests.get(requestId);
+                    if (!pending) {
+                        logger.debug(`[tim/c2c] No pending request for result requestId=${requestId}`);
+                        return;
+                    }
+                    logger.info(`[tim/c2c] Result for requestId=${requestId}: status=${payload.status}`);
+                    clearTimeout(pending.timeoutHandle);
+                    pendingRequests.delete(requestId);
+                    // T4: Collect pending files from this sender.
+                    // Files may arrive before or after task_result (race condition).
+                    // If files are already here → drain immediately.
+                    // If not → register a fileWaiter and wait up to FILE_WAIT_TIMEOUT_MS.
+                    const fileCount = payload.file_count ?? 0;
+                    let mediaUrls;
+                    if (fileCount > 0) {
+                        const senderFiles = pendingFiles.get(raw.from) ?? [];
+                        logger.info(`[tim/c2c] Result has file_count=${fileCount}, pending files from sender: ${senderFiles.length}`);
+                        let filesToDrain;
+                        if (senderFiles.length >= fileCount) {
+                            // Files already arrived → drain immediately
+                            filesToDrain = senderFiles;
+                            pendingFiles.delete(raw.from);
+                        }
+                        else {
+                            // Files haven't arrived yet → wait for them
+                            logger.info(`[tim/c2c] Waiting for ${fileCount} file(s) from ${raw.from} (have ${senderFiles.length})...`);
+                            filesToDrain = await new Promise((resolveFiles) => {
+                                const timeoutHandle = setTimeout(() => {
+                                    fileWaiters.delete(raw.from);
+                                    const partial = pendingFiles.get(raw.from) ?? [];
+                                    pendingFiles.delete(raw.from);
+                                    logger.warn(`[tim/c2c] File wait timeout (${FILE_WAIT_TIMEOUT_MS}ms) for ${raw.from}, got ${partial.length}/${fileCount} file(s)`);
+                                    resolveFiles(partial);
+                                }, FILE_WAIT_TIMEOUT_MS);
+                                fileWaiters.set(raw.from, {
+                                    expectedCount: fileCount,
+                                    onFilesReady: (files) => {
+                                        clearTimeout(timeoutHandle);
+                                        fileWaiters.delete(raw.from);
+                                        resolveFiles(files);
+                                    },
+                                    timeoutHandle,
+                                });
+                            });
+                        }
+                        if (filesToDrain.length > 0) {
+                            mediaUrls = [];
+                            for (const fileInfo of filesToDrain) {
+                                try {
+                                    logger.info(`[tim/c2c] Downloading file: ${fileInfo.fileName} (${fileInfo.fileSize} bytes)`);
+                                    const resp = await fetch(fileInfo.fileUrl);
+                                    if (!resp.ok) {
+                                        logger.error(`[tim/c2c] File download failed: HTTP ${resp.status} for ${fileInfo.fileName}`);
+                                        continue;
+                                    }
+                                    const buffer = Buffer.from(await resp.arrayBuffer());
+                                    // Save to temp dir with original filename preserved
+                                    // Use /tmp/openclaw/ prefix — framework's default localRoots whitelist.
+                                    const fs = await import('node:fs');
+                                    const nodePath = await import('node:path');
+                                    const tmpDir = nodePath.join('/tmp/openclaw', 'openagent-media');
+                                    fs.mkdirSync(tmpDir, { recursive: true });
+                                    const tmpPath = nodePath.join(tmpDir, `${Date.now()}-${fileInfo.fileName}`);
+                                    fs.writeFileSync(tmpPath, buffer);
+                                    mediaUrls.push(tmpPath);
+                                    logger.info(`[tim/c2c] File saved: ${fileInfo.fileName} → ${tmpPath} (${buffer.byteLength} bytes)`);
+                                }
+                                catch (err) {
+                                    logger.error(`[tim/c2c] File download/save error: ${err.message} for ${fileInfo.fileName}`);
+                                }
+                            }
+                            if (mediaUrls.length === 0)
+                                mediaUrls = undefined;
+                        }
+                    }
+                    pending.resolve({ status: payload.status, content: payload.content, mediaUrls });
+                    break;
+                }
+                case 'openagent_task_request': {
+                    // Incoming task request from another agent → forward to T3 handler
+                    // T1 does not process requests, only replies (progress + result)
+                    logger.info(`[tim/c2c] Incoming task request from=${raw.from} requestId=${requestId}`);
+                    client.emit('c2c_request', {
+                        from: raw.from,
+                        payload,
+                        time: raw.time,
+                    });
+                    break;
+                }
+                default:
+                    logger.debug(`[tim/c2c] Unknown C2C payload type: ${payload.type}`);
+            }
+        }
+        catch (err) {
+            logger.error(`[tim/c2c] Error handling C2C message: ${err.message}`);
+        }
+    });
+    logger.info('[tim/c2c] C2C message handler initialized');
+}
+/**
+ * Handle a raw C2C message that might be a TIMFileElem.
+ * Called from initC2CHandler for non-CustomMessage types.
+ * Accumulates file metadata in pendingFiles for later retrieval.
+ *
+ * @see docs/audit/023-tim-upload-plugin-v1.md §4.4
+ */
+function handleC2CFileMessage(raw) {
+    // TIMFileElem payload structure (from TIM SDK):
+    // { fileUrl: string, fileName: string, fileSize: number, uuid: string }
+    const payload = raw.payload;
+    if (!payload?.fileUrl || !payload?.fileName) {
+        logger.debug(`[tim/c2c] MSG_FILE from=${raw.from} but missing fileUrl/fileName, skip`);
+        return;
+    }
+    const fileInfo = {
+        fileUrl: payload.fileUrl,
+        fileName: payload.fileName,
+        fileSize: payload.fileSize ?? 0,
+    };
+    if (!pendingFiles.has(raw.from)) {
+        pendingFiles.set(raw.from, []);
+    }
+    pendingFiles.get(raw.from).push(fileInfo);
+    const totalFiles = pendingFiles.get(raw.from).length;
+    logger.info(`[tim/c2c] Pending file from=${raw.from}: ${fileInfo.fileName} (${fileInfo.fileSize} bytes) total=${totalFiles}`);
+    // Check if a fileWaiter is waiting for files from this sender.
+    // This handles the race condition where task_result arrived before the file.
+    const waiter = fileWaiters.get(raw.from);
+    if (waiter && totalFiles >= waiter.expectedCount) {
+        logger.info(`[tim/c2c] File waiter satisfied for ${raw.from}: ${totalFiles}/${waiter.expectedCount} file(s)`);
+        const files = pendingFiles.get(raw.from) ?? [];
+        pendingFiles.delete(raw.from);
+        waiter.onFilesReady(files);
+    }
+}

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

@@ -0,0 +1,95 @@
+/**
+ * TIM Channels — Channel management operations via SDK
+ *
+ * All operations use the TIM SDK (not REST API).
+ * listChannels uses the auth service endpoint.
+ */
+import type { TIMClient } from './client.js';
+export interface ChannelInfo {
+    id: string;
+    name: string;
+    desc: string;
+    memberCount?: number;
+}
+export interface MemberInfo {
+    id: string;
+    nick: string;
+    role: string;
+    avatar?: string;
+}
+/**
+ * List all available channels from the auth service.
+ */
+export declare function listChannels(client: TIMClient): Promise<ChannelInfo[]>;
+/**
+ * Search channels by keyword (client-side filter of listChannels).
+ */
+export declare function searchChannels(client: TIMClient, keyword: string): Promise<ChannelInfo[]>;
+/**
+ * Join a group channel.
+ *
+ * Per TIM Web SDK docs, joinGroup may:
+ *   - Resolve with status JOIN_STATUS_SUCCESS / ALREADY_IN_GROUP / WAIT_APPROVAL
+ *   - Reject with error code 10013 ("already group member")
+ *
+ * We handle both paths and always refresh the SDK conversation cache
+ * afterwards to prevent sendMessage error 2801.
+ *
+ * @see https://cloud.tencent.com/document/product/269/75395
+ */
+export declare function joinChannel(client: TIMClient, channelId: string): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * Leave a group channel.
+ */
+export declare function leaveChannel(client: TIMClient, channelId: string): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * Get members of a group channel.
+ */
+export declare function getMembers(client: TIMClient, channelId: string): Promise<MemberInfo[]>;
+/**
+ * Create a new Community group channel.
+ *
+ * Uses GRP_COMMUNITY (社群) — supports large-scale membership, topics,
+ * and free join/leave. Requires Tencent IM flagship plan with Community
+ * feature enabled in console.
+ *
+ * groupID is always auto-generated by the SDK with @TGS#_ prefix.
+ * Community groups reject custom groupIDs that don't start with @TGS#_
+ * (SDK error ILLEGAL_GRP_ID / 2602).
+ *
+ * @see https://cloud.tencent.com/document/product/269/75394
+ * @see https://cloud.tencent.com/document/product/269/1502 (群组类型)
+ */
+export declare function createChannel(client: TIMClient, name: string, description?: string, skill?: string): Promise<{
+    success: boolean;
+    channelId: string;
+}>;
+/**
+ * Get channel skill (stored in group notification field).
+ */
+export declare function getChannelSkill(client: TIMClient, channelId: string): Promise<string | null>;
+/**
+ * Set channel skill (stored in group notification field).
+ */
+export declare function setChannelSkill(client: TIMClient, channelId: string, skill: string): Promise<{
+    success: boolean;
+}>;
+/**
+ * Get channel display name from group profile.
+ */
+export declare function getGroupName(client: TIMClient, channelId: string): Promise<string | null>;
+/**
+ * Read a single group-level custom field (AppDefinedData).
+ *
+ * Uses getGroupProfile with groupCustomFieldFilter to fetch only the
+ * requested field. Returns null if field not set or fetch fails.
+ *
+ * @param fieldKey - The custom field key (e.g. 'gm_req_mention')
+ */
+export declare function getGroupCustomField(client: TIMClient, channelId: string, fieldKey: string): Promise<string | null>;

package/dist/src/tim/channels.js

@@ -0,0 +1,279 @@
+/**
+ * TIM Channels — Channel management operations via SDK
+ *
+ * All operations use the TIM SDK (not REST API).
+ * listChannels uses the auth service endpoint.
+ */
+import { logger } from '../util/logger.js';
+import { httpGet } from '../util/http.js';
+const AUTH_BASE = 'https://auth.ai-talk.live';
+// ── Functions ──
+/**
+ * List all available channels from the auth service.
+ */
+export async function listChannels(client) {
+    logger.info('[tim/channels] listChannels: fetching from auth service');
+    try {
+        const headers = {};
+        if (client.userSig) {
+            headers['Authorization'] = `Bearer ${client.userSig}`;
+        }
+        const data = await httpGet(`${AUTH_BASE}/api/channels`, { headers });
+        const rawList = Array.isArray(data) ? data : (data.data
+            || data.channels
+            || []);
+        logger.info(`[tim/channels] listChannels: found ${rawList.length} channels`);
+        return rawList.map((item) => {
+            const ch = item;
+            return {
+                id: (ch['channel_id'] || ch['id'] || ch['channelId'] || ch['GroupId'] || ''),
+                name: (ch['name'] || ch['Name'] || ''),
+                desc: (ch['description'] || ch['desc'] || ch['Introduction'] || ''),
+                memberCount: (ch['member_count'] || ch['memberCount'] || 0),
+            };
+        });
+    }
+    catch (err) {
+        logger.error(`[tim/channels] listChannels error: ${err.message}`);
+        throw err;
+    }
+}
+/**
+ * Search channels by keyword (client-side filter of listChannels).
+ */
+export async function searchChannels(client, keyword) {
+    logger.info(`[tim/channels] searchChannels: keyword="${keyword}"`);
+    const all = await listChannels(client);
+    const lower = keyword.toLowerCase();
+    return all.filter(ch => ch.name.toLowerCase().includes(lower) ||
+        ch.desc.toLowerCase().includes(lower) ||
+        ch.id.toLowerCase().includes(lower));
+}
+/**
+ * TIM SDK error code for "already a group member".
+ * @see https://cloud.tencent.com/document/product/269/75394
+ */
+const ERR_ALREADY_GROUP_MEMBER = 10013;
+/**
+ * Join a group channel.
+ *
+ * Per TIM Web SDK docs, joinGroup may:
+ *   - Resolve with status JOIN_STATUS_SUCCESS / ALREADY_IN_GROUP / WAIT_APPROVAL
+ *   - Reject with error code 10013 ("already group member")
+ *
+ * We handle both paths and always refresh the SDK conversation cache
+ * afterwards to prevent sendMessage error 2801.
+ *
+ * @see https://cloud.tencent.com/document/product/269/75395
+ */
+export async function joinChannel(client, channelId) {
+    const chat = client._chat;
+    if (!chat || !client.isReady)
+        throw new Error('Not connected');
+    logger.info(`[tim/channels] joinChannel: ${channelId}`);
+    try {
+        await chat.joinGroup({ groupID: channelId });
+        logger.info(`[tim/channels] joinChannel: joined ${channelId}`);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === ERR_ALREADY_GROUP_MEMBER) {
+            logger.info(`[tim/channels] joinChannel: already a member of ${channelId} (code=${code})`);
+        }
+        else {
+            logger.error(`[tim/channels] joinChannel failed: code=${code} msg=${err.message}`);
+            throw err;
+        }
+    }
+    // Force SDK to cache group conversation profile.
+    // Required because: (1) ALREADY_IN_GROUP does not refresh cache,
+    // and (2) even new joins may not populate the conversation list.
+    // Without this, sendMessage fails with error 2801 (group profile cache miss).
+    try {
+        await chat.getConversationProfile(`GROUP${channelId}`);
+        logger.info(`[tim/channels] joinChannel: conversation profile cached for ${channelId}`);
+    }
+    catch (cacheErr) {
+        const cacheCode = cacheErr?.code;
+        logger.warn(`[tim/channels] joinChannel: failed to cache conversation profile for ${channelId} (code=${cacheCode})`);
+    }
+    return { success: true, message: `Joined ${channelId}` };
+}
+/**
+ * Leave a group channel.
+ */
+export async function leaveChannel(client, channelId) {
+    const chat = client._chat;
+    if (!chat || !client.isReady)
+        throw new Error('Not connected');
+    logger.info(`[tim/channels] leaveChannel: ${channelId}`);
+    try {
+        await chat.quitGroup(channelId);
+        return { success: true, message: `Left ${channelId}` };
+    }
+    catch (err) {
+        const code = err?.code;
+        logger.error(`[tim/channels] leaveChannel failed: code=${code} msg=${err.message} ch=${channelId}`);
+        throw err;
+    }
+}
+/**
+ * Get members of a group channel.
+ */
+export async function getMembers(client, channelId) {
+    const chat = client._chat;
+    if (!chat || !client.isReady)
+        throw new Error('Not connected');
+    logger.info(`[tim/channels] getMembers: ${channelId}`);
+    try {
+        const res = await chat.getGroupMemberList({
+            groupID: channelId,
+            count: 100,
+            offset: 0,
+        });
+        const members = (res.data?.memberList || []).map(m => ({
+            id: m.userID,
+            nick: m.nick || m.userID,
+            role: m.role || 'Member',
+            avatar: m.avatar || '',
+        }));
+        logger.info(`[tim/channels] getMembers: ${channelId} found ${members.length} members`);
+        return members;
+    }
+    catch (err) {
+        const code = err?.code;
+        logger.error(`[tim/channels] getMembers failed: code=${code} msg=${err.message} ch=${channelId}`);
+        throw err;
+    }
+}
+/**
+ * Create a new Community group channel.
+ *
+ * Uses GRP_COMMUNITY (社群) — supports large-scale membership, topics,
+ * and free join/leave. Requires Tencent IM flagship plan with Community
+ * feature enabled in console.
+ *
+ * groupID is always auto-generated by the SDK with @TGS#_ prefix.
+ * Community groups reject custom groupIDs that don't start with @TGS#_
+ * (SDK error ILLEGAL_GRP_ID / 2602).
+ *
+ * @see https://cloud.tencent.com/document/product/269/75394
+ * @see https://cloud.tencent.com/document/product/269/1502 (群组类型)
+ */
+export async function createChannel(client, name, description = '', skill = '') {
+    const chat = client._chat;
+    if (!chat || !client.isReady)
+        throw new Error('Not connected');
+    logger.info(`[tim/channels] createChannel: type=Community name="${name}"`);
+    try {
+        // Community groups require groupID to start with @TGS#_ or be empty.
+        // SDK auto-generates @TGS#_ prefixed ID when groupID is omitted.
+        const result = await chat.createGroup({
+            type: client._types.GRP_COMMUNITY,
+            name,
+            // groupID intentionally omitted — SDK auto-generates @TGS#_ prefixed ID
+            introduction: description,
+            notification: skill,
+            isSupportTopic: false,
+        });
+        const actualId = result?.data?.group?.groupID;
+        if (!actualId)
+            throw new Error('SDK returned no groupID');
+        logger.info(`[tim/channels] Channel created: ${actualId} (type=Community)`);
+        return { success: true, channelId: actualId };
+    }
+    catch (err) {
+        const code = err?.code;
+        const msg = err?.message || String(err);
+        logger.error(`[tim/channels] createChannel failed: code=${code} msg=${msg}`);
+        throw err;
+    }
+}
+/**
+ * Get channel skill (stored in group notification field).
+ */
+export async function getChannelSkill(client, channelId) {
+    const chat = client._chat;
+    if (!chat || !client.isReady)
+        return null;
+    try {
+        const res = await chat.getGroupProfile({
+            groupID: channelId,
+            groupCustomFieldFilter: [],
+        });
+        return res.data?.group?.notification || null;
+    }
+    catch (err) {
+        const code = err?.code;
+        logger.warn(`[tim/channels] getChannelSkill failed: code=${code} msg=${err.message} ch=${channelId}`);
+        return null;
+    }
+}
+/**
+ * Set channel skill (stored in group notification field).
+ */
+export async function setChannelSkill(client, channelId, skill) {
+    const chat = client._chat;
+    if (!chat || !client.isReady)
+        throw new Error('Not connected');
+    logger.info(`[tim/channels] setChannelSkill: ${channelId}`);
+    try {
+        await chat.updateGroupProfile({
+            groupID: channelId,
+            notification: skill,
+        });
+        return { success: true };
+    }
+    catch (err) {
+        const code = err?.code;
+        logger.error(`[tim/channels] setChannelSkill failed: code=${code} msg=${err.message} ch=${channelId}`);
+        throw err;
+    }
+}
+/**
+ * Get channel display name from group profile.
+ */
+export async function getGroupName(client, channelId) {
+    const chat = client._chat;
+    if (!chat || !client.isReady)
+        return null;
+    try {
+        const res = await chat.getGroupProfile({
+            groupID: channelId,
+            groupCustomFieldFilter: [],
+        });
+        return res.data?.group?.name || null;
+    }
+    catch (err) {
+        const code = err?.code;
+        logger.warn(`[tim/channels] getGroupName failed: code=${code} msg=${err.message} ch=${channelId}`);
+        return null;
+    }
+}
+/**
+ * Read a single group-level custom field (AppDefinedData).
+ *
+ * Uses getGroupProfile with groupCustomFieldFilter to fetch only the
+ * requested field. Returns null if field not set or fetch fails.
+ *
+ * @param fieldKey - The custom field key (e.g. 'gm_req_mention')
+ */
+export async function getGroupCustomField(client, channelId, fieldKey) {
+    const chat = client._chat;
+    if (!chat || !client.isReady)
+        return null;
+    try {
+        const res = await chat.getGroupProfile({
+            groupID: channelId,
+            groupCustomFieldFilter: [fieldKey],
+        });
+        const fields = res.data?.group?.groupCustomField ?? [];
+        const target = fields.find((f) => f.key === fieldKey);
+        return target?.value ?? null;
+    }
+    catch (err) {
+        const code = err?.code;
+        logger.warn(`[tim/channels] getGroupCustomField(${fieldKey}) failed: code=${code} ch=${channelId}`);
+        return null;
+    }
+}