@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.1

package/dist/net/WsHub.js

@@ -0,0 +1,689 @@
+/**
+ * `WsHub` —— 一条 WebSocket 上的接线层（architecture A2 / §6）。
+ *
+ * 它只做四件事，一件也不多做：
+ *
+ *   1. **握手**：首帧必须是 `hello`（`{ token, language?, clientInfo }`）。没通过之前除了 `hello`
+ *      什么都不接（一律 `unauthorized`），凭证不放在 URL 查询串里。`language` 挂在这条连接上、
+ *      断开即忘（PRD D8）。
+ *   2. **分发**：`MethodMap` 里的方法交给注入的 handler 表；没注册的方法回 `unsupported`
+ *      （接线层自己代管的只有 `host.hello` / `host.setLanguage` 与上传三段）。
+ *      业务逻辑一律不在本文件里。
+ *   3. **推送**：JSON-RPC 通知（无 id），`params` 就是事件载荷。不重放、不需要 ack（PRD L5：
+ *      断线重连由客户端自己拉）。受理即返回的方法（`conversation.send` 这类）会产生「事件早于回包」
+ *      的顺序问题，所以按 `conversationId` 缓冲，回包写完再按序放行（裁定 R47）。
+ *   4. **上传帧**：二进制帧交给 `UploadReceiver` 落盘；连接断开时把它名下未完成的上传清掉。
+ *
+ * 错误一律走 JSON-RPC `error`：`data.code` 是稳定业务码、`data.message` 是按**这条连接的语言**
+ * 渲染好的句子、`data.detail` 是结构化事实。非 `HostError` 的抛出收敛成 `internal` ——
+ * 细节只进日志，栈与内部路径不出网。
+ */
+import { randomUUID } from "node:crypto";
+import { WebSocket, WebSocketServer } from "ws";
+import { normalizeLanguage } from "../i18n/index.js";
+import { MAX_ASSETS_PER_MESSAGE, MAX_ASSET_BYTES, PROTOCOL_VERSION, HostError, errResponse, isMethodName, notification, okResponse, parseFrame, } from "../wire/index.js";
+import { decodeChunkFrame } from "./UploadReceiver.js";
+/** 安静日志（缺省值，不导出：不让它变成别处共享的全局） */
+const QUIET_LOGGER = {
+    warn: () => undefined,
+    error: () => undefined,
+};
+/** `hello` 之前唯一允许的方法 */
+const HELLO_METHOD = "host.hello";
+export class WsHub {
+    options;
+    logger;
+    clock;
+    startedAt;
+    /** 缺省语言来源（可能是函数：配置里的那一项可改，每次握手现算） */
+    defaultLanguageSource;
+    /** connectionId → 连接状态（关闭即移除；推送只发给还在这里面的连接） */
+    connections = new Map();
+    server = null;
+    closing = null;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? QUIET_LOGGER;
+        this.clock = options.clock ?? Date.now;
+        this.startedAt = options.startedAt ?? new Date(this.clock()).toISOString();
+        this.defaultLanguageSource = options.defaultLanguage ?? "en";
+    }
+    // -------------------------------------------------------------------------
+    // 启停
+    // -------------------------------------------------------------------------
+    /**
+     * 开始监听。
+     *
+     * 返回**实际**监听地址：端口给 `0` 时由系统分配，回调里拿到的才是真端口 ——
+     * 调用方要把它写进发现文件（客户端读的是那里，不是启动参数）。
+     */
+    async listen() {
+        if (this.server)
+            throw new Error("WsHub 已经在监听");
+        const server = new WebSocketServer({ host: this.options.host, port: this.options.port });
+        server.on("connection", (socket) => this.accept(socket));
+        await new Promise((resolve, reject) => {
+            const onError = (error) => {
+                server.off("listening", onListening);
+                reject(error);
+            };
+            const onListening = () => {
+                server.off("error", onError);
+                resolve();
+            };
+            server.once("error", onError);
+            server.once("listening", onListening);
+        });
+        // 监听成功之后的错误（某个连接上的异常等）记日志，不让它变成未捕获异常
+        server.on("error", (error) => this.logger.error("WebSocket 服务器出错", { error }));
+        this.server = server;
+        const address = server.address();
+        if (typeof address === "string" || address === null) {
+            return { host: this.options.host, port: this.options.port };
+        }
+        const info = address;
+        return { host: info.address, port: info.port };
+    }
+    /** 实际监听地址；没在监听时为 `null` */
+    address() {
+        const address = this.server?.address();
+        if (!address || typeof address === "string")
+            return null;
+        return { host: address.address, port: address.port };
+    }
+    /**
+     * 收尾：先给每条连接一个正常的关闭帧，再关服务器；有连接迟迟不断就强制断开。
+     *
+     * 收尾之后不再接受新连接，也不再持有任何连接状态与上传状态。
+     */
+    close() {
+        this.closing ??= this.doClose();
+        return this.closing;
+    }
+    async doClose() {
+        const server = this.server;
+        this.server = null;
+        const states = [...this.connections.values()];
+        for (const state of states) {
+            try {
+                state.socket.close(1001, "host shutting down");
+            }
+            catch {
+                // 已经断了：下面统一按「连接没了」处理
+            }
+            await this.options.uploads?.abortConnection(state.id).catch((error) => {
+                this.logger.warn("清理上传失败", { error });
+            });
+            state.holds.clear();
+            this.connections.delete(state.id);
+        }
+        this.notifyConnectionsChanged();
+        if (!server)
+            return;
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                // 兜底：还在半开状态的连接直接断掉，避免关宿主时挂在这里
+                for (const client of server.clients)
+                    client.terminate();
+            }, 200);
+            server.close(() => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    // -------------------------------------------------------------------------
+    // 推送（宿主 → 客户端）
+    // -------------------------------------------------------------------------
+    /**
+     * 推一个事件给所有已握手的连接。
+     *
+     * 形状与 `ChatRunner` 的 `ChatEventEmitter` 一致，所以单根可以把它直接当 `emit` 注入。
+     * 事件里带 `conversationId` 的（全部事件都带）会受该对话的缓冲控制：有请求还没回包时先排队。
+     */
+    push(event, payload) {
+        const key = conversationKeyOf(event, payload);
+        for (const state of this.connections.values()) {
+            this.deliver(state, key, () => this.frameFor(state, event, payload));
+        }
+    }
+    /** 推一个事件给指定连接；连接不在（已断开）时返回 `false` */
+    pushTo(connectionId, event, payload) {
+        const state = this.connections.get(connectionId);
+        if (!state)
+            return false;
+        this.deliver(state, conversationKeyOf(event, payload), () => this.frameFor(state, event, payload));
+        return true;
+    }
+    /**
+     * 把事件载荷变成这条连接要收的通知帧。
+     *
+     * 注入了 `localizeEvent` 时先过一道：事件里的 `LocalizedText` 是在产生现场渲染的（那时不知道
+     * 收件人是谁），而语言挂在连接上（D8），所以真正的「按这条连接的语言说这句话」发生在这里。
+     * 没注入时原样搬运（测试与不关心多语言的场合）。
+     */
+    frameFor(state, event, payload) {
+        const localize = this.options.localizeEvent;
+        const body = localize ? localize(event, payload, state.language) : payload;
+        return notification(event, body);
+    }
+    /** 当前在线的连接（只给事实，不给 socket） */
+    connectionInfos() {
+        return [...this.connections.values()].map((state) => toConnectionInfo(state));
+    }
+    /** 报一次连接数变化；回调自己抛错不影响连接本身 */
+    notifyConnectionsChanged() {
+        const listener = this.options.onConnectionsChanged;
+        if (!listener)
+            return;
+        try {
+            listener(this.connections.size);
+        }
+        catch (error) {
+            this.logger.warn("连接数变化回调抛错", { error: describeError(error) });
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 连接
+    // -------------------------------------------------------------------------
+    accept(socket) {
+        const state = {
+            id: randomUUID(),
+            socket,
+            // 握完手就换成协商出的那一份；这里是它之前的样子（同步可得的那个值）
+            language: this.initialLanguage(),
+            clientInfo: null,
+            credentialId: null,
+            authorized: false,
+            holds: new Map(),
+        };
+        this.connections.set(state.id, state);
+        this.notifyConnectionsChanged();
+        socket.on("message", (data, isBinary) => {
+            void this.onFrame(state, data, isBinary).catch((error) => {
+                // 兜底：任何没被分支捕获的抛出都只能进日志（连接已经没法给出更具体的回答）
+                this.logger.error("处理帧时出现未捕获的错误", { error: describeError(error) });
+            });
+        });
+        socket.on("close", () => this.drop(state));
+        socket.on("error", (error) => {
+            this.logger.warn("连接出错", { connectionId: state.id, error });
+        });
+    }
+    /** 连接断开：把它的上传与缓冲一起扔掉（订阅就是「它在不在这个集合里」） */
+    drop(state) {
+        if (!this.connections.delete(state.id))
+            return;
+        state.holds.clear();
+        this.notifyConnectionsChanged();
+        void this.options.uploads?.abortConnection(state.id).catch((error) => {
+            this.logger.warn("断线清理上传失败", { connectionId: state.id, error });
+        });
+    }
+    // -------------------------------------------------------------------------
+    // 入站帧
+    // -------------------------------------------------------------------------
+    async onFrame(state, data, isBinary) {
+        if (isBinary) {
+            await this.onBinary(state, toBytes(data));
+            return;
+        }
+        let frame;
+        try {
+            frame = parseFrame(toText(data));
+        }
+        catch (error) {
+            this.send(state, this.errorFrame(extractId(toText(data)), error, state.language));
+            return;
+        }
+        if (frame.kind === "request") {
+            await this.onRequest(state, frame.id, frame.method, frame.params);
+            return;
+        }
+        if (frame.kind === "notification") {
+            await this.onNotification(state, frame.method, frame.params);
+            return;
+        }
+        // 客户端发来的响应：我们的协议里没有「宿主向客户端请求」这回事
+        this.send(state, this.errorFrame(null, new HostError("invalid_params", {
+            detail: { reason: "unexpected_response", got: frame.kind },
+        }), state.language));
+    }
+    /** 二进制帧：只可能是上传分片 */
+    async onBinary(state, bytes) {
+        const uploads = this.options.uploads;
+        if (!uploads) {
+            this.send(state, this.errorFrame(null, new HostError("unsupported", {
+                params: { what: "binary uploads" },
+                detail: { reason: "uploads_not_enabled" },
+            }), state.language));
+            return;
+        }
+        if (!state.authorized) {
+            this.send(state, this.errorFrame(null, new HostError("unauthorized", { detail: { reason: "hello_required" } }), state.language));
+            return;
+        }
+        try {
+            await uploads.receiveBinary(state.id, bytes);
+        }
+        catch (error) {
+            this.send(state, this.chunkErrorFrame(error, bytes, state.language));
+        }
+    }
+    /**
+     * 分片帧的错误帧。
+     *
+     * 二进制帧没有 `id`，所以「哪一趟上传被拒了」只能靠 `detail.uploadId` 认出来：这里尽力从帧头
+     * 取一次 `uploadId` 补进 `detail`（原有的结构化事实不动，已经有 `uploadId` 就不覆盖）。
+     * 业务错误原样出网；非业务错误按 `internal` 出网、细节只进日志。帧头坏到解不出 `uploadId` 时
+     * 与原来一样，什么也不补。
+     */
+    chunkErrorFrame(error, frame, language) {
+        const uploadId = uploadIdOf(frame);
+        if (uploadId === null)
+            return this.errorFrame(null, error, language);
+        if (HostError.is(error)) {
+            return errResponse(null, withUploadId(error, uploadId), language);
+        }
+        this.logger.error("处理上传分片时出现非业务错误", { uploadId, error: describeError(error) });
+        return errResponse(null, new HostError("internal", { detail: { reason: "chunk_failed", uploadId } }), language);
+    }
+    /**
+     * 请求帧：先按对话挂起推送，再分发，最后写回包，回包写完按序放行该对话的推送（R47）。
+     *
+     * 「先挂起再分发」是关键：事件可能在分发的第一行就产生（受理即返回的方法正是这样），
+     * 挂起晚一步就会出现「客户端还没拿到 id 就收到事件」。
+     */
+    async onRequest(state, id, method, params) {
+        const holdKey = conversationKeyOfParams(params);
+        if (holdKey !== null)
+            this.hold(state, holdKey);
+        let response;
+        try {
+            const result = await this.invoke(state, method, params);
+            response = okResponse(id, result);
+        }
+        catch (error) {
+            response = this.errorFrame(id, error, state.language);
+        }
+        this.send(state, response);
+        // 回包已经交给 socket（ws 按调用顺序写出），这时候放行不会插到回包前面
+        if (holdKey !== null)
+            this.release(state, holdKey);
+    }
+    /** 通知帧（客户端发来的、不需要回包）：照常执行，出错时用 `id: null` 报一次 */
+    async onNotification(state, method, params) {
+        const holdKey = conversationKeyOfParams(params);
+        if (holdKey !== null)
+            this.hold(state, holdKey);
+        try {
+            await this.invoke(state, method, params);
+        }
+        catch (error) {
+            this.send(state, this.errorFrame(null, error, state.language));
+        }
+        if (holdKey !== null)
+            this.release(state, holdKey);
+    }
+    // -------------------------------------------------------------------------
+    // 分发
+    // -------------------------------------------------------------------------
+    /**
+     * 方法名 → 结果。
+     *
+     * 顺序是有意的：`hello` 永远放行（握手本身不需要先握手）；其余方法在未握手时一律
+     * `unauthorized`（连方法名都不判断，免得「未授权的连接能探出宿主有哪些方法」）。
+     */
+    async invoke(state, method, params) {
+        if (method === HELLO_METHOD)
+            return await this.handleHello(state, params);
+        if (!state.authorized) {
+            throw new HostError("unauthorized", { detail: { reason: "hello_required" } });
+        }
+        if (!isMethodName(method)) {
+            throw new HostError("unsupported", {
+                params: { what: method },
+                detail: { method, reason: "unknown_method" },
+            });
+        }
+        // 语言是连接状态，接线层自己管（业务层不该知道「这条连接说哪种语言」之外的任何事）
+        if (method === "host.setLanguage")
+            return this.handleSetLanguage(state, params);
+        if (this.options.uploads) {
+            if (method === "asset.begin") {
+                // 语言是连接状态：草稿对话落库时要靠它渲染那条隐藏的 cwd 消息（D8）
+                return await this.options.uploads.begin(state.id, params, state.language);
+            }
+            if (method === "asset.end") {
+                return await this.options.uploads.end(state.id, params);
+            }
+        }
+        const handler = this.options.handlers[method];
+        if (typeof handler !== "function") {
+            throw new HostError("unsupported", {
+                params: { what: method },
+                detail: { method, reason: "handler_not_registered" },
+            });
+        }
+        const call = handler;
+        return await call({ method, params, connection: toConnectionInfo(state) });
+    }
+    /**
+     * 握手。
+     *
+     * `language` 认不出来时回落英文（PRD D8）；不传就用配置的默认语言。
+     * 失败不改变这条连接已经有的授权状态（重复握手是客户端自己的选择，失败不该把现有连接打回未授权）。
+     */
+    async handleHello(state, params) {
+        const hello = asHelloParams(params);
+        const verified = await this.options.verifyToken.verify(hello.token);
+        if (verified === null) {
+            throw new HostError("unauthorized", { detail: { reason: "token_rejected" } });
+        }
+        state.authorized = true;
+        state.credentialId = verified.id;
+        state.clientInfo = hello.clientInfo;
+        state.language =
+            typeof hello.language === "string" && hello.language.trim() !== ""
+                ? normalizeLanguage(hello.language)
+                : await this.resolveDefaultLanguage();
+        return {
+            language: state.language,
+            hostVersion: this.options.hostVersion,
+            protocolVersion: PROTOCOL_VERSION,
+            startedAt: this.startedAt,
+            // 握手只给能力 id 列表（R57）：清单本身按这条连接的语言渲染，但 id 与顺序固定
+            capabilities: (this.options.capabilities?.(state.language) ?? []).map((capability) => capability.id),
+            limits: this.transferLimits(),
+        };
+    }
+    /**
+     * 连接没声明语言时用哪一种（PRD D8 / 裁定 R58）。
+     *
+     * 来源可以是函数（配置里的缺省语言可改），所以每次握手现算一次；算不出来就用英文 ——
+     * 语言这件事不该让握手失败。
+     */
+    async resolveDefaultLanguage() {
+        const source = this.defaultLanguageSource;
+        if (typeof source === "string")
+            return source;
+        try {
+            return normalizeLanguage(await source());
+        }
+        catch (error) {
+            this.logger.warn("读缺省语言失败，回落到英文", { error: describeError(error) });
+            return "en";
+        }
+    }
+    /** 握手之前的语言：来源不是函数时就是它，是函数时先用英文（拿不到同步值） */
+    initialLanguage() {
+        const source = this.defaultLanguageSource;
+        return typeof source === "string" ? source : "en";
+    }
+    /** `host.setLanguage`：改这条连接的语言，断开即忘（PRD D8 / F-E4） */
+    handleSetLanguage(state, params) {
+        const record = asRecord(params, "params");
+        const language = record.language;
+        if (typeof language !== "string" || language.trim() === "") {
+            throw new HostError("invalid_params", {
+                params: { field: "language" },
+                detail: { field: "language", reason: "missing_language" },
+            });
+        }
+        state.language = normalizeLanguage(language);
+        return { language: state.language };
+    }
+    transferLimits() {
+        return {
+            maxAssetBytes: this.options.uploads?.maxAssetBytes ?? MAX_ASSET_BYTES,
+            maxAssetsPerMessage: MAX_ASSETS_PER_MESSAGE,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // 推送缓冲（R47）
+    // -------------------------------------------------------------------------
+    hold(state, key) {
+        const existing = state.holds.get(key);
+        if (existing) {
+            existing.depth += 1;
+            return;
+        }
+        state.holds.set(key, { depth: 1, queue: [] });
+    }
+    /**
+     * 放行一段对话的推送。
+     *
+     * 只有最后一层请求回包之后才真的放（同一对话同时有两个请求在飞时，先回包的那一个不该把
+     * 后一个还没回包时产生的事件抢在前面发出去）。
+     */
+    release(state, key) {
+        const hold = state.holds.get(key);
+        if (!hold)
+            return;
+        hold.depth -= 1;
+        if (hold.depth > 0)
+            return;
+        state.holds.delete(key);
+        for (const makeFrame of hold.queue)
+            this.send(state, makeFrame());
+    }
+    /** 发一帧：按对话的缓冲、连接状态一起看，该排队就排队 */
+    deliver(state, conversationId, makeFrame) {
+        if (!state.authorized)
+            return;
+        if (conversationId !== null) {
+            const hold = state.holds.get(conversationId);
+            if (hold) {
+                // 排队的是一段「怎么造这一帧」的意图，不是某个已经渲染好的帧：放行时用那时的语言重算
+                hold.queue.push(makeFrame);
+                return;
+            }
+        }
+        this.send(state, makeFrame());
+    }
+    send(state, frame) {
+        if (state.socket.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            state.socket.send(JSON.stringify(frame));
+        }
+        catch (error) {
+            this.logger.warn("发送帧失败", { connectionId: state.id, error });
+        }
+    }
+    /**
+     * 抛出的东西 → 错误帧。
+     *
+     * `HostError` 原样出网（业务码 + 按连接语言渲染的句子 + detail）；其余一律收敛成 `internal`，
+     * 细节（含栈）只进日志 —— 客户端看到的是「宿主出错了，日志里有细节」。
+     */
+    errorFrame(id, error, language) {
+        if (HostError.is(error))
+            return errResponse(id, error, language);
+        this.logger.error("处理请求时抛出非业务错误", { error: describeError(error) });
+        return errResponse(id, new HostError("internal"), language);
+    }
+}
+// ---------------------------------------------------------------------------
+// 纯函数
+// ---------------------------------------------------------------------------
+function toConnectionInfo(state) {
+    return {
+        id: state.id,
+        language: state.language,
+        clientInfo: state.clientInfo,
+        credentialId: state.credentialId,
+    };
+}
+function describeError(error) {
+    if (error instanceof Error)
+        return { message: error.message, stack: error.stack };
+    return { message: String(error) };
+}
+/**
+ * 从一帧分片里尽力取出 `uploadId`（解不出就是 `null`：帧已经坏到没有头可读）。
+ */
+function uploadIdOf(frame) {
+    try {
+        return decodeChunkFrame(frame).uploadId;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 把 `uploadId` 补进错误的 `detail`（原有的事实保留，已有的 `uploadId` 不覆盖）。
+ *
+ * `detail` 不是对象时把它挪到 `detail.detail` 下而不是丢掉：错误帧里带出去的结构化事实
+ * 都走 `detail`，一个非对象的值不能成为「既然不好合并就扔掉」的理由。
+ */
+function withUploadId(error, uploadId) {
+    const detail = error.detail;
+    if (detail === undefined)
+        return error.withDetail({ uploadId });
+    if (typeof detail === "object" && detail !== null && !Array.isArray(detail)) {
+        const record = detail;
+        if (record.uploadId !== undefined)
+            return error;
+        return error.withDetail({ ...record, uploadId });
+    }
+    return error.withDetail({ detail, uploadId });
+}
+/** 入站字节：`ws` 可能给 Buffer、ArrayBuffer 或 Buffer 数组（分片） */
+function toBytes(data) {
+    if (Array.isArray(data))
+        return new Uint8Array(Buffer.concat(data));
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+/** 入站文本：同样要能吃分片 */
+function toText(data) {
+    if (Array.isArray(data))
+        return Buffer.concat(data).toString("utf8");
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data).toString("utf8");
+    return data.toString("utf8");
+}
+/**
+ * 从一段坏帧里尽量捞出 `id`，好让错误响应能对上是哪个请求。
+ *
+ * 两步：能整段解析就取 `id`；解析不了（半截 JSON、多了个逗号）再用一次文本扫描 ——
+ * 这是尽力而为：扫不到就回 `null`，错误帧允许 `id` 为 `null`（标准里就是「连 id 都没解析出来」）。
+ * 扫描可能误命中嵌套对象里的 `id`，所以它只作为整段解析失败后的退路。
+ */
+function extractId(text) {
+    try {
+        const value = JSON.parse(text);
+        if (typeof value === "object" && value !== null) {
+            return asId(value.id);
+        }
+    }
+    catch {
+        // 坏到解析不了：往下走文本扫描
+    }
+    const matched = /"id"\s*:\s*("(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?)/.exec(text);
+    const raw = matched?.[1];
+    if (raw === undefined)
+        return null;
+    if (raw.startsWith("\"")) {
+        try {
+            return asId(JSON.parse(raw));
+        }
+        catch {
+            return null;
+        }
+    }
+    return asId(Number(raw));
+}
+function asId(value) {
+    if (typeof value === "string" && value !== "")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    return null;
+}
+/** 请求参数里的 `conversationId`：有就按它缓冲该对话的推送（R47） */
+function conversationKeyOfParams(params) {
+    if (typeof params !== "object" || params === null || Array.isArray(params))
+        return null;
+    const value = params.conversationId;
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+/**
+ * 事件载荷里的对话 id。
+ *
+ * 六种事件都挂着某段对话（通知与问题的 `conversationId` 可能是 `null`：那是全局的，
+ * 不受任何对话的缓冲影响）。这一处让 `push` 的调用方不必自己传 key。
+ */
+function conversationKeyOf(event, payload) {
+    switch (event) {
+        case "run.state":
+        case "message.delta":
+        case "conversation.changed":
+        case "usage":
+            return nonEmpty(payload.conversationId);
+        case "notice":
+            return nonEmpty(payload.notice.conversationId);
+        case "question":
+            return nonEmpty(payload.question.conversationId);
+        default:
+            return null;
+    }
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+function asRecord(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new HostError("invalid_params", {
+            params: { field },
+            detail: { field, reason: "not_an_object" },
+        });
+    }
+    return value;
+}
+/**
+ * `hello` 入参的校验。
+ *
+ * 只校验「少了就完全没法握手」的三样：`token`、`clientInfo`（客户端自报身份，用于连接列表与日志）、
+ * 以及可选的 `language`（不是字符串就当没给）。
+ */
+function asHelloParams(value) {
+    const record = asRecord(value, "params");
+    const token = record.token;
+    if (typeof token !== "string" || token.trim() === "") {
+        throw new HostError("invalid_params", {
+            params: { field: "token" },
+            detail: { field: "token", reason: "missing_token" },
+        });
+    }
+    return {
+        token: token.trim(),
+        language: typeof record.language === "string" ? record.language : undefined,
+        clientInfo: asClientInfo(record.clientInfo),
+    };
+}
+function asClientInfo(value) {
+    const record = asRecord(value, "clientInfo");
+    const name = record.name;
+    const version = record.version;
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new HostError("invalid_params", {
+            params: { field: "clientInfo.name" },
+            detail: { field: "clientInfo.name", reason: "missing_name" },
+        });
+    }
+    if (typeof version !== "string" || version.trim() === "") {
+        throw new HostError("invalid_params", {
+            params: { field: "clientInfo.version" },
+            detail: { field: "clientInfo.version", reason: "missing_version" },
+        });
+    }
+    const platform = record.platform;
+    return {
+        name: name.trim(),
+        version: version.trim(),
+        platform: typeof platform === "string" && platform.trim() !== "" ? platform.trim() : undefined,
+    };
+}