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

package/dist/net/WsHub.d.ts

@@ -0,0 +1,231 @@
+/**
+ * `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 type { ListenTarget } from "../config.js";
+import { type Language } from "../i18n/index.js";
+import { type CapabilityView, type ClientInfo, type EventMap, type EventName, type MethodName, type MethodParams, type MethodResult } from "../wire/index.js";
+import type { TokenVerifier } from "./auth.js";
+import { type UploadReceiver } from "./UploadReceiver.js";
+/** 一条连接对 handler 可见的事实（不把 socket 漏给业务层） */
+export interface ConnectionInfo {
+    /** 宿主分配的连接 id（问题对象的 `answeredBy` 这类「哪条连接」的事实用它） */
+    id: string;
+    /** 这条连接协商出的语言 */
+    language: Language;
+    /** 客户端自报的身份（`hello` 之后才有值） */
+    clientInfo: ClientInfo | null;
+    /** 这条连接用的是哪一串凭证（`hello` 之后才有值） */
+    credentialId: string | null;
+}
+/** 一个方法的调用现场 */
+export interface MethodCallContext<M extends MethodName> {
+    method: M;
+    /** 入参：以契约为准（`MethodMap[M]["params"]`），业务层自己按字段取值校验 */
+    params: MethodParams<M>;
+    connection: ConnectionInfo;
+}
+/**
+ * 方法实现。
+ *
+ * 抛 `HostError` 表达「可以给用户看的原因」，抛别的会被收敛成 `internal` 并进日志。
+ */
+export type MethodHandler<M extends MethodName> = (context: MethodCallContext<M>) => MethodResult<M> | Promise<MethodResult<M>>;
+/**
+ * handler 表：注册哪些方法就有哪些方法，其余一律 `unsupported`。
+ *
+ * 用 `Partial` + 映射类型，是为了让「注册时的入参/出参类型」跟着方法名走 ——
+ * 写错一个字段名在编译期就露出来，而不是等客户端连上来才发现。
+ */
+export type HandlerTable = {
+    [M in MethodName]?: MethodHandler<M>;
+};
+/** 日志口子：连接事件与内部错误往哪写 */
+export interface HubLogger {
+    warn(message: string, detail?: unknown): void;
+    error(message: string, detail?: unknown): void;
+}
+/**
+ * 推送的按连接本地化（PRD D8）：事件里的 `LocalizedText` 在产生现场渲染，而语言挂在连接上，
+ * 所以出网前最后一道是「按这条连接的语言把句子换掉」。注入方（W4 的通知/问题层）重渲染
+ * `message` 字段后原样返回；不改载荷时直接返回 `payload`。
+ */
+export type EventLocalizer = <E extends EventName>(event: E, payload: EventMap[E], language: Language) => EventMap[E];
+/**
+ * 连接未声明语言时的缺省语言来源。
+ *
+ * 给函数时在每次握手那一刻求值：缺省语言是「配置里的那一项」（PRD D8 / R58），而配置可以在
+ * 进程跑着的时候改，存成构造时的快照会让「刚改的缺省语言」对下一条连接不生效。
+ */
+export type DefaultLanguageSource = Language | (() => Language | Promise<Language>);
+export interface WsHubOptions {
+    /** 监听地址（由调用方按 `resolveListenTarget` 算好传进来，本文件不判断本地/对外） */
+    host: string;
+    /** 监听端口；`0` 表示由系统分配（用例与「端口被占时退回临时端口」都靠它） */
+    port: number;
+    /** 凭证校验（`auth.createTokenVerifier`；用例注入假实现） */
+    verifyToken: TokenVerifier;
+    /** 方法表 */
+    handlers: HandlerTable;
+    /** 上传接收器；不给时 `asset.begin` / `asset.end` 与二进制帧都按 `unsupported` 处理 */
+    uploads?: UploadReceiver;
+    /** 宿主版本（`hello` 的 `hostVersion`，升级判定要向客户端报这个） */
+    hostVersion: string;
+    /** 进程启动时刻（ISO 8601）；缺省取构造时的时钟 */
+    startedAt?: string;
+    /**
+     * 能力清单（PRD F-E5：帮助页与指令菜单从这一份渲染）；缺省为空。
+     *
+     * 入参是这条连接的语言（裁定 R58）：句子按收件人的语言给，id 列表与顺序不变（R57）。
+     */
+    capabilities?: (language: Language) => CapabilityView[];
+    /** 连接未声明语言时的缺省语言（PRD D8：缺省英文）；给函数时每次握手现算 */
+    defaultLanguage?: DefaultLanguageSource;
+    /** 推送出网前的按连接本地化（不注入则原样搬运） */
+    localizeEvent?: EventLocalizer;
+    /**
+     * 连接数变化时回调（参数是这一刻的连接数）。
+     *
+     * 单根靠它发现「最后一条连接走了」：那正是退出判据的一个触发源（PRD L4 / A10：
+     * 回收计时只有一处，所以这里只报事实、不自带定时器）。
+     */
+    onConnectionsChanged?: (count: number) => void;
+    /** 时钟，缺省 `Date.now` */
+    clock?: () => number;
+    /** 日志；缺省安静 */
+    logger?: HubLogger;
+}
+export declare class WsHub {
+    private readonly options;
+    private readonly logger;
+    private readonly clock;
+    private readonly startedAt;
+    /** 缺省语言来源（可能是函数：配置里的那一项可改，每次握手现算） */
+    private readonly defaultLanguageSource;
+    /** connectionId → 连接状态（关闭即移除；推送只发给还在这里面的连接） */
+    private readonly connections;
+    private server;
+    private closing;
+    constructor(options: WsHubOptions);
+    /**
+     * 开始监听。
+     *
+     * 返回**实际**监听地址：端口给 `0` 时由系统分配，回调里拿到的才是真端口 ——
+     * 调用方要把它写进发现文件（客户端读的是那里，不是启动参数）。
+     */
+    listen(): Promise<ListenTarget>;
+    /** 实际监听地址；没在监听时为 `null` */
+    address(): ListenTarget | null;
+    /**
+     * 收尾：先给每条连接一个正常的关闭帧，再关服务器；有连接迟迟不断就强制断开。
+     *
+     * 收尾之后不再接受新连接，也不再持有任何连接状态与上传状态。
+     */
+    close(): Promise<void>;
+    private doClose;
+    /**
+     * 推一个事件给所有已握手的连接。
+     *
+     * 形状与 `ChatRunner` 的 `ChatEventEmitter` 一致，所以单根可以把它直接当 `emit` 注入。
+     * 事件里带 `conversationId` 的（全部事件都带）会受该对话的缓冲控制：有请求还没回包时先排队。
+     */
+    push<E extends EventName>(event: E, payload: EventMap[E]): void;
+    /** 推一个事件给指定连接；连接不在（已断开）时返回 `false` */
+    pushTo<E extends EventName>(connectionId: string, event: E, payload: EventMap[E]): boolean;
+    /**
+     * 把事件载荷变成这条连接要收的通知帧。
+     *
+     * 注入了 `localizeEvent` 时先过一道：事件里的 `LocalizedText` 是在产生现场渲染的（那时不知道
+     * 收件人是谁），而语言挂在连接上（D8），所以真正的「按这条连接的语言说这句话」发生在这里。
+     * 没注入时原样搬运（测试与不关心多语言的场合）。
+     */
+    private frameFor;
+    /** 当前在线的连接（只给事实，不给 socket） */
+    connectionInfos(): ConnectionInfo[];
+    /** 报一次连接数变化；回调自己抛错不影响连接本身 */
+    private notifyConnectionsChanged;
+    private accept;
+    /** 连接断开：把它的上传与缓冲一起扔掉（订阅就是「它在不在这个集合里」） */
+    private drop;
+    private onFrame;
+    /** 二进制帧：只可能是上传分片 */
+    private onBinary;
+    /**
+     * 分片帧的错误帧。
+     *
+     * 二进制帧没有 `id`，所以「哪一趟上传被拒了」只能靠 `detail.uploadId` 认出来：这里尽力从帧头
+     * 取一次 `uploadId` 补进 `detail`（原有的结构化事实不动，已经有 `uploadId` 就不覆盖）。
+     * 业务错误原样出网；非业务错误按 `internal` 出网、细节只进日志。帧头坏到解不出 `uploadId` 时
+     * 与原来一样，什么也不补。
+     */
+    private chunkErrorFrame;
+    /**
+     * 请求帧：先按对话挂起推送，再分发，最后写回包，回包写完按序放行该对话的推送（R47）。
+     *
+     * 「先挂起再分发」是关键：事件可能在分发的第一行就产生（受理即返回的方法正是这样），
+     * 挂起晚一步就会出现「客户端还没拿到 id 就收到事件」。
+     */
+    private onRequest;
+    /** 通知帧（客户端发来的、不需要回包）：照常执行，出错时用 `id: null` 报一次 */
+    private onNotification;
+    /**
+     * 方法名 → 结果。
+     *
+     * 顺序是有意的：`hello` 永远放行（握手本身不需要先握手）；其余方法在未握手时一律
+     * `unauthorized`（连方法名都不判断，免得「未授权的连接能探出宿主有哪些方法」）。
+     */
+    private invoke;
+    /**
+     * 握手。
+     *
+     * `language` 认不出来时回落英文（PRD D8）；不传就用配置的默认语言。
+     * 失败不改变这条连接已经有的授权状态（重复握手是客户端自己的选择，失败不该把现有连接打回未授权）。
+     */
+    private handleHello;
+    /**
+     * 连接没声明语言时用哪一种（PRD D8 / 裁定 R58）。
+     *
+     * 来源可以是函数（配置里的缺省语言可改），所以每次握手现算一次；算不出来就用英文 ——
+     * 语言这件事不该让握手失败。
+     */
+    private resolveDefaultLanguage;
+    /** 握手之前的语言：来源不是函数时就是它，是函数时先用英文（拿不到同步值） */
+    private initialLanguage;
+    /** `host.setLanguage`：改这条连接的语言，断开即忘（PRD D8 / F-E4） */
+    private handleSetLanguage;
+    private transferLimits;
+    private hold;
+    /**
+     * 放行一段对话的推送。
+     *
+     * 只有最后一层请求回包之后才真的放（同一对话同时有两个请求在飞时，先回包的那一个不该把
+     * 后一个还没回包时产生的事件抢在前面发出去）。
+     */
+    private release;
+    /** 发一帧：按对话的缓冲、连接状态一起看，该排队就排队 */
+    private deliver;
+    private send;
+    /**
+     * 抛出的东西 → 错误帧。
+     *
+     * `HostError` 原样出网（业务码 + 按连接语言渲染的句子 + detail）；其余一律收敛成 `internal`，
+     * 细节（含栈）只进日志 —— 客户端看到的是「宿主出错了，日志里有细节」。
+     */
+    private errorFrame;
+}