openclaw-openagent 1.0.1 → 1.0.3

package/dist/src/app/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared tool types
+ *
+ * Return format aligned with OpenClaw SDK's AgentToolResult:
+ * @see https://docs.openclaw.ai (Plugin SDK → Building Plugins)
+ * @see docs/reference/openclaw/v2026.3.23/dist/plugin-sdk/src/agents/tools/common.d.ts
+ */
+export interface ToolParams {
+    [key: string]: unknown;
+}
+/** SDK-compatible tool result (matches AgentToolResult structure) */
+export interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    /** Optional details for rich media. Matches OpenClaw AgentToolResult<TDetails>. */
+    details?: {
+        media?: {
+            mediaUrls: string[];
+        };
+        [key: string]: unknown;
+    };
+}
+export type ToolUpdateCallback = (partialResult: ToolResult) => void;
+export interface ToolDescriptor {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description: string;
+            enum?: string[];
+            default?: unknown;
+            items?: {
+                type: string;
+            };
+        }>;
+        required: string[];
+    };
+    /**
+     * Execute the tool.
+     *
+     * OpenClaw runtime usually calls:
+     *   tool.execute(toolCallId, params, signal, onUpdate)
+     *
+     * Older adapters used:
+     *   tool.execute(toolCallId, params, onUpdate, ctx, signal)
+     *
+     * The wider signature lets streaming tools normalize both shapes while
+     * existing 2-param tools continue to work unchanged.
+     *
+     * @see docs/reference/openclaw/v2026.3.23/dist/pi-embedded-CswW9luA.js L169823
+     */
+    execute: (_id: unknown, params: ToolParams, signalOrUpdate?: AbortSignal | ToolUpdateCallback, onUpdateOrContext?: ToolUpdateCallback | unknown, legacySignal?: AbortSignal) => Promise<ToolResult>;
+}
+export type ToolFactory = () => ToolDescriptor;
+/** Helper: create a successful text result in SDK format */
+export declare function toolResult(text: string): ToolResult;

package/dist/src/app/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared tool types
+ *
+ * Return format aligned with OpenClaw SDK's AgentToolResult:
+ * @see https://docs.openclaw.ai (Plugin SDK → Building Plugins)
+ * @see docs/reference/openclaw/v2026.3.23/dist/plugin-sdk/src/agents/tools/common.d.ts
+ */
+/** Helper: create a successful text result in SDK format */
+export function toolResult(text) {
+    return { content: [{ type: 'text', text }] };
+}

package/dist/src/app/upload-file-tool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Upload File Tool — openagent_upload_file
+ *
+ * Uploads a local file to the OASN agent network, returning a fileRef
+ * that can be passed to openagent_call_remote_agent via input_file_refs.
+ *
+ * Supports three input modes:
+ *   - file_path: absolute path to a local file
+ *   - media_ref: OpenClaw media://inbound/<id> reference (from web UI attachments)
+ *   - filename_hint: original filename to scan & match from ~/.openclaw/media/inbound/
+ *
+ * API: POST /api/files (access layer)
+ * Ref: access-upload-download-api.md §2
+ */
+import { type ToolDescriptor } from './types.js';
+export declare function createUploadFileTool(): ToolDescriptor;

package/dist/src/app/upload-file-tool.js

@@ -0,0 +1,353 @@
+/**
+ * Upload File Tool — openagent_upload_file
+ *
+ * Uploads a local file to the OASN agent network, returning a fileRef
+ * that can be passed to openagent_call_remote_agent via input_file_refs.
+ *
+ * Supports three input modes:
+ *   - file_path: absolute path to a local file
+ *   - media_ref: OpenClaw media://inbound/<id> reference (from web UI attachments)
+ *   - filename_hint: original filename to scan & match from ~/.openclaw/media/inbound/
+ *
+ * API: POST /api/files (access layer)
+ * Ref: access-upload-download-api.md §2
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import nodePath from 'node:path';
+import { registry } from '../runtime/registry.js';
+import { logger } from '../util/logger.js';
+import { toolResult, } from './types.js';
+// ── Helpers ──
+const MAX_FILE_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB
+function fail(error) {
+    return toolResult(JSON.stringify({ success: false, error }));
+}
+function success(result) {
+    return toolResult(JSON.stringify({ success: true, ...result }));
+}
+/** 根据文件扩展名推断 MIME 类型 */
+function inferMimeType(filePath) {
+    const ext = nodePath.extname(filePath).toLowerCase();
+    const map = {
+        '.pdf': 'application/pdf',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.svg': 'image/svg+xml',
+        '.webp': 'image/webp',
+        '.txt': 'text/plain',
+        '.md': 'text/markdown',
+        '.json': 'application/json',
+        '.csv': 'text/csv',
+        '.html': 'text/html',
+        '.css': 'text/css',
+        '.js': 'text/javascript',
+        '.ts': 'text/typescript',
+        '.py': 'text/x-python',
+        '.xml': 'application/xml',
+        '.zip': 'application/zip',
+        '.tar': 'application/x-tar',
+        '.gz': 'application/gzip',
+        '.mp3': 'audio/mpeg',
+        '.mp4': 'video/mp4',
+        '.doc': 'application/msword',
+        '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        '.xls': 'application/vnd.ms-excel',
+        '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        '.ppt': 'application/vnd.ms-powerpoint',
+        '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    };
+    return map[ext] || 'application/octet-stream';
+}
+/**
+ * Resolve a media://inbound/<id> reference to an absolute file path.
+ * Uses OpenClaw's resolveMediaBufferPath when available, else falls back
+ * to computing the path from ~/.openclaw/media/inbound/<id>.
+ */
+async function resolveMediaRef(mediaRef) {
+    // Parse media://inbound/<id>
+    const match = mediaRef.match(/^media:\/\/inbound\/(.+)$/);
+    if (!match) {
+        throw new Error(`Unsupported media reference format: ${mediaRef}. Expected media://inbound/<id>`);
+    }
+    const id = match[1];
+    // Try OpenClaw SDK's resolveMediaBufferPath first
+    try {
+        const { resolveMediaBufferPath } = await import('openclaw/plugin-sdk/media-runtime');
+        return await resolveMediaBufferPath(id, 'inbound');
+    }
+    catch {
+        // Fallback: compute path manually
+        const mediaDir = nodePath.join(os.homedir(), '.openclaw', 'media', 'inbound');
+        const resolved = nodePath.join(mediaDir, id);
+        // Security: ensure resolved path stays within mediaDir
+        if (!resolved.startsWith(mediaDir + nodePath.sep) && resolved !== mediaDir) {
+            throw new Error(`Unsafe media ID: ${id}`);
+        }
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`Media file not found: ${id}. The attachment may have been sent inline (not saved to disk). Use file_path to upload a local file instead.`);
+        }
+        return resolved;
+    }
+}
+/** Recency window for filename_hint matching (milliseconds) */
+const FILENAME_HINT_RECENCY_MS = 5 * 60 * 1000;
+/**
+ * Scan ~/.openclaw/media/inbound/ for recently modified files,
+ * optionally filtered by a predicate. Returns candidates sorted by
+ * mtime descending (most recent first).
+ */
+function findRecentInboundFiles(mediaDir, filter) {
+    if (!fs.existsSync(mediaDir))
+        return [];
+    let entries;
+    try {
+        entries = fs.readdirSync(mediaDir);
+    }
+    catch {
+        return [];
+    }
+    const now = Date.now();
+    return entries
+        .filter((name) => {
+        if (name.startsWith('.'))
+            return false;
+        if (filter && !filter(name))
+            return false;
+        try {
+            const stat = fs.statSync(nodePath.join(mediaDir, name));
+            return stat.isFile() && (now - stat.mtimeMs) <= FILENAME_HINT_RECENCY_MS;
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((name) => {
+        const fullPath = nodePath.join(mediaDir, name);
+        const stat = fs.statSync(fullPath);
+        return { name, path: fullPath, mtimeMs: stat.mtimeMs };
+    })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+/**
+ * Resolve a filename hint to an absolute file path by scanning
+ * ~/.openclaw/media/inbound/ for recently modified files whose
+ * names contain the hint (case-insensitive substring match).
+ *
+ * Handles the disk naming convention: <original-base>---<uuid>.<ext>
+ * A hint of "photo.png" matches "photo---abc123.png" by extracting
+ * the base name "photo" and matching it against the stored filename.
+ */
+function resolveByFilenameHint(filenameHint) {
+    const mediaDir = nodePath.join(os.homedir(), '.openclaw', 'media', 'inbound');
+    if (!fs.existsSync(mediaDir)) {
+        throw new Error(`Media inbound directory not found: ${mediaDir}. ` +
+            `Ensure a file has been uploaded via the Web UI first.`);
+    }
+    // Normalize hint for matching against <base>---<uuid>.<ext> filenames
+    const hintLower = filenameHint.toLowerCase();
+    const lastDot = filenameHint.lastIndexOf('.');
+    const hintBaseLower = lastDot > 0
+        ? filenameHint.substring(0, lastDot).toLowerCase()
+        : hintLower;
+    const candidates = findRecentInboundFiles(mediaDir, (name) => {
+        const nameLower = name.toLowerCase();
+        return nameLower.includes(hintLower) || nameLower.includes(hintBaseLower);
+    });
+    if (candidates.length === 0) {
+        throw new Error(`No recently modified file matching "${filenameHint}" found in the media inbound directory. ` +
+            `The file may have been renamed, deleted, or uploaded more than 5 minutes ago. ` +
+            `Try uploading the file again via the Web UI, or use file_path to specify an absolute path.`);
+    }
+    // Security: ensure resolved path stays within mediaDir
+    const resolved = candidates[0].path;
+    const mediaSep = mediaDir + nodePath.sep;
+    if (!resolved.startsWith(mediaSep) && resolved !== mediaDir) {
+        throw new Error(`Unsafe path resolved from filename hint: ${filenameHint}`);
+    }
+    return resolved;
+}
+/**
+ * Resolve the most recently uploaded file from ~/.openclaw/media/inbound/.
+ * Used as a last-resort fallback when the model sees an inline image
+ * but has no filename or path information at all.
+ */
+function resolveLatestInboundFile() {
+    const mediaDir = nodePath.join(os.homedir(), '.openclaw', 'media', 'inbound');
+    if (!fs.existsSync(mediaDir)) {
+        throw new Error(`Media inbound directory not found: ${mediaDir}. ` +
+            `Ensure a file has been uploaded via the Web UI first.`);
+    }
+    const candidates = findRecentInboundFiles(mediaDir);
+    if (candidates.length === 0) {
+        throw new Error(`No recently uploaded files found in the media inbound directory. ` +
+            `Upload a file via the Web UI first, then retry. ` +
+            `If you know the file path, use the file_path parameter instead.`);
+    }
+    if (candidates.length > 1) {
+        // Log a warning so the user/operator can audit unexpected matches
+        logger.warn(`[upload-tool] auto-resolved latest of ${candidates.length} inbound files: ` +
+            `"${candidates[0].name}" (others: ${candidates.slice(1, 4).map((c) => c.name).join(', ')})`);
+    }
+    const resolved = candidates[0].path;
+    const mediaSep = mediaDir + nodePath.sep;
+    if (!resolved.startsWith(mediaSep) && resolved !== mediaDir) {
+        throw new Error('Unsafe path resolved from latest inbound file');
+    }
+    return resolved;
+}
+// ── Tool Factory ──
+export function createUploadFileTool() {
+    return {
+        name: 'openagent_upload_file',
+        label: 'Upload File',
+        description: 'Upload a local file to the OASN agent network before calling a remote agent. ' +
+            'Use this when the user wants to send a file (document, image, code, etc.) ' +
+            'to a remote specialist agent for processing. ' +
+            'Returns a fileRef string. Pass this fileRef in the ' +
+            'openagent_call_remote_agent input_file_refs parameter so the remote agent can access the file. ' +
+            'Three input modes (use exactly one, or none to auto-detect): ' +
+            '(1) file_path: absolute local path (e.g., /Users/name/Downloads/photo.png); ' +
+            '(2) media_ref: a media://inbound/<id> URL visible in the message text; ' +
+            '(3) filename_hint: the filename as shown in the upload UI (e.g., "photo.png") — ' +
+            'use this when you see an inline image in the chat but NO media://inbound/ URL. ' +
+            'The tool will automatically scan recently uploaded files to find the match on disk. ' +
+            'If NO parameters are provided, the tool auto-resolves the most recently uploaded file ' +
+            'from the Web UI — this is the easiest option when the user just attached a file. ' +
+            'Prefer media_ref when you see a media://inbound/ URL, ' +
+            'filename_hint when you only see the inline content without a URL, ' +
+            'and file_path when the user explicitly tells you a specific path.',
+        parameters: {
+            type: 'object',
+            properties: {
+                file_path: {
+                    type: 'string',
+                    description: 'Absolute path to a local file (e.g., /Users/.../report.pdf). Use this for files on disk.',
+                },
+                media_ref: {
+                    type: 'string',
+                    description: 'OpenClaw media reference from web UI attachments (e.g., media://inbound/photo---uuid.png). Use this when the user attached a file in the chat and you see a media://inbound/ URL.',
+                },
+                filename_hint: {
+                    type: 'string',
+                    description: 'The original filename as shown in the upload UI (e.g., "photo.png", "report.pdf"). ' +
+                        'Use this when you can see the file content inline but do NOT have a media://inbound/ URL. ' +
+                        'The tool will scan recently uploaded files to find a match.',
+                },
+                display_name: {
+                    type: 'string',
+                    description: 'Optional display name for the file (defaults to filename)',
+                },
+            },
+            required: [],
+        },
+        async execute(_id, params) {
+            const filePathRaw = String(params.file_path || '').trim();
+            const mediaRefRaw = String(params.media_ref || '').trim();
+            const filenameHint = String(params.filename_hint || '').trim();
+            // ① Resolve input source
+            let filePath;
+            let displayName;
+            if (mediaRefRaw) {
+                // media://inbound/<id> reference
+                try {
+                    filePath = await resolveMediaRef(mediaRefRaw);
+                    displayName = String(params.display_name || '').trim()
+                        || nodePath.basename(filePath);
+                }
+                catch (err) {
+                    return fail(err.message);
+                }
+            }
+            else if (filePathRaw) {
+                // traditional file path
+                filePath = filePathRaw;
+                displayName = String(params.display_name || '').trim()
+                    || nodePath.basename(filePath);
+            }
+            else if (filenameHint) {
+                // filename hint → scan ~/.openclaw/media/inbound/ for matching file
+                try {
+                    filePath = resolveByFilenameHint(filenameHint);
+                    displayName = String(params.display_name || '').trim()
+                        || nodePath.basename(filePath);
+                }
+                catch (err) {
+                    return fail(err.message);
+                }
+            }
+            else {
+                // fallback: auto-resolve the most recently uploaded file
+                try {
+                    filePath = resolveLatestInboundFile();
+                    displayName = String(params.display_name || '').trim()
+                        || nodePath.basename(filePath);
+                    logger.info(`[upload-tool] Auto-resolved latest inbound file: ${filePath}`);
+                }
+                catch (err) {
+                    return fail(err.message);
+                }
+            }
+            // ② 检查运行态
+            const rt = registry.getDefault();
+            if (!rt || !rt.isRunning) {
+                return fail('OpenAgent runtime not running');
+            }
+            if (rt.transportType !== 'oasn') {
+                return fail('File upload is only available via OASN transport');
+            }
+            const transport = rt.transport;
+            if (!transport || transport.transportType !== 'oasn') {
+                return fail('OASN transport not ready');
+            }
+            // ③ 读取文件
+            let stat;
+            try {
+                stat = fs.statSync(filePath);
+            }
+            catch {
+                return fail(`File not found: ${filePath}`);
+            }
+            if (!stat.isFile()) {
+                return fail(`Not a file: ${filePath}`);
+            }
+            if (stat.size > MAX_FILE_SIZE_BYTES) {
+                return fail(`File too large: ${(stat.size / (1024 * 1024)).toFixed(1)} MB (max 100 MB)`);
+            }
+            let buffer;
+            try {
+                buffer = fs.readFileSync(filePath);
+            }
+            catch (err) {
+                return fail(`Cannot read file: ${err.message}`);
+            }
+            // ④ 上传
+            const mimeType = inferMimeType(filePath);
+            const oasnTransport = transport;
+            const uploadParams = {
+                content: buffer,
+                displayName,
+                mimeType,
+            };
+            logger.info(`[upload-tool] Uploading file: name=${displayName} size=${buffer.byteLength} mime=${mimeType}`);
+            let result;
+            try {
+                result = await oasnTransport.uploadFile(uploadParams);
+            }
+            catch (err) {
+                logger.error(`[upload-tool] Upload failed: ${err.message}`);
+                return fail(`Upload failed: ${err.message}`);
+            }
+            logger.info(`[upload-tool] Upload success: fileRef=${result.fileRef} size=${result.sizeBytes}`);
+            return success({
+                fileRef: result.fileRef,
+                displayName: result.displayName,
+                mimeType: result.mimeType,
+                sizeBytes: result.sizeBytes,
+                expiresAt: result.expiresAt,
+            });
+        },
+    };
+}

package/dist/src/app/verbose-preflight.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/plugin-entry';
+export declare function installOpenagentVerbosePreflight(api: OpenClawPluginApi): void;

package/dist/src/app/verbose-preflight.js

@@ -0,0 +1,145 @@
+import { logger } from '../util/logger.js';
+const AGENT_EVENT_STATE_KEY = Symbol.for('openclaw.agentEvents.state');
+const REMOTE_TOOL_CALL_IDS = new Set();
+const REMOTE_TOOL_CALL_IDS_BY_RUN = new Map();
+const PROMOTED_RUNS = new Set();
+let installed = false;
+let missingStateWarned = false;
+let missingRuntimeWarned = false;
+function asRecord(value) {
+    return value && typeof value === 'object' ? value : {};
+}
+function readString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function readToolName(data) {
+    const call = asRecord(data.call);
+    return (readString(data.name) ||
+        readString(data.toolName) ||
+        readString(data.tool_name) ||
+        readString(call.name)).toLowerCase();
+}
+function readToolCallId(data) {
+    const call = asRecord(data.call);
+    return (readString(data.toolCallId) ||
+        readString(data.tool_call_id) ||
+        readString(data.id) ||
+        readString(call.id));
+}
+function isOpenagentRemoteToolName(name) {
+    return name.includes('call_remote_agent') || name.includes('openagent_delegate');
+}
+function rememberRemoteToolCall(runId, toolCallId) {
+    REMOTE_TOOL_CALL_IDS.add(toolCallId);
+    let runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
+    if (!runToolCallIds) {
+        runToolCallIds = new Set();
+        REMOTE_TOOL_CALL_IDS_BY_RUN.set(runId, runToolCallIds);
+    }
+    runToolCallIds.add(toolCallId);
+}
+function forgetRemoteToolCall(runId, toolCallId) {
+    REMOTE_TOOL_CALL_IDS.delete(toolCallId);
+    const runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
+    if (!runToolCallIds)
+        return;
+    runToolCallIds.delete(toolCallId);
+    if (runToolCallIds.size === 0) {
+        REMOTE_TOOL_CALL_IDS_BY_RUN.delete(runId);
+    }
+}
+function forgetRun(runId) {
+    PROMOTED_RUNS.delete(runId);
+    const runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
+    if (!runToolCallIds)
+        return;
+    for (const toolCallId of runToolCallIds) {
+        REMOTE_TOOL_CALL_IDS.delete(toolCallId);
+    }
+    REMOTE_TOOL_CALL_IDS_BY_RUN.delete(runId);
+}
+function getAgentEventState() {
+    const state = globalThis[AGENT_EVENT_STATE_KEY];
+    if (!state || typeof state !== 'object')
+        return null;
+    return state;
+}
+function promoteRunVerboseLevel(runId, toolCallId, toolName) {
+    const state = getAgentEventState();
+    const runContextById = state?.runContextById;
+    if (!(runContextById instanceof Map)) {
+        if (!missingStateWarned) {
+            missingStateWarned = true;
+            logger.warn('[verbose-preflight] OpenClaw agent event state is unavailable; OpenAgent SSE payload may be stripped');
+        }
+        return;
+    }
+    let ctx = runContextById.get(runId);
+    if (!ctx) {
+        ctx = {};
+        runContextById.set(runId, ctx);
+    }
+    if (ctx.verboseLevel !== 'full') {
+        ctx.verboseLevel = 'full';
+    }
+    if (!PROMOTED_RUNS.has(runId)) {
+        PROMOTED_RUNS.add(runId);
+        logger.info(`[verbose-preflight] promoted run verboseLevel=full (runId=${runId}, toolCallId=${toolCallId || 'unknown'}, tool=${toolName || 'unknown'})`);
+    }
+}
+function handleAgentEvent(evt) {
+    const runId = readString(evt.runId);
+    if (!runId)
+        return;
+    const data = asRecord(evt.data);
+    if (evt.stream === 'lifecycle') {
+        const phase = readString(data.phase);
+        if (phase === 'end' || phase === 'error') {
+            forgetRun(runId);
+        }
+        return;
+    }
+    if (evt.stream !== 'tool')
+        return;
+    const toolName = readToolName(data);
+    const toolCallId = readToolCallId(data);
+    if (toolCallId && isOpenagentRemoteToolName(toolName)) {
+        rememberRemoteToolCall(runId, toolCallId);
+    }
+    const shouldKeepPayload = isOpenagentRemoteToolName(toolName) ||
+        (toolCallId !== '' && REMOTE_TOOL_CALL_IDS.has(toolCallId));
+    if (!shouldKeepPayload)
+        return;
+    promoteRunVerboseLevel(runId, toolCallId, toolName);
+    const phase = readString(data.phase);
+    if (toolCallId && (phase === 'result' || phase === 'error' || phase === 'end')) {
+        forgetRemoteToolCall(runId, toolCallId);
+    }
+}
+function prioritizePreflightListener(listener) {
+    const listeners = getAgentEventState()?.listeners;
+    if (!(listeners instanceof Set) || !listeners.has(listener))
+        return;
+    const rest = Array.from(listeners).filter(item => item !== listener);
+    listeners.clear();
+    listeners.add(listener);
+    for (const item of rest)
+        listeners.add(item);
+    logger.debug('[verbose-preflight] listener moved before gateway subscribers');
+}
+export function installOpenagentVerbosePreflight(api) {
+    if (installed)
+        return;
+    const onAgentEvent = api.runtime?.events?.onAgentEvent;
+    if (typeof onAgentEvent !== 'function') {
+        if (!missingRuntimeWarned) {
+            missingRuntimeWarned = true;
+            logger.warn('[verbose-preflight] api.runtime.events.onAgentEvent is unavailable; OpenAgent SSE payload preflight disabled');
+        }
+        return;
+    }
+    onAgentEvent(handleAgentEvent);
+    prioritizePreflightListener(handleAgentEvent);
+    installed = true;
+    logger.info('[verbose-preflight] installed');
+}

package/dist/src/auth/config.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Auth — Configuration resolution
+ *
+ * Resolves OpenAgent account configuration from the OpenClaw config object.
+ * Supports two configuration layouts:
+ *   1. Nested: cfg.channels.openagent.accounts.{accountId}.*
+ *   2. Fallback (F1 compat): cfg.channels.openagent.agentId / .apiKey (top-level shorthand)
+ *
+ * See §0.1 of refactoring-plan.md.
+ */
+/**
+ * OASN 默认 API base。
+ *
+ * 未配置时故意使用不可达占位，避免把本地或生产请求误打到 REL 私有地址。
+ * 解析优先级：账号级 api_base > channel 级 api_base > 环境变量 > 该占位。
+ */
+export declare const DEFAULT_OASN_API_BASE = "https://oasn.invalid/CONFIGURE_ME";
+export declare function isUnconfiguredOasnApiBase(value: string | undefined): boolean;
+/**
+ * Transport 类型 —— v3.9+ 双轨抽象。
+ *
+ * 默认 'tim' 保留向后兼容（旧 openagent 配置无此字段，按 TIM 路径走）。
+ * 新 OASN 部署在配置中显式设置 transport='oasn'。
+ */
+export type TransportType = 'oasn' | 'tim';
+export interface OpenagentAccountConfig {
+    /** Resolved account ID */
+    accountId: string;
+    /** Display name */
+    name: string;
+    /** Whether the channel is enabled */
+    enabled: boolean;
+    /** Whether required credentials (agentId + apiKey) are present */
+    configured: boolean;
+    /** Agent identity on OpenAgent network */
+    agentId: string;
+    /** API key for auth verification */
+    apiKey: string;
+    /** API base URL */
+    apiBase: string;
+    /** Optional Access-layer API base URL for invocations/files when REL splits services */
+    accessApiBase: string;
+    /** Claim URL returned by OASN onboarding */
+    claimUrl: string;
+    /** Current onboarding claim status */
+    status: 'unregistered' | 'unclaimed' | 'claim_pending' | 'claimed' | 'credential_expired' | 'unknown';
+    /** Registration timestamp stored by the plugin */
+    registeredAt: string;
+    /**
+     * Transport 选型（v3.9+）。
+     *
+     *   - 'oasn': 直接走 OASN HTTP API（Bearer api_key）
+     *   - 'tim':  走腾讯云 IM（默认，向后兼容）
+     *
+     * 未在 config 中显式声明时默认 'tim'，确保旧版插件配置无需迁移即可工作。
+     */
+    transport: TransportType;
+    /** Raw merged config object */
+    config: Record<string, unknown>;
+}
+/**
+ * Extract the OpenAgent-specific config block from the full OpenClaw config.
+ * Handles multiple config key locations that have drifted across versions.
+ *
+ * v3.9+ 兼容：同时支持 `channels.oasn` / `entries.openclaw-oasn` / `entries.openclaw-plugin-oasn`，
+ * 与原有 openagent 键名并列查找。优先 oasn → openagent，便于过渡期同时挂双配置。
+ */
+export declare function getOpenagentConfig(cfg: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Resolve a specific account's configuration from OpenClaw config.
+ *
+ * @param cfg - Full OpenClaw configuration object
+ * @param accountId - Target account ID, or 'default' to pick the first available
+ */
+export declare function resolveOpenagentAccount(cfg: Record<string, unknown>, accountId?: string): OpenagentAccountConfig;
+/**
+ * List available account IDs from the config.
+ */
+export declare function listAccountIds(cfg: Record<string, unknown>): string[];