@mininglamp-oss/octo-runtime 0.0.0-stage → 1.0.0

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-wecom/dist/transport/connection.js

@@ -0,0 +1,219 @@
+/**
+ * 企业微信长连接：处理机器人鉴权、心跳 ACK、请求匹配和断线通知。
+ * 被其他连接替换时停止本连接，避免两个实例争抢同一账号；不管理模型执行。
+ */
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+/** 企业微信 IM 传输：鉴权、心跳、消息回调和回复；不是 MCP 连接器，不发起 AgentRun。 */
+export class WecomConnection {
+    callbacks;
+    #url;
+    #heartbeatIntervalMs;
+    #requestTimeoutMs;
+    #socket;
+    #closing;
+    #heartbeat;
+    #ping;
+    #closed = false;
+    #status = { connected: false, heartbeatAcks: 0 };
+    #pending = new Map();
+    constructor(options = {}, callbacks = {}) {
+        this.callbacks = callbacks;
+        this.#url = options.wsUrl ?? "wss://openws.work.weixin.qq.com";
+        const url = new URL(this.#url);
+        if (url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            (url.protocol !== "wss:" &&
+                !(url.protocol === "ws:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))) {
+            throw new Error("WECOM_WS_URL_INVALID");
+        }
+        this.#heartbeatIntervalMs = options.heartbeatIntervalMs ?? 30_000;
+        this.#requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
+        for (const value of [this.#heartbeatIntervalMs, this.#requestTimeoutMs]) {
+            if (!Number.isSafeInteger(value) || value < 1 || value > 300_000)
+                throw new Error("WECOM_TIMEOUT_INVALID");
+        }
+    }
+    get status() {
+        return { ...this.#status };
+    }
+    async connect(credentials) {
+        if (this.#socket || this.#closed)
+            throw new Error("WECOM_CONNECTION_ALREADY_USED");
+        if (typeof credentials.appBot !== "string" ||
+            !credentials.appBot.trim() ||
+            typeof credentials.appSecret !== "string" ||
+            !credentials.appSecret.trim())
+            throw new Error("WECOM_CREDENTIALS_REQUIRED");
+        const socket = new WebSocket(this.#url, {
+            handshakeTimeout: this.#requestTimeoutMs,
+            maxPayload: 1024 * 1024,
+            followRedirects: false
+        });
+        this.#socket = socket;
+        socket.on("message", (data, binary) => {
+            try {
+                if (binary)
+                    throw new Error("WECOM_FRAME_INVALID");
+                const bytes = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+                const frame = JSON.parse(bytes.toString());
+                if (!frame || typeof frame !== "object" || Array.isArray(frame))
+                    throw new Error("WECOM_FRAME_INVALID");
+                if (frame.cmd === "aibot_event_callback" &&
+                    frame.body?.event?.eventtype === "disconnected_event") {
+                    this.#fail("WECOM_CONNECTION_REPLACED");
+                    return;
+                }
+                if (frame.cmd === "aibot_msg_callback") {
+                    this.callbacks.onMessage?.(frame);
+                    return;
+                }
+                // 回调推送不是鉴权或心跳 ACK，不记录其正文。
+                if (frame.cmd)
+                    return;
+                const reqId = frame.headers?.req_id;
+                if (typeof reqId !== "string")
+                    return;
+                // ACK 必须回到对应请求；不能把普通推送或过期 ACK 当作鉴权/心跳成功。
+                const pending = this.#pending.get(reqId);
+                if (!pending)
+                    return;
+                clearTimeout(pending.timer);
+                this.#pending.delete(reqId);
+                if (frame.errcode === 0)
+                    pending.resolve();
+                else {
+                    const code = Number.isSafeInteger(frame.errcode) ? String(frame.errcode) : "INVALID_ACK";
+                    pending.reject(new Error(`WECOM_${pending.command === "aibot_subscribe" ? "AUTH" : pending.command === "ping" ? "HEARTBEAT" : "REPLY"}_REJECTED_${code}`));
+                }
+            }
+            catch {
+                this.#fail("WECOM_FRAME_INVALID");
+            }
+        });
+        socket.on("error", () => this.#fail("WECOM_WS_ERROR"));
+        socket.on("close", () => {
+            if (!this.#closed)
+                this.#fail("WECOM_DISCONNECTED");
+        });
+        try {
+            await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    socket.off("open", opened);
+                    socket.off("close", failed);
+                    socket.off("error", failed);
+                };
+                const opened = () => {
+                    cleanup();
+                    resolve();
+                };
+                const failed = () => {
+                    cleanup();
+                    reject(new Error(this.#status.error ?? "WECOM_DISCONNECTED"));
+                };
+                socket.once("open", opened);
+                socket.once("close", failed);
+                socket.once("error", failed);
+            });
+            await this.#request("aibot_subscribe", {
+                bot_id: credentials.appBot,
+                secret: credentials.appSecret
+            });
+            if (this.#closed || socket.readyState !== WebSocket.OPEN)
+                throw new Error("WECOM_DISCONNECTED");
+            this.#status.connected = true;
+            this.#status.authenticatedAt = new Date().toISOString();
+            this.#heartbeat = setInterval(() => {
+                void this.ping().catch(() => { }); // ping 已记录错误并关闭失效连接。
+            }, this.#heartbeatIntervalMs);
+            this.#heartbeat.unref();
+        }
+        catch (error) {
+            const code = error instanceof Error ? error.message : "WECOM_CONNECTION_FAILED";
+            this.#fail(code);
+            throw new Error(this.#status.error, { cause: error });
+        }
+    }
+    /** 只有 req_id 匹配且 errcode=0 的服务端回执才计为心跳成功。 */
+    ping() {
+        if (this.#ping)
+            return this.#ping;
+        if (!this.#status.connected || this.#closed)
+            return Promise.reject(new Error("WECOM_NOT_READY"));
+        this.#ping = this.#request("ping")
+            .then(() => {
+            this.#status.heartbeatAcks++;
+            this.#status.lastHeartbeatAt = new Date().toISOString();
+        })
+            .catch((error) => {
+            this.#fail(error.message);
+            throw error;
+        })
+            .finally(() => {
+            this.#ping = undefined;
+        });
+        return this.#ping;
+    }
+    replyStream(reqId, streamId, content, finish) {
+        if (!this.#status.connected || !reqId || !streamId)
+            return Promise.reject(new Error("WECOM_NOT_READY"));
+        if (Buffer.byteLength(content) > 20_480)
+            return Promise.reject(new Error("WECOM_REPLY_TOO_LARGE"));
+        return this.#request("aibot_respond_msg", { msgtype: "stream", stream: { id: streamId, content, finish } }, reqId);
+    }
+    #request(command, body, requestId) {
+        const socket = this.#socket;
+        if (this.#closed || socket?.readyState !== WebSocket.OPEN)
+            return Promise.reject(new Error("WECOM_NOT_READY"));
+        const reqId = requestId ?? `${command}_${randomUUID()}`;
+        if (this.#pending.has(reqId))
+            return Promise.reject(new Error("WECOM_REQUEST_PENDING"));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(reqId);
+                reject(new Error(command === "ping"
+                    ? "WECOM_HEARTBEAT_TIMEOUT"
+                    : command === "aibot_subscribe"
+                        ? "WECOM_AUTH_TIMEOUT"
+                        : "WECOM_REPLY_TIMEOUT"));
+            }, this.#requestTimeoutMs);
+            this.#pending.set(reqId, { command, resolve, reject, timer });
+            socket.send(JSON.stringify({ cmd: command, headers: { req_id: reqId }, ...(body ? { body } : {}) }), (error) => {
+                if (error)
+                    this.#fail("WECOM_SEND_FAILED");
+            });
+        });
+    }
+    #fail(code) {
+        const notify = !this.#closed;
+        if (!this.#closed)
+            this.#status.error ??= code;
+        void this.close();
+        if (notify)
+            this.callbacks.onDisconnect?.(this.#status.error ?? code);
+    }
+    close() {
+        if (this.#closing)
+            return this.#closing;
+        this.#closed = true;
+        this.#status.connected = false;
+        if (this.#heartbeat)
+            clearInterval(this.#heartbeat);
+        for (const pending of this.#pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(this.#status.error ?? "WECOM_CLOSED"));
+        }
+        this.#pending.clear();
+        const socket = this.#socket;
+        this.#closing =
+            !socket || socket.readyState === WebSocket.CLOSED
+                ? Promise.resolve()
+                : new Promise((resolve) => {
+                    socket.once("close", resolve);
+                    socket.terminate();
+                });
+        return this.#closing;
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-wecom/dist/transport/stream-session.d.ts

@@ -0,0 +1,10 @@
+import type { ImPresentation } from "../contracts.js";
+/** 企业微信 IM 呈现：空 think stream 触发客户端原生思考气泡，不是独立 typing API。 */
+export declare class WecomStreamSession {
+    #private;
+    readonly send: (streamId: string, text: string, finish: boolean) => Promise<void>;
+    constructor(send: (streamId: string, text: string, finish: boolean) => Promise<void>);
+    begin(onDiagnostic: (code: string) => void): ImPresentation;
+    reply(text: string, effectKey?: string): Promise<void>;
+    close(): Promise<void>;
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-wecom/dist/transport/stream-session.js

@@ -0,0 +1,52 @@
+/**
+ * 企业微信回复流：一次空 think 启动原生思考气泡，最终消息结束同一个 stream。
+ * 同一请求的发送必须逐个等待 ACK，避免并发覆盖或终态被迟到的思考帧覆盖。
+ */
+import { randomUUID } from "node:crypto";
+/** 企业微信 IM 呈现：空 think stream 触发客户端原生思考气泡，不是独立 typing API。 */
+export class WecomStreamSession {
+    send;
+    #streamId = `stream_${randomUUID()}`;
+    #tail = Promise.resolve();
+    #sealed = true;
+    #closed = false;
+    constructor(send) {
+        this.send = send;
+    }
+    begin(onDiagnostic) {
+        this.#streamId = `stream_${randomUUID()}`;
+        this.#sealed = false;
+        // 一次空 think 即可触发原生气泡；重复发送会与当前 stream 冲突。
+        void this.#send("<think></think>", false).catch(() => onDiagnostic("WECOM_TYPING_DELIVERY_FAILED"));
+        return {
+            update: () => undefined,
+            // 等待已发送思考帧的 ACK 后，再由最终回复结束气泡。
+            finish: async () => {
+                this.#sealed = true;
+                await this.#tail;
+            }
+        };
+    }
+    reply(text, effectKey) {
+        const finish = this.#sealed || effectKey?.startsWith("final:") === true;
+        if (finish)
+            this.#sealed = true;
+        return this.#send(text, finish);
+    }
+    #send(text, finish) {
+        const streamId = this.#streamId;
+        // 共享 req_id 的交互和最终回复都串行等 ACK，防止服务端匹配到错误请求。
+        const operation = this.#tail.then(() => {
+            if (this.#closed)
+                throw new Error("WECOM_STREAM_CLOSED");
+            return this.send(streamId, text, finish);
+        });
+        this.#tail = operation.catch(() => undefined);
+        return operation;
+    }
+    close() {
+        this.#closed = true;
+        this.#sealed = true;
+        return this.#tail;
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-wecom/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@mininglamp-oss/octo-runtime-extra-channel-wecom",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./config-schema.json": "./config-schema.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./daemon-module": {
+      "types": "./dist/daemon-module.d.ts",
+      "import": "./dist/daemon-module.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "config-schema.json",
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "dependencies": {
+    "@mininglamp-oss/octo-runtime-daemon": "1.0.0",
+    "@mininglamp-oss/octo-runtime-core": "1.0.0",
+    "@mininglamp-oss/octo-runtime-adapter-host": "1.0.0",
+    "ws": "8.21.3",
+    "@mininglamp-oss/octo-runtime-protocol": "1.0.0"
+  }
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-webui/config-schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:mininglamp-oss:octo-runtime:extra:webui:config",
+  "title": "本地 WebUI Extra 完整配置声明",
+  "description": "描述 module、enabled 和 config 的完整 JSON 声明，供接入方参考、生成类型或自行构造校验器。加载入口仍接收 JsonObject，不自动执行本 schema、不转换配置、不填充 default。default 记录插件现有的省略行为，不代表宿主必须采用该业务选择。",
+  "$comment": "声明文件最多 1 MiB，POSIX 权限须为 0600。端口占用、路径可访问性、会话文件内容及文件权限仍需运行时检查。加载生命周期 loaded 不等于监听成功，宿主须检查插件状态中的 listening 与 errors。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["module", "config"],
+  "properties": {
+    "module": {
+      "type": "string",
+      "const": "@mininglamp-oss/octo-runtime-extra-webui",
+      "description": "必填。本地 WebUI Extra 的固定包入口；宿主须预先安装并确保模块可解析。此 schema 约束包名声明，宿主通过绝对路径加载同一模块时可自行调整该约束。插件实例名及 CLI 配置目录名为 webui。"
+    },
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "可选。是否加载整个 WebUI 插件，省略视为 true；false 时加载器不导入插件、不启动 HTTP 监听。不会因此删除已保存会话、项目目录或 Runtime 身份。"
+    },
+    "config": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["sessionStorePath"],
+      "description": "必填。传给 WebUI Extra load 的原始 JSON 对象；来源由宿主决定。仅支持下列业务字段，未知配置字段当前忽略。监听地址固定为 127.0.0.1，不能通过增加 host 字段改为公网监听。",
+      "properties": {
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535,
+          "default": 13888,
+          "description": "可选。本机 HTTP 工作台端口，范围 1..65535，省略为 13888；固定监听 127.0.0.1。不能用 0 自动分配；端口被占用时插件状态报告 WEBUI_ADDRESS_IN_USE，schema 无法预先证明端口可用。"
+        },
+        "sessionStorePath": {
+          "type": "string",
+          "pattern": "^(?:/|[A-Za-z]:[\\\\/]|\\\\\\\\[^\\\\/]+[\\\\/][^\\\\/]+)",
+          "description": "必填。宿主指定的本机 WebUI 会话 JSON 文件绝对路径，不能写 ~ 或相对路径，也不会按 Runtime Home 自动推导。用于保存最多 100 条本 WebUI 会话及不透明 Provider binding，文件以 0600 原子写入，总大小上限 32 MiB。宿主应选择受保护且可写的位置；损坏文件不会被自动覆盖。不是模型工作目录或 Runtime 身份文件。",
+          "examples": ["/absolute/host-home/extras/webui/sessions.json"]
+        },
+        "defaultProjectPath": {
+          "type": "string",
+          "description": "可选。页面初始默认项目的本机目录；省略使用运行进程用户 Home 下的 octo-runtime-workspace，并在启动时创建目录。显式相对路径按进程 cwd 解析，建议使用绝对路径；~ 和环境变量不会展开。页面可另外选择项目，本字段不限制所有调用的工作区，也不是沙箱边界。",
+          "examples": ["/absolute/workspace"]
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schema", "items"],
+          "description": "可选。WebUI 发起每轮调用时使用的固定 Context v3；本轮显式同 namespace/name 项整项覆盖配置项。省略为空，不从历史补齐。建议新配置包含固定助理人设。",
+          "properties": {
+            "schema": {
+              "const": "octo.context-envelope/v3",
+              "description": "固定 Context 协议版本。"
+            },
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "object"
+              },
+              "description": "Context v3 的有序项；具体内部结构由 Context 协议校验。"
+            }
+          },
+          "examples": [
+            {
+              "schema": "octo.context-envelope/v3",
+              "items": [
+                {
+                  "namespace": "octo.control",
+                  "name": "instructions",
+                  "payload": {
+                    "entries": [
+                      {
+                        "text": "我是明略科技的Octo助理"
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "module": "@mininglamp-oss/octo-runtime-extra-webui",
+      "enabled": true,
+      "config": {
+        "port": 13888,
+        "sessionStorePath": "/absolute/host-home/extras/webui/sessions.json",
+        "defaultProjectPath": "/absolute/workspace",
+        "context": {
+          "schema": "octo.context-envelope/v3",
+          "items": [
+            {
+              "namespace": "octo.control",
+              "name": "instructions",
+              "payload": {
+                "entries": [
+                  {
+                    "text": "我是明略科技的Octo助理"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "module": "@mininglamp-oss/octo-runtime-extra-webui",
+      "config": {
+        "sessionStorePath": "/absolute/host-home/extras/webui/sessions.json",
+        "context": {
+          "schema": "octo.context-envelope/v3",
+          "items": [
+            {
+              "namespace": "octo.control",
+              "name": "instructions",
+              "payload": {
+                "entries": [
+                  {
+                    "text": "我是明略科技的Octo助理"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-webui/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { ExtraInitializer, ExtraContext, JsonObject } from "@mininglamp-oss/octo-runtime-daemon";
+export declare const name = "webui";
+export default function load(ctx: ExtraContext, config: JsonObject): ExtraInitializer;