agent-bridge-hermes 1.0.2 → 1.0.3

package/README.md

@@ -4,4 +4,14 @@
 
 Windows 默认安装根目录为 `%LOCALAPPDATA%\hermes`，其他系统为 `~/.hermes`；自定义安装可配置 `hermesHome` 和 `pythonPath`。Python 入口通过官方依赖管理器加载当前环境。网关鉴权复用官方同用户私有管道票据，不开放远程网关端口。
 
+连接健康检查最多等待 120 秒，覆盖官方 Gateway 的 60 秒冷启动预算、依赖加载和首次 RPC。连接或会话操作超时明确提示未提交任务；生成任务仍使用 `timeoutMs`，超时不代表桌面任务已取消，也不会自动重发。
+
 会话返回 Hermes 的真实 ID，保存该 ID 即可续聊；`newSession` 创建独立会话。支持文本文件等普通文件以及 PNG/JPEG/WebP 图片输入，文件经官方 `file.attach` 引用，图片经 `image.attach_bytes` 及 `prompt.submit` 提交；不把附件内容伪装成文本。单个附件最多 32 MiB、每条最多 8 个、合计最多 64 MiB，并受 Hermes 自身更严格的限制约束。附件暂存失败时不提交任务。暂未实现模型生成附件的回传。任务按调用顺序执行，不自动批准工具或交互确认；需要确认时请在桌面操作。取消、卸载与超时只停止等待，已经提交的桌面任务可能继续运行；请在桌面检查，避免盲目重发。
+
+## 远端任务 Ability
+
+当前源码声明 `agent/task/run`、`agent/task/recent`、`agent/task/read`、`agent/task/switch` 和 `agent/task/new`，使用原生 Gateway 接口。`run` 接受 `{"task":"需要执行的自然语言任务"}`，未选择任务时独立新建；`switch` 或 `new` 成功后，同一 Provider 与已认证 Peer 的后续 `run` 续聊并返回 `text`、持久会话 `sessionId`，重载清除选择。
+
+`recent` 使用 Gateway 的持久化目录（`session.list scope=stored`），不宣称历史完整。`read` 只读 Gateway 已加载会话的用户和助手文字，不自动恢复或切换；未加载时需先显式 `switch`。`switch` 仅验证精确持久 ID，未加载的目标不在前 200 条可验证目录中时需先在桌面加载，正在运行的任务会拒绝切换或续聊；不以新建任务替代消失的目标。
+
+需在 AUN 中验证 Provider 的 Owner、选择发布并逐次确认执行；升级不会自动公开。任务按目标 Agent 的权限执行，Ability 仅交付文字。参数和契约见仓库[桌面 Agent Ability 使用说明](../../docs/desktop-agent-ability.md)。

package/dist/src-ts/plugins/agent-task-abilities.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTaskAbilities = void 0;
+const agent_task_ability_1 = require("./agent-task-ability");
+const idSchema = { type: "string", minLength: 1, maxLength: 512 };
+const sessionSchema = { type: "object", required: ["id", "title"], properties: { id: idSchema, title: { type: "string" }, updatedAt: { type: "string" }, updatedLabel: { type: "string" }, active: { type: "boolean" } }, additionalProperties: false };
+const pageProperties = { scope: { type: "string" }, complete: { type: "boolean" }, missingReasons: { type: "array", items: { type: "string" } }, readAt: { type: "string" }, nextCursor: { type: "string" } };
+function params(value, fields) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !fields.includes(key)))
+        throw new Error("任务能力参数无效或含未知字段");
+    return value;
+}
+function string(value, name, max) {
+    if (typeof value !== "string" || !value.trim() || value.length > max || /[\u0000-\u001f]/.test(value))
+        throw new Error(`任务${name}参数无效`);
+    return value;
+}
+function limit(value, max) {
+    if (value === undefined)
+        return 20;
+    if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > max)
+        throw new Error(`任务分页参数必须为 1–${max}`);
+    return Number(value);
+}
+/** 只统一任务契约和远程选择；桌面身份、队列及会话恢复由插件验证。 */
+class AgentTaskAbilities {
+    adapter;
+    selected = new Map();
+    generation = 0;
+    abilities;
+    constructor(adapter) {
+        this.adapter = adapter;
+        const task = (0, agent_task_ability_1.createTaskAbility)(async () => { throw new Error("任务入口未绑定"); });
+        this.abilities = [{
+                definition: { ...task.definition, contract_revision: "2", summary: "执行自然语言任务；本 Provider 与 Peer 经 switch/new 选择后续聊，否则独立新建。重载清除选择。空白页可能返回带 pending 前缀的临时逻辑句柄，首轮成功后返回原生 ID。仅交付文字，逐次确认；具体传输不支持时明确报错。", result_schema: { ...task.definition.result_schema, required: ["text", "sessionId"], properties: { ...task.definition.result_schema.properties, sessionId: idSchema } } },
+                handler: async (value, context) => {
+                    const generation = this.generation;
+                    let sessionId = "";
+                    const run = (0, agent_task_ability_1.createTaskAbility)(request => this.execute(context, "run", async () => {
+                        const key = context.callerAid ? this.key(context) : undefined;
+                        const selectedId = key ? this.selected.get(key) : undefined;
+                        const response = await this.adapter.run(request, selectedId, context);
+                        context.signal.throwIfAborted();
+                        this.checkGeneration(generation);
+                        sessionId = string(response.sessionId, "标识", 512);
+                        if (key && selectedId)
+                            this.selected.set(key, sessionId);
+                        return response;
+                    }));
+                    return { ...await run.handler(value, context), sessionId };
+                },
+            }, this.ability("recent", "最近任务", "只读目标插件原生任务目录，不切换或发送消息；scope、complete、missingReasons 说明目录范围。部分传输不支持。", { limit: { type: "integer", minimum: 1, maximum: 50 } }, [], { type: "object", required: ["sessions", "scope", "complete", "missingReasons", "readAt"], properties: { sessions: { type: "array", maxItems: 50, items: sessionSchema }, ...pageProperties }, additionalProperties: false }, ["state.read", "data.egress"], async (value, context) => {
+                const count = limit(params(value, ["limit"]).limit, 50);
+                return this.execute(context, "recent", async () => {
+                    const page = await this.adapter.recent(count, context);
+                    if (!page.supported)
+                        throw new Error(page.reason);
+                    if (page.sessions.length > count)
+                        throw new Error("任务目录返回数量超过 limit，未截断或宣称完整");
+                    const { supported: _supported, ...result } = page;
+                    return { ...result, scope: this.adapter.scope("recent") };
+                });
+            }), this.ability("read", "读取任务正文", "只读指定任务可验证的用户和助理文字，不切换或发送；部分客户端要求先 switch。范围由 scope 和完整性字段说明。", { sessionId: idSchema, limit: { type: "integer", minimum: 1, maximum: 100 }, cursor: { type: "string", minLength: 1, maxLength: 4096 } }, ["sessionId"], { type: "object", required: ["session", "turns", "scope", "complete", "missingReasons", "readAt"], properties: { session: sessionSchema, turns: { type: "array", maxItems: 100, items: { type: "object", required: ["role", "text"], properties: { id: { type: "string" }, role: { type: "string", enum: ["user", "assistant"] }, text: { type: "string", maxLength: 60_000 }, time: { type: "string" } }, additionalProperties: false } }, ...pageProperties }, additionalProperties: false }, ["state.read", "data.egress"], async (value, context) => {
+                const input = params(value, ["sessionId", "limit", "cursor"]);
+                const query = { sessionId: string(input.sessionId, "标识", 512), limit: limit(input.limit, 100), ...(input.cursor === undefined ? {} : { cursor: string(input.cursor, "游标", 4096) }) };
+                return this.execute(context, "read", async () => {
+                    const page = await this.adapter.read(query, context);
+                    if (!page.supported)
+                        throw new Error(page.reason);
+                    if (page.session.id !== query.sessionId)
+                        throw new Error("任务正文身份与请求不一致，未返回其他任务内容");
+                    if (page.turns.length > query.limit || page.turns.reduce((total, turn) => total + turn.text.length, 0) > 60_000)
+                        throw new Error("任务正文超过分页或 60,000 字符上限，请减小 limit；未截断");
+                    const { supported: _supported, ...result } = page;
+                    return { ...result, scope: this.adapter.scope("read") };
+                });
+            }), this.ability("switch", "切换任务", "只选择精确 ID 的已有任务，不发送消息；之后仅此 Provider 与认证 Peer 的 run 续聊。具体客户端不支持安全切换时明确报错。", { sessionId: idSchema }, ["sessionId"], this.selectionSchema(), ["state.read", "state.write", "system.interact"], (value, context) => this.select(value, context, false)),
+            this.ability("new", "新建任务", "新建并选择空白任务，不发送消息。未分配原生 ID 时返回带 pending 前缀的临时逻辑句柄，首轮 run 后返回原生 ID。仅本 Provider 与认证 Peer 使用，重载清除选择。", {}, [], this.selectionSchema(), ["state.read", "state.write", "system.interact"], (value, context) => this.select(value, context, true))];
+    }
+    reset() { this.generation++; this.selected.clear(); }
+    checkGeneration(generation) {
+        if (generation !== this.generation)
+            throw new Error("任务能力实例已重载，旧调用及选择已失效，请重新调用");
+    }
+    key(context) {
+        if (!context.callerAid)
+            throw new Error("缺少宿主认证的调用者身份，请升级 AUN 插件与后台后重新调用");
+        return JSON.stringify([context.providerAid, context.callerAid]);
+    }
+    async execute(context, action, work) {
+        const generation = this.generation;
+        context.signal.throwIfAborted();
+        return this.adapter.execute(context, action, async () => {
+            context.signal.throwIfAborted();
+            this.checkGeneration(generation);
+            const result = await work();
+            context.signal.throwIfAborted();
+            this.checkGeneration(generation);
+            return result;
+        });
+    }
+    async select(value, context, create) {
+        const generation = this.generation;
+        const input = params(value, create ? [] : ["sessionId"]);
+        const target = create ? undefined : string(input.sessionId, "标识", 512);
+        const key = this.key(context);
+        return this.execute(context, create ? "new" : "switch", async () => {
+            const selection = await this.adapter.select(target, context);
+            string(selection.sessionId, "标识", 512);
+            if (target && target !== selection.sessionId)
+                throw new Error("任务切换身份不一致，选择未保存");
+            context.signal.throwIfAborted();
+            this.checkGeneration(generation);
+            this.selected.set(key, selection.sessionId);
+            return selection;
+        });
+    }
+    selectionSchema() { return { type: "object", required: ["sessionId", "title"], properties: { sessionId: idSchema, title: { type: "string" } }, additionalProperties: false }; }
+    ability(action, name, summary, properties, required, result_schema, effects, handler) {
+        const definition = { path: `agent/task/${action}`, name, summary, contract_revision: "1", params_schema: { type: "object", properties, required, additionalProperties: false }, result_schema, effects, auth_required: true, require_confirm: true, idempotency: "keyed", allowed_modes: ["explicit"], aggregation: "none", dedupe_retention_seconds: 3600 };
+        return { definition, handler };
+    }
+}
+exports.AgentTaskAbilities = AgentTaskAbilities;

package/dist/src-ts/plugins/hermes/client.js

@@ -50,14 +50,15 @@ class PythonHermesTransport {
         this.helper = (0, node_path_1.join)((0, node_path_1.dirname)(__filename), "gateway-client.py");
     }
     async connect() {
-        await this.run({ op: "health" });
+        // 官方冷启动预算为 60 秒，另留依赖加载、鉴权和首次 RPC 的时间。
+        await this.run({ op: "health" }, undefined, 120_000);
         this.connectedState = true;
     }
     close() { this.connectedState = false; for (const cancel of this.pending)
         cancel(); }
-    async createSession(title) {
+    async createSession(title, signal) {
         this.requireConnected();
-        const value = await this.run({ op: "create", title });
+        const value = await this.run({ op: "create", title }, signal);
         if (!value || typeof value.sessionId !== "string" || !value.sessionId)
             throw new Error("Hermes Gateway 未返回会话 ID");
         return value.sessionId;
@@ -66,6 +67,24 @@ class PythonHermesTransport {
         this.requireConnected();
         await this.run({ op: "resume", sessionId });
     }
+    async listSessions(limit, signal) {
+        return (await this.run({ op: "recent", limit }, signal)).page;
+    }
+    async readSession(query, signal) {
+        return (await this.run({ op: "read", ...query }, signal)).page;
+    }
+    async selectSession(sessionId, signal) {
+        const value = await this.run({ op: "select", sessionId }, signal);
+        if (value.sessionId !== sessionId || typeof value.title !== "string")
+            throw new Error("Hermes 精确会话身份不一致");
+        return { sessionId, title: value.title };
+    }
+    async completeSelected(task, sessionId, timeoutMs = this.timeoutMs, signal) {
+        const value = await this.run({ op: "completeSelected", task, sessionId, timeoutMs }, signal, timeoutMs + 15_000);
+        if (value.sessionId !== sessionId || typeof value.text !== "string" || !value.text.trim())
+            throw new Error("Hermes 精确会话回复无效");
+        return { sessionId, text: value.text };
+    }
     async complete(task, sessionId, timeoutMs = this.timeoutMs, signal, attachments) {
         this.requireConnected();
         (0, attachments_1.validateAttachments)(attachments);
@@ -94,7 +113,11 @@ class PythonHermesTransport {
                 const cancel = () => { child.kill(); finish(new Error("Hermes 已停止等待，桌面任务可能仍在运行，请在桌面检查")); };
                 const abort = cancel;
                 this.pending.add(cancel);
-                const timer = setTimeout(() => { child.kill(); finish(new Error("Hermes Gateway 等待超时，桌面任务可能仍在运行，请在桌面检查")); }, Math.max(1_000, timeoutMs));
+                const timer = setTimeout(() => {
+                    child.kill();
+                    const submitted = payload.op === "complete" || payload.op === "completeSelected";
+                    finish(new Error(submitted ? "Hermes Gateway 等待超时，桌面任务可能仍在运行，请在桌面检查" : "Hermes Gateway 连接或会话操作等待超时，未提交任务；请检查官方 Gateway 状态"));
+                }, Math.max(1_000, timeoutMs));
                 signal?.addEventListener("abort", abort, { once: true });
                 child.stdout.setEncoding("utf8");
                 child.stdout.on("data", chunk => { stdout += String(chunk); if (stdout.length > 8 * 1024 * 1024)
@@ -134,9 +157,29 @@ class HermesGatewayClient {
     connected() { return this.isConnected; }
     async connect() { await this.transport.connect(); this.isConnected = true; }
     close() { this.transport.close(); this.isConnected = false; }
-    createSession(title) { return this.transport.createSession(title); }
+    createSession(title, signal) { return this.transport.createSession(title, signal); }
     resumeSession(sessionId) { return this.transport.resumeSession(sessionId); }
     complete(task, sessionId, timeoutMs, signal, attachments) { return this.transport.complete(task, sessionId, timeoutMs, signal, attachments); }
+    listSessions(limit, signal) {
+        if (!this.transport.listSessions)
+            return Promise.reject(new Error("Hermes 当前传输不支持原生任务目录"));
+        return this.transport.listSessions(limit, signal);
+    }
+    readSession(query, signal) {
+        if (!this.transport.readSession)
+            return Promise.reject(new Error("Hermes 当前传输不支持原生任务正文"));
+        return this.transport.readSession(query, signal);
+    }
+    selectSession(sessionId, signal) {
+        if (!this.transport.selectSession)
+            return Promise.reject(new Error("Hermes 当前传输不支持精确任务选择"));
+        return this.transport.selectSession(sessionId, signal);
+    }
+    completeSelected(task, sessionId, timeoutMs, signal) {
+        if (!this.transport.completeSelected)
+            return Promise.reject(new Error("Hermes 当前传输不支持精确任务续聊"));
+        return this.transport.completeSelected(task, sessionId, timeoutMs, signal);
+    }
 }
 exports.HermesGatewayClient = HermesGatewayClient;
 function sessionTitle(task) {

package/dist/src-ts/plugins/hermes/gateway-client.py

@@ -1,5 +1,8 @@
 import asyncio
+import base64
 from contextlib import suppress
+from datetime import datetime, timezone
+import hashlib
 import json
 import os
 import sys
@@ -46,14 +49,36 @@ async def operate(client, request):
         return {"ok": True}
     if operation == "create":
         snapshot = await client.rpc("session.create", source="gui", request_id=str(uuid.uuid4()), title=str(request.get("title") or "Agent Bridge"))
-        return {"ok": True, "sessionId": snapshot["session_id"]}
+        return {"ok": True, "sessionId": snapshot.get("stored_session_id") or snapshot["session_id"]}
+    if operation == "recent":
+        limit = page_limit(request, 50)
+        rows = (await client.rpc("session.list", scope="stored", limit=limit + 1)).get("sessions")
+        if not isinstance(rows, list):
+            fail("Hermes 原生任务目录格式无效")
+        sessions = []
+        for row in rows[:limit]:
+            if not isinstance(row, dict) or not isinstance(row.get("id"), str) or not row["id"]:
+                fail("Hermes 原生任务目录缺少精确 ID")
+            sessions.append({"id": row["id"], "title": str(row.get("title") or "")})
+        return {"ok": True, "page": {"supported": True, "sessions": sessions, "complete": False,
+                "missingReasons": ["仅当前配置的持久化目录，不含未持久化空白任务；Gateway 未返回总数或更新时间"], "readAt": read_at()}}
     session_id = str(request.get("sessionId") or "")
     if not session_id:
         fail("Hermes 会话 ID 不能为空")
-    await client.rpc("session.resume", session_id=session_id)
+    if operation == "read":
+        return await read_history(client, request, session_id)
+    response_id = session_id
+    if operation in ("select", "completeSelected"):
+        session_id, title = await select_exact(client, session_id)
+        if operation == "select":
+            return {"ok": True, "sessionId": response_id, "title": title}
+    else:
+        snapshot = await client.rpc("session.resume", session_id=session_id)
+        session_id = snapshot.get("session_id") or session_id
+        response_id = snapshot.get("stored_session_id") or snapshot.get("session_key") or response_id
     if operation == "resume":
         return {"ok": True}
-    if operation != "complete":
+    if operation not in ("complete", "completeSelected"):
         fail("不支持的 Hermes 操作")
     text = str(request.get("task") or "")
     images = []
@@ -93,11 +118,120 @@ async def operate(client, request):
             text = result.get("final_response")
             if not isinstance(text, str) or not text.strip():
                 fail("Hermes Gateway 未返回文字")
-            return {"ok": True, "sessionId": session_id, "text": text}
+            return {"ok": True, "sessionId": response_id, "text": text}
         await asyncio.sleep(0.5)
     fail("Hermes Gateway 等待超时，桌面任务可能仍在运行，请在桌面检查")
 
 
+def read_at():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def page_limit(request, maximum):
+    value = request.get("limit", 20)
+    if type(value) is not int or not 1 <= value <= maximum:
+        fail("Hermes 任务分页参数无效")
+    return value
+
+
+async def live_session(client, session_id):
+    rows = (await client.rpc("session.active_list")).get("sessions")
+    if not isinstance(rows, list):
+        fail("Hermes 已加载会话目录格式无效")
+    return next((row for row in rows if isinstance(row, dict) and
+                 (row.get("session_key") == session_id or row.get("id") == session_id)), None)
+
+
+async def select_exact(client, session_id):
+    row = await live_session(client, session_id)
+    if row:
+        if row.get("status") != "idle":
+            fail("Hermes 目标任务正在运行或状态未知，请稍后重试")
+    else:
+        # shortcut: 原生目录没有按 ID 查询，超过 200 条时先在桌面加载目标后再切换。
+        rows = (await client.rpc("session.list", scope="stored", limit=200)).get("sessions")
+        if not isinstance(rows, list):
+            fail("Hermes 原生任务目录格式无效")
+        row = next((item for item in rows if isinstance(item, dict) and item.get("id") == session_id), None)
+        if row is None:
+            fail("Hermes 未找到精确任务 ID；目标不存在或不在可验证目录，请先在桌面加载")
+    snapshot = await client.rpc("session.resume", session_id=row.get("session_key") or session_id, omit_messages=True)
+    runtime_id = snapshot.get("session_id")
+    actual = snapshot.get("stored_session_id") or snapshot.get("session_key")
+    if not runtime_id or snapshot.get("session_id") != runtime_id or actual != (row.get("session_key") or session_id):
+        fail("Hermes 精确会话身份不一致，未提交任务或保存选择")
+    if snapshot.get("running") is not False:
+        fail("Hermes 目标任务正在运行或状态未知，请稍后重试")
+    return runtime_id, str(row.get("title") or "")
+
+
+async def read_history(client, request, session_id):
+    limit = page_limit(request, 100)
+    row = await live_session(client, session_id)
+    if row is None:
+        fail("Hermes 任务未加载，无法只读正文；请先显式 switch，不会自动恢复或切换")
+    history = await client.rpc("session.history", session_id=row["id"])
+    current = await live_session(client, session_id)
+    if current is None or current.get("id") != row["id"] or current.get("session_key") != row.get("session_key"):
+        fail("Hermes 精确目标已消失或变化，请重新读取")
+    messages = history.get("messages")
+    if not isinstance(messages, list):
+        fail("Hermes 原生任务正文格式无效")
+    native_count = history.get("count")
+    if type(native_count) is not int or native_count < len(messages):
+        fail("Hermes 原生任务正文数量格式无效")
+    turns = []
+    omitted = native_count != len(messages)
+    for message in messages:
+        if not isinstance(message, dict):
+            fail("Hermes 原生任务消息格式无效")
+        text = message.get("text")
+        if (message.get("role") not in ("user", "assistant") or not isinstance(text, str) or not text.strip()
+                or message.get("channel") in ("analysis", "reasoning")
+                or message.get("display_kind") in ("hidden", "analysis", "reasoning")):
+            omitted = True
+            continue
+        turn = {"role": message["role"], "text": text}
+        if message.get("row_id") is not None:
+            turn["id"] = str(message["row_id"])
+        timestamp = message.get("timestamp")
+        if type(timestamp) in (int, float) and timestamp > 0:
+            turn["time"] = datetime.fromtimestamp(timestamp, timezone.utc).isoformat()
+        turns.append(turn)
+        omitted = omitted or any(message.get(field) for field in (
+            "reasoning", "thinking", "reasoning_content", "reasoning_details",
+            "codex_reasoning_items", "codex_message_items", "tool_calls", "attachments"))
+    snapshot = hashlib.sha256(json.dumps([session_id, turns], ensure_ascii=False, sort_keys=True).encode("utf8")).hexdigest()
+    start = 0
+    cursor = request.get("cursor")
+    if cursor is not None:
+        try:
+            if not isinstance(cursor, str) or not 1 <= len(cursor) <= 4096:
+                raise ValueError()
+            decoded = json.loads(base64.urlsafe_b64decode(cursor + "=" * (-len(cursor) % 4)))
+            if (set(decoded) != {"sessionId", "snapshot", "offset"} or decoded["sessionId"] != session_id
+                    or decoded["snapshot"] != snapshot or type(decoded["offset"]) is not int
+                    or not 0 < decoded["offset"] < len(turns)):
+                raise ValueError()
+            start = decoded["offset"]
+        except Exception:
+            fail("Hermes 正文游标或快照无效，请重新读取")
+    selected = turns[start:start + limit]
+    if sum(len(turn["text"].encode("utf-16le")) // 2 for turn in selected) > 60000:
+        fail("Hermes 任务正文超过 60,000 字符，请减小 limit；未截断")
+    end = start + len(selected)
+    missing = ["仅返回 Gateway 可验证的用户和助理文字；推理、工具及非文字内容不交付"] if omitted else []
+    if current.get("status") != "idle":
+        missing.append("任务正在运行或状态未知，正文可能尚未落入完整历史")
+    if end < len(turns):
+        missing.append("正文尚有后续分页")
+    page = {"supported": True, "session": {"id": session_id, "title": str(row.get("title") or "")},
+            "turns": selected, "complete": not missing, "missingReasons": missing, "readAt": read_at()}
+    if end < len(turns):
+        page["nextCursor"] = base64.urlsafe_b64encode(json.dumps({"sessionId": session_id, "snapshot": snapshot, "offset": end}).encode("utf8")).decode("ascii").rstrip("=")
+    return {"ok": True, "page": page}
+
+
 try:
     sys.stdin.reconfigure(encoding="utf-8")
     sys.stdout.reconfigure(encoding="utf-8")
@@ -107,4 +241,12 @@ try:
 except SystemExit:
     raise
 except Exception as exc:
-    fail("Hermes Gateway 通信失败，请在桌面检查连接与任务状态")
+    # 只暴露异常类型和官方枚举状态，不能把含凭据的异常正文回传。
+    kind = type(exc).__name__
+    state = getattr(exc, "state", None)
+    reason = getattr(exc, "reason_code", None)
+    details = [kind]
+    for value in (state, reason):
+        if isinstance(value, str) and value and all(c.isascii() and (c.isalnum() or c in "_-") for c in value):
+            details.append(value)
+    fail("Hermes Gateway 通信失败（" + "/".join(details) + "），请在桌面检查连接与任务状态")

package/dist/src-ts/plugins/hermes/index.js

@@ -2,18 +2,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HermesPlugin = exports.hermesManifest = void 0;
 const attachments_1 = require("../../attachments");
-const agent_task_ability_1 = require("../agent-task-ability");
+const agent_task_abilities_1 = require("../agent-task-abilities");
 const agent_1 = require("../../agent");
 const client_1 = require("./client");
 exports.hermesManifest = {
-    id: "hermes", version: "1.0.2", displayName: "Hermes Desktop", type: "agent",
+    id: "hermes", version: "1.0.3", displayName: "Hermes Desktop", type: "agent",
     entry: "dist/src-ts/plugins/hermes/index.js", apiVersion: "1", process: "in-process",
     capabilities: ["chat", "health"], configSchema: "config.schema.json",
 };
 class HermesPlugin {
     options;
     manifest = exports.hermesManifest;
-    abilities = [createReadinessAbility(() => this.health()), (0, agent_task_ability_1.createTaskAbility)(request => this.handle(request))];
+    taskAbilities = new agent_task_abilities_1.AgentTaskAbilities({
+        execute: (context, _action, work) => this.enqueue(work, context.signal),
+        scope: () => "Hermes Gateway 当前配置的持久化任务目录；正文仅限已加载会话，不自动恢复或切换",
+        recent: (limit, context) => this.requireClient().listSessions(limit, context.signal),
+        read: (query, context) => this.requireClient().readSession(query, context.signal),
+        select: async (sessionId, context) => sessionId
+            ? this.requireClient().selectSession(sessionId, context.signal)
+            : { sessionId: await this.requireClient().createSession((0, client_1.sessionTitle)("远程新任务"), context.signal), title: "远程新任务" },
+        run: async (request, selectedId, context) => selectedId
+            ? this.requireClient().completeSelected(request.task, selectedId, request.timeoutMs ?? this.timeoutMs, context.signal)
+            : this.runTask(request),
+    });
+    abilities = [createReadinessAbility(() => this.health()), ...this.taskAbilities.abilities.map(ability => ({
+            ...ability,
+            handler: (params, context) => ability.handler(params, { ...context, signal: AbortSignal.any([context.signal, this.lifetime.signal]) }),
+        }))];
     sessionOperations = ["new"];
     attachmentInput = true;
     client;
@@ -33,6 +48,7 @@ class HermesPlugin {
             transport: this.options.transport,
         };
         this.failure = undefined;
+        this.taskAbilities.reset();
         this.lifetime = new AbortController();
         this.client = this.options.client ?? new client_1.HermesGatewayClient(options);
         try {
@@ -47,6 +63,7 @@ class HermesPlugin {
     }
     async deactivate(_reason, _options) {
         this.lifetime.abort(new Error("Hermes 插件已停用"));
+        this.taskAbilities.reset();
         this.client?.close();
         this.client = undefined;
     }
@@ -64,9 +81,18 @@ class HermesPlugin {
     }
     handle(request) {
         const signal = request.signal ? AbortSignal.any([request.signal, this.lifetime.signal]) : this.lifetime.signal;
-        const result = this.queue.then(() => this.runTask({ ...request, signal }));
+        return this.enqueue(() => this.runTask({ ...request, signal }), signal);
+    }
+    requireClient() {
+        if (!this.client?.connected())
+            throw new Error("Hermes 插件未连接 Gateway");
+        return this.client;
+    }
+    enqueue(work, signal) {
+        const lifetime = this.lifetime.signal;
+        const result = this.queue.then(async () => { lifetime.throwIfAborted(); signal?.throwIfAborted(); return work(); });
         this.queue = result.catch(() => undefined);
-        return (0, agent_1.abortable)(result, request.signal);
+        return (0, agent_1.abortable)(result, signal);
     }
     async runTask(request) {
         (0, attachments_1.validateAttachments)(request.attachments);
@@ -96,7 +122,7 @@ class HermesPlugin {
     }
     async resolveSession(client, request, task) {
         if (request.newSession || !request.sessionId) {
-            return client.createSession((0, client_1.sessionTitle)(task));
+            return client.createSession((0, client_1.sessionTitle)(task), request.signal);
         }
         await client.resumeSession(request.sessionId);
         return request.sessionId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bridge-hermes",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "mu-agent-bridge 的 Hermes 桌面原生网关插件。",
   "keywords": [
     "mu-agent-bridge-plugin",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "hermes",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "displayName": "Hermes Desktop",
   "type": "agent",
   "entry": "dist/src-ts/plugins/hermes/index.js",