openclaw-openagent 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenAgent Plugin — Entry point
+ *
+ * Registers the channel adapter, tools, and hooks with OpenClaw.
+ *
+ * Aligned with openclaw-weixin v2.1.1 plugin entry pattern.
+ * Reference: docs/reference/plugins/openclaw-weixin-latest-v2.1.1/index.ts
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/plugin-entry';
+export declare function getOpenagentRuntime(): OpenClawPluginApi['runtime'] | undefined;
+export declare function setOpenagentRuntime(runtime: OpenClawPluginApi['runtime']): void;
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: unknown;
+    contracts: {
+        tools: string[];
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default _default;
+export { openagentPlugin } from './src/channel.js';
+export { registerTools, registerHooks } from './src/app/index.js';
+export { registry } from './src/runtime/registry.js';

package/dist/index.js

@@ -0,0 +1,105 @@
+/**
+ * OpenAgent Plugin — Entry point
+ *
+ * Registers the channel adapter, tools, and hooks with OpenClaw.
+ *
+ * Aligned with openclaw-weixin v2.1.1 plugin entry pattern.
+ * Reference: docs/reference/plugins/openclaw-weixin-latest-v2.1.1/index.ts
+ */
+import { buildChannelConfigSchema } from 'openclaw/plugin-sdk/channel-config-schema';
+import { openagentPlugin } from './src/channel.js';
+import { assertHostCompatibility } from './src/compat.js';
+import { OpenagentConfigSchema } from './src/config/config-schema.js';
+import { registerTools, registerHooks } from './src/app/index.js';
+import { installOpenagentVerbosePreflight } from './src/app/verbose-preflight.js';
+// guard.ts removed — unhandled rejections fixed at source in ws-frame.ts send()
+import { setOpenagentPluginRuntime } from './src/runtime/plugin-runtime.js';
+import { injectControlUiOverride } from './src/plugin-ui/index.js';
+import { createAuthProxyHandler } from './src/proxy/auth-proxy.js';
+import { logger } from './src/util/logger.js';
+// ── Runtime reference ─────────────────────────────────────────────────────
+// Saved from api.runtime during register(), accessible by other modules.
+let _runtime;
+export function getOpenagentRuntime() {
+    return _runtime;
+}
+export function setOpenagentRuntime(runtime) {
+    _runtime = runtime;
+}
+// ── Plugin entry ──────────────────────────────────────────────────────────
+export default {
+    id: 'openclaw-openagent',
+    name: 'OpenAgent',
+    // v3.9+ 双轨抽象：transport 字段决定走 OASN HTTP API 或腾讯 IM C2C。
+    // description 同时覆盖两条路径，避免误导用户以为只能用 IM。
+    description: 'OpenAgent channel plugin — connects to remote agents on the OASN agent network via HTTP API ' +
+        '(transport=oasn) or Tencent IM C2C (transport=tim, default).',
+    configSchema: buildChannelConfigSchema(OpenagentConfigSchema),
+    // 2026.6.9+: Gateway requires plugins to declare tool contracts before registering them.
+    contracts: {
+        tools: [
+            'openagent_call_remote_agent',
+            'openagent_search_agents',
+            'openagent_get_agent_detail',
+            'openagent_upload_file',
+            'openagent_download_file',
+        ],
+    },
+    register(api) {
+        logger.info('[entry] register() called');
+        // P1-1: Fail-fast — reject incompatible host versions before any side-effects.
+        assertHostCompatibility(api.runtime?.version);
+        logger.info(`[entry] Host version: ${api.runtime?.version ?? 'unknown'}`);
+        // P0: TIM rejection guard removed — root cause fixed in ws-frame.ts send() with p.catch(() => {}).
+        // P1-3: Save runtime reference for use by other modules (logging, config, etc.)
+        if (api.runtime) {
+            setOpenagentRuntime(api.runtime);
+            setOpenagentPluginRuntime(api.runtime);
+            installOpenagentVerbosePreflight(api);
+            logger.info('[entry] Runtime reference saved');
+        }
+        // Always register the channel adapter (needed even in setup-only mode).
+        api.registerChannel({ plugin: openagentPlugin });
+        logger.info('[entry] Channel adapter registered');
+        // P1-2: registrationMode exists in 2026.3.22+; skip heavy registrations in
+        // setup-only mode (e.g. `openclaw channels list`).
+        const mode = api.registrationMode;
+        if (mode && mode !== 'full') {
+            logger.info(`[entry] Setup-only mode (registrationMode=${mode}), skipping tools/hooks`);
+            return;
+        }
+        // Full mode — register tools and hooks.
+        registerTools(api);
+        registerHooks(api);
+        // Auth proxy — same-origin reverse proxy to bypass CSP connect-src.
+        // Browser fetches /plugins/openagent/* → Gateway proxies to auth.ai-talk.live.
+        // Covers both API calls (/api/agents) and static assets (/avatars/oc1.png).
+        // Replaces the fragile patchCsp() approach (see docs/audit/022-A §4.6–4.10).
+        try {
+            if (typeof api.registerHttpRoute !== 'function') {
+                logger.warn('[entry] api.registerHttpRoute is NOT a function — type: ' + typeof api.registerHttpRoute);
+            }
+            else {
+                api.registerHttpRoute({
+                    path: '/plugins/openagent',
+                    auth: 'plugin',
+                    match: 'prefix',
+                    handler: createAuthProxyHandler(),
+                });
+                logger.info('[entry] Auth proxy route registered (prefix: /plugins/openagent)');
+            }
+        }
+        catch (routeErr) {
+            logger.warn(`[entry] registerHttpRoute failed: ${routeErr.message}`);
+        }
+        // Auto-inject Control UI override (copies openagent-override.js + patches)
+        injectControlUiOverride().catch(err => {
+            logger.warn(`[entry] Control UI injection failed: ${err.message}`);
+        });
+        logger.info('[entry] Tools + hooks registered (full mode)');
+    },
+};
+// Named exports for direct imports
+export { openagentPlugin } from './src/channel.js';
+export { registerTools, registerHooks } from './src/app/index.js';
+export { registry } from './src/runtime/registry.js';

package/dist/src/app/channel-tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Channel Tools — 8 channel management tools
+ *
+ * list_channels, search_channels, join_channel, leave_channel,
+ * create_channel, get_members, set_channel_skill, get_channel_skill
+ *
+ * Contract ref: §0.2 refactoring-plan.md
+ */
+import { type ToolDescriptor } from './types.js';
+export declare function createListChannelsTool(): ToolDescriptor;
+export declare function createSearchChannelsTool(): ToolDescriptor;
+/**
+ * join_channel — supports optional `purpose?` per §0.2.
+ * If purpose is provided, it is stored via setPurpose().
+ */
+export declare function createJoinChannelTool(): ToolDescriptor;
+export declare function createLeaveChannelTool(): ToolDescriptor;
+/**
+ * create_channel — supports optional `channelId?`, `skill?`, `desc?` per §0.2.
+ * If channelId is not given, auto-generates one.
+ */
+export declare function createCreateChannelTool(): ToolDescriptor;
+/**
+ * get_members — returns avatar? field per §0.2.
+ */
+export declare function createGetMembersTool(): ToolDescriptor;
+export declare function createSetChannelSkillTool(): ToolDescriptor;
+export declare function createGetChannelSkillTool(): ToolDescriptor;

package/dist/src/app/channel-tools.js

@@ -0,0 +1,251 @@
+/**
+ * Channel Tools — 8 channel management tools
+ *
+ * list_channels, search_channels, join_channel, leave_channel,
+ * create_channel, get_members, set_channel_skill, get_channel_skill
+ *
+ * Contract ref: §0.2 refactoring-plan.md
+ */
+import { registry } from '../runtime/registry.js';
+import { toolResult } from './types.js';
+function fail(error) {
+    return toolResult(JSON.stringify({ success: false, error }));
+}
+function getRuntime() {
+    const rt = registry.getDefault();
+    if (!rt || !rt.isRunning)
+        return null;
+    return rt;
+}
+export function createListChannelsTool() {
+    return {
+        name: 'openagent_list_channels',
+        label: 'List OpenAgent Channels',
+        description: 'List all available channels on OpenAgent agent network',
+        parameters: { type: 'object', properties: {}, required: [] },
+        async execute() {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                const channels = await rt.listChannels();
+                return toolResult(JSON.stringify({ success: true, channels }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+export function createSearchChannelsTool() {
+    return {
+        name: 'openagent_search_channels',
+        label: 'Search OpenAgent Channels',
+        description: 'Search channels by keyword',
+        parameters: {
+            type: 'object',
+            properties: { keyword: { type: 'string', description: 'Search keyword' } },
+            required: ['keyword'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                const channels = await rt.searchChannels(String(params.keyword || ''));
+                return toolResult(JSON.stringify({ success: true, channels }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+/**
+ * join_channel — supports optional `purpose?` per §0.2.
+ * If purpose is provided, it is stored via setPurpose().
+ */
+export function createJoinChannelTool() {
+    return {
+        name: 'openagent_join_channel',
+        label: 'Join OpenAgent Channel',
+        description: 'Join a channel by ID (e.g. ch-001). Optionally set a purpose for this channel.',
+        parameters: {
+            type: 'object',
+            properties: {
+                channelId: { type: 'string', description: 'Channel ID to join' },
+                purpose: { type: 'string', description: 'Optional: your purpose/goal for this channel' },
+            },
+            required: ['channelId'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                const channelId = String(params.channelId);
+                const result = await rt.joinChannel(channelId);
+                if (result.success && rt.store) {
+                    rt.store.markJoined(channelId, channelId);
+                    if (params.purpose) {
+                        rt.store.setPurpose(channelId, String(params.purpose));
+                    }
+                }
+                return toolResult(JSON.stringify({
+                    success: result.success,
+                    channelId,
+                    purpose: params.purpose ? String(params.purpose) : undefined,
+                }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+export function createLeaveChannelTool() {
+    return {
+        name: 'openagent_leave_channel',
+        label: 'Leave OpenAgent Channel',
+        description: 'Leave a channel by ID',
+        parameters: {
+            type: 'object',
+            properties: { channelId: { type: 'string', description: 'Channel ID to leave' } },
+            required: ['channelId'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                const channelId = String(params.channelId);
+                const result = await rt.leaveChannel(channelId);
+                if (result.success && rt.store) {
+                    rt.store.markLeft(channelId);
+                }
+                return toolResult(JSON.stringify(result));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+/**
+ * create_channel — supports optional `channelId?`, `skill?`, `desc?` per §0.2.
+ * If channelId is not given, auto-generates one.
+ */
+export function createCreateChannelTool() {
+    return {
+        name: 'openagent_create_channel',
+        label: 'Create OpenAgent Channel',
+        description: 'Create a new channel. You become the owner and are automatically joined.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Channel display name (e.g. "AI Research Discussion")' },
+                desc: { type: 'string', description: 'Short description of the channel topic' },
+                skill: { type: 'string', description: 'Optional initial channel skill/rules' },
+            },
+            required: ['name'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                // Community groups: SDK auto-generates @TGS#_ prefixed groupID
+                const result = await rt.createChannel(String(params.name), String(params.desc || ''), params.skill ? String(params.skill) : undefined);
+                return toolResult(JSON.stringify(result));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+/**
+ * get_members — returns avatar? field per §0.2.
+ */
+export function createGetMembersTool() {
+    return {
+        name: 'openagent_get_members',
+        label: 'Get Channel Members',
+        description: 'Get the member list of a channel',
+        parameters: {
+            type: 'object',
+            properties: { channelId: { type: 'string', description: 'Channel ID' } },
+            required: ['channelId'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                const members = await rt.getMembers(String(params.channelId));
+                // Preserve all fields including avatar? per contract
+                return toolResult(JSON.stringify({ success: true, members }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+export function createSetChannelSkillTool() {
+    return {
+        name: 'openagent_set_channel_skill',
+        label: 'Set Channel Skill',
+        description: 'Set the skill/behavior rules for a channel',
+        parameters: {
+            type: 'object',
+            properties: {
+                channelId: { type: 'string', description: 'Channel ID' },
+                skill: { type: 'string', description: 'Channel rules that control agent behavior' },
+            },
+            required: ['channelId', 'skill'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                await rt.setChannelSkill(String(params.channelId), String(params.skill));
+                return toolResult(JSON.stringify({ success: true, message: `Skill set for ${params.channelId}` }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+export function createGetChannelSkillTool() {
+    return {
+        name: 'openagent_get_channel_skill',
+        label: 'Get Channel Skill',
+        description: 'Get the current skill/behavior rules for a channel',
+        parameters: {
+            type: 'object',
+            properties: {
+                channelId: { type: 'string', description: 'Channel ID' },
+            },
+            required: ['channelId'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                const skill = await rt.getChannelSkill(String(params.channelId));
+                return toolResult(JSON.stringify({
+                    success: true,
+                    channelId: params.channelId,
+                    skill: skill || '(no skill set)',
+                }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}

package/dist/src/app/discovery-tools.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Discovery Tools — Agent 搜索 / Agent 详情
+ *
+ * 封装 OASN DiscoveryTransport 能力为 LLM 可用工具。
+ * 当前仅 OASN 模式可用；TIM 模式下工具返回明确错误。
+ *
+ * 设计依据：docs/specs/2026-06-21-oasn-agent-search-tool-wiring.md
+ *
+ * 工具列表：
+ *   - openagent_search_agents    — 按关键词 / 分类 / 标签搜索 Agent
+ *   - openagent_get_agent_detail  — 查看单个 Agent 详情
+ *
+ * 注：getCategories() 传输层能力保留给 Agent Book UI 使用，不暴露为 LLM 工具。
+ */
+import { type ToolFactory } from './types.js';
+/**
+ * 搜索可用 Agent。
+ *
+ * 三种搜索模式（互斥，按优先级）：
+ *   1. query   — 自然语言搜索（POST /api/agent-cards/search/by-query）
+ *   2. category — 分类浏览（POST /api/agent-cards/search/by-category）
+ *   3. tags    — 标签筛选（POST /api/agent-cards/search/by-tags）
+ *
+ * LLM 使用场景：
+ *   - 用户说"我想去旅行" → search_agents({ query: "旅行" })
+ *   - 用户说"找个机票助手" → search_agents({ query: "机票" })
+ *   - 用户说"看看有哪些旅行类 Agent" → search_agents({ category: ["travel"] })
+ */
+export declare const createSearchAgentsTool: ToolFactory;
+/**
+ * 查看单个 Agent 详情。
+ *
+ * 在搜索结果中选择了一个 Agent 后，可以调用此工具获取完整信息（包括 MOM）。
+ */
+export declare const createGetAgentDetailTool: ToolFactory;