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

package/dist/app.d.ts

@@ -0,0 +1,384 @@
+/**
+ * `HostApp` —— 单根对象：把零件接成一台真能跑、能被连的服务（architecture §3 / §4）。
+ *
+ * 这个文件的边界是三件事：
+ *
+ *   1. **组装**：按对象图的顺序 `new` 出依赖（库 → 仓储 → 配置 → 运行时 → 服务 → 接线），
+ *      每一层都靠构造参数注入；没有模块级单例、没有反射扫描、不读进程工作目录。
+ *   2. **启停**：`start()` 决定监听在哪、把**实际**地址写进发现文件；`stop()` 对称地拆回去
+ *      （摘发现文件、断连接、关上传、回收 Scope、关库）。
+ *   3. **判据**：什么时候「什么都不欠了」可以退出（PRD L4 / 裁定 R53），以及启动时
+ *      「这台机器上是不是已经有人在服务」（单实例，architecture §2）。
+ *
+ * 方法实现不在这里：每个域的 handler 在 `handlers/`，由 {@link createHandlers} 拼成一张表交给
+ * `WsHub`。本文件只给它们提供持有者（服务、运行时、配置、时钟）与几个只有它才接得起来的钩子：
+ *   - **配置生效**（`ConfigApplyPort`）：改完配置要回收受影响的 Scope（F-E2）并发一条通知（F-F9）；
+ *   - **Scope 装配**（`ScopeRegistry` 的工厂）：能力目录由 `DiscoveryService` 按 cwd 算好（R54/L9）；
+ *   - **退出判据**（`checkExit`）：连接数、在跑的轮次、Scope 三个来源都收敛到一处。
+ */
+import { ConfigManager } from "@ai-zen/agents-sdk";
+import type { HandoffService } from "@ai-zen/agents-sdk";
+import type { ListenTarget, HostPaths } from "./config.js";
+import type { Language } from "./i18n/index.js";
+import { UploadReceiver, WsHub } from "./net/index.js";
+import type { HandlerTable, HubLogger } from "./net/index.js";
+import { ChatRunner, RunRegistry, ScopeRegistry } from "./runtime/index.js";
+import type { AgentBuildContext, AgentFactory, Clock, ScopeFactory } from "./runtime/index.js";
+import { ConversationDrafts } from "./runtime/ConversationDrafts.js";
+import { TransientRunner } from "./runtime/TransientRunner.js";
+import { ConversationService, CredentialService, MessageService, SearchService, WorkspaceService } from "./services/index.js";
+import type { ConversationRuntimePort } from "./services/index.js";
+import { AgentService } from "./services/AgentService.js";
+import { AssetService } from "./services/AssetService.js";
+import { AutoNaming } from "./services/AutoNaming.js";
+import { CompletionService } from "./services/CompletionService.js";
+import { ConfigService } from "./services/ConfigService.js";
+import { DiscoveryService } from "./services/DiscoveryService.js";
+import { HandoffService as HandoffDocumentsService } from "./services/HandoffService.js";
+import { ModelService } from "./services/ModelService.js";
+import { NoticeService } from "./services/NoticeService.js";
+import { QuestionService } from "./services/QuestionService.js";
+import { AssetRepository, ConversationRepository, CredentialRepository, Database, MessageRepository, NoticeRepository, QuestionRepository, WorkspaceRepository } from "./storage/index.js";
+import type { CapabilityView } from "./wire/index.js";
+/**
+ * 起一个低频定时器，返回取消函数。
+ *
+ * 缺省实现是 `setInterval(...).unref()`：这个定时器不该成为「进程为什么还没退」的原因。
+ * 做成注入点是因为用例不可能真等 30 秒（假定时器又会把真套接字的关闭路径拖住）。
+ */
+export type RepeatTimer = (task: () => void, everyMs: number) => () => void;
+/** 进程为什么会走到「什么都不欠了」 */
+export type ExitReason = "idle" | "requested";
+/** 退出那一刻的事实（判断依据 + 为什么退） */
+export interface ExitFacts {
+    reason: ExitReason;
+    /** 那一刻还有几条连接（`idle` 时为 0） */
+    connections: number;
+    /** 那一刻还在跑的轮次数（`idle` 时为 0） */
+    runs: number;
+    /** 那一刻还持有几个 Workspace Scope（`idle` 时为 0） */
+    scopes: number;
+}
+/**
+ * 「真的退出」这个动作。
+ *
+ * 进程退不退是不可逆的事，所以做成注入点：生产缺省 `process.exit(0)`，
+ * 用例注入一个记账函数，从而能验证「判据在什么时刻成立」而不把测试进程送走。
+ */
+export type ExitHook = (facts: ExitFacts) => void | Promise<void>;
+/** 组装 `HostApp` 的入参 */
+export interface HostAppOptions {
+    /** 数据根（缺省 `AI_ZEN_DIR`，再缺省 `~/.ai-zen`，PRD F-J4） */
+    aiZenDir?: string;
+    /** 启动参数给的端口（优先级最高，D25）；`0` 表示让系统分配（用例与冒烟用） */
+    port?: number;
+    /**
+     * 配置文件（`<dataRoot>/host.json`）里的端口（第二优先，D25）。
+     *
+     * 不传时由 `create()` 自己读那份文件（裁定 R67）；显式传了就以传入的为准
+     * （命令行已经读过一次，不必再读）。
+     */
+    configPort?: number;
+    /** 显式指定监听地址（优先级高于 `local` 推出的那个） */
+    host?: string;
+    /** 本地实例只监听回环（PRD A6）；缺省 `true` */
+    local?: boolean;
+    /** 宿主版本；缺省读包元数据 */
+    version?: string;
+    /** 造 agent 的工厂；缺省按 SDK 口径装配（用例注入假 agent，不必连模型） */
+    createAgent?: AgentFactory;
+    /** 造 Scope 的工厂；缺省按 SDK 口径装配（用例可以给不带能力的空 Scope） */
+    createScope?: ScopeFactory;
+    /** Scope 空闲回收时长（PRD D28 缺省 10 分钟；用例调小以免真等） */
+    scopeIdleTimeoutMs?: number;
+    /** 交接服务（SDK 口径，装交接线插件用）；未注入时不装插件并推一条警告通知（裁定 R50） */
+    handoff?: (context: AgentBuildContext) => HandoffService | undefined;
+    /** 时钟（Scope 回收计时与用例里的时间推进） */
+    clock?: Clock;
+    /** 真退出时做什么；缺省 `process.exit(0)` */
+    exit?: ExitHook;
+    /** 能力清单（PRD F-E5）；缺省用 `handlers/capabilities.ts` 里那份与契约同步的清单 */
+    capabilities?: (language: Language) => CapabilityView[];
+    /** 连接未声明语言时的缺省语言（PRD D8）；不给时用配置里的 `language`，再缺省英文 */
+    defaultLanguage?: Language;
+    /** 日志口（连接事件与内部错误）；缺省写到 `<dataRoot>/logs/host.log` 并按大小轮转 */
+    logger?: HubLogger;
+    /** 读磁盘上的版本号（D4 / F-E3 的自检要比它）；缺省读本包 `package.json` */
+    diskVersion?: () => string | null;
+    /** 版本自检的间隔（毫秒），缺省 30 秒；用例调小以免真等 */
+    versionCheckIntervalMs?: number;
+    /** 起低频定时器的方式（缺省 `setInterval` + `unref`）；用例注入自己的，从而不必真等 30 秒 */
+    startVersionTimer?: RepeatTimer;
+}
+/**
+ * 宿主版本：读本包的 `package.json`。
+ *
+ * 相对 `import.meta.url` 找而不是读进程工作目录：宿主是常驻后台进程，工作目录由启动方式
+ * 决定（`src/app.ts` 与 `dist/app.js` 的上一级都是包根，两种形态都能读到同一份）。
+ */
+export declare function resolveHostVersion(): string;
+/**
+ * 磁盘上的版本号：读本包的 `package.json`；读不到（或格式不对）返回 `null`。
+ *
+ * 升级判定（D4 / F-E3）要的就是「磁盘上现在是哪个版本」，所以这里与宿主版本共用
+ * 同一处读法，`null` 与 `"0.0.0"` 不混：前者是「不知道」，后者是「真的读到了 0.0.0」。
+ */
+export declare function readDiskVersion(): string | null;
+export declare class HostApp {
+    readonly paths: HostPaths;
+    readonly db: Database;
+    readonly configManager: ConfigManager;
+    readonly workspaces: WorkspaceRepository;
+    readonly conversations: ConversationRepository;
+    readonly messages: MessageRepository;
+    readonly assets: AssetRepository;
+    readonly notices: NoticeRepository;
+    readonly questions: QuestionRepository;
+    readonly credentials: CredentialRepository;
+    readonly scopeRegistry: ScopeRegistry;
+    readonly runRegistry: RunRegistry;
+    /**
+     * 服务层要的两件运行时事实：忙不忙、删掉之后的中止。
+     *
+     * 模型与思考档位不在这里 —— 它们在会话行上。
+     */
+    readonly conversationRuntime: ConversationRuntimePort;
+    /** 还没发过第一条消息的对话（R56：`create` 只发 id 与身份，首次 `send` 才落库） */
+    readonly conversationDrafts: ConversationDrafts;
+    readonly chatRunner: ChatRunner;
+    readonly transientRunner: TransientRunner;
+    readonly assetService: AssetService;
+    readonly workspaceService: WorkspaceService;
+    readonly conversationService: ConversationService;
+    readonly messageService: MessageService;
+    readonly searchService: SearchService;
+    readonly credentialService: CredentialService;
+    readonly discoveryService: DiscoveryService;
+    readonly configService: ConfigService;
+    readonly agentService: AgentService;
+    readonly modelService: ModelService;
+    readonly completionService: CompletionService;
+    readonly noticeService: NoticeService;
+    readonly questionService: QuestionService;
+    readonly handoffService: HandoffDocumentsService;
+    readonly autoNaming: AutoNaming;
+    readonly uploads: UploadReceiver;
+    readonly hub: WsHub;
+    /** 方法名 → 实现（`handlers/createHandlers` 拼出来的那张表） */
+    readonly handlers: HandlerTable;
+    /** 宿主版本（`hello` 与 `host.version` 报的那一个） */
+    readonly version: string;
+    /** 能力清单（PRD F-E5：帮助页与指令菜单按它渲染；按给定语言出句子） */
+    readonly capabilities: (language: Language) => CapabilityView[];
+    /** 进程启动时刻（ISO 8601） */
+    readonly startedAt: string;
+    /** 是不是本地实例（PRD A6：决定监听范围与要不要发本地凭证交付文件） */
+    readonly local: boolean;
+    private readonly options;
+    private readonly clock;
+    private readonly logger;
+    /** 自己拥有的文件日志（注入了外部 logger 时为 `null`：那份不归本对象关） */
+    private readonly fileLogger;
+    private readonly exitHook;
+    /** 磁盘版本的读法（D4 / F-E3 自检用；用例换成假实现） */
+    private readonly readDiskVersion;
+    /** 版本自检的间隔与定时器句柄（`stop()` 里清掉，不留悬挂定时器） */
+    private readonly versionCheckIntervalMs;
+    private readonly startVersionTimer;
+    /** 取消自检定时器（`null` 表示现在没有在跑） */
+    private stopVersionTimer;
+    /** 配置文件给出的端口（第二优先；`undefined` 表示这一档没说话） */
+    private readonly configPort;
+    /** 当前阶段：造好 / 自己监听中 / 挂靠已有实例 / 已收尾 */
+    private phase;
+    private listening;
+    /** 发现文件是不是这一份进程写的（挂靠别人的实例时不能去删它） */
+    private ownsHostFile;
+    /** 收尾只做一次（`host.shutdown`、判据、显式 `stop()` 都可能先到） */
+    private closing;
+    /** 「真的退出」只交棒一次 */
+    private exited;
+    private checking;
+    /** 这条进程至少被用过一次：没有它，刚起来的进程会在第一个客户端连上来之前就判自己该退 */
+    private served;
+    private stopAllRecycled;
+    /** 思考策略表快照（装配 agent 时要把档位名展开成参数，而那一层是同步的） */
+    private presets;
+    /** 推送入口（造好之前为 `null`：这时没有任何连接可推） */
+    private hubForPush;
+    /** 交接服务（SDK 口径）：给了就装交接线插件（R59） */
+    private readonly handoffProvider;
+    /** R50 的那条警告只说一次（描述的是装配能力，不是某一轮的错） */
+    private handoffWarningSent;
+    private constructor();
+    /**
+     * 造一个 `HostApp`（不监听）。
+     *
+     * 顺序上先读配置文件、再开库：端口写得不对（`config_invalid`）时连库都不必建
+     * （裁定 R67：显式给出的非法端口报错，不静默回落）。建库与迁移失败时把库关掉再抛，
+     * 避免留下一个开着 worker 的坏实例。
+     */
+    static create(options?: HostAppOptions): Promise<HostApp>;
+    /** 本进程是否在自己监听 */
+    get running(): boolean;
+    /** 是不是挂靠在「已经在运行」的那个实例上（本进程没监听） */
+    get attached(): boolean;
+    /** 服务地址（`port: 0` 时是系统分配的那个；没在服务时为 `null`） */
+    get address(): ListenTarget | null;
+    /**
+     * 开始服务。
+     *
+     * 两步顺序是有意的：
+     *   1. **先看这台机器上是不是已经有人在服务**（发现文件是唯一真相）。活着就挂靠它的地址，
+     *      本进程不重复监听 —— 同一个数据根起两个进程会各写一份 `host.json`，客户端连谁都不对。
+     *      陈旧的（pid 已死、或文件坏了）清掉再起。
+     *   2. 自己起：本地实例先备好凭证交付文件 → 监听 → 按**实际**地址写发现文件。客户端读的是
+     *      发现文件里的端口，端口被占退回临时端口时启动参数里的那个数已经不是真的了。
+     */
+    start(): Promise<ListenTarget>;
+    /**
+     * 收尾：对称于 `start()` —— 摘发现文件 → 回收 Scope → 断连接 → 关上传 → 关库。
+     *
+     * 幂等：`host.shutdown`、判据、信号处理器都可能先到，只有第一次真的做事。
+     * 挂靠别人的实例时不摘发现文件（那份不属于本进程）。
+     */
+    stop(reason?: ExitReason): Promise<ExitFacts>;
+    /** 收尾 + 交棒给「真的退出」（判据成立、`host.shutdown`、信号处理器走这条） */
+    shutdown(reason?: ExitReason): Promise<ExitFacts>;
+    /**
+     * 退出判据（PRD L4 / 裁定 R53）：没有连接、没有在跑的轮次、Scope 全部回收 —— 什么都不欠了。
+     *
+     * 触发源有三个，都不另起计时器（A10：计时器只有一处，即 `ScopeRegistry` 里那份空闲计时）：
+     *   - `ScopeRegistry.onAllRecycled`：Scope 全部拆完那一刻；
+     *   - 每轮结算（`onTurnSettled`）：最后一件欠着的事可能是刚跑完的这一轮；
+     *   - `WsHub.onConnectionsChanged`：最后一条连接走了。
+     *
+     * 两个防止误退的口子：
+     *   1. **还没被真正用过**时不判：只有握过手（凭证被接受）的连接才算「有人用过它」，
+     *      刚起来的进程与端口扫描器留下的空连接都不该把宿主送走；
+     *   2. 只在自己监听中判断（造好未启动、挂靠别人、已收尾时都不判）。
+     */
+    checkExit(): Promise<void>;
+    private doStop;
+    /**
+     * 起一个低频自检：磁盘上的版本号变了（且已经是新的）就收尾退出，由启动方式重拉。
+     *
+     * 这个定时器不是退出判据的触发源（A10：计时器只有 `ScopeRegistry` 那一份负责回收），
+     * 它只把「包已经换了」这个事实变成一次重启。缺省的启动方式带 `unref()`：
+     * 只有它还在跑时，也不该拦住进程退出。
+     */
+    private startVersionCheck;
+    /** 清掉自检定时器（`stop()` 里调：用例会断言退出后没有悬挂定时器） */
+    private stopVersionCheck;
+    /**
+     * 比一次磁盘版本与运行版本。
+     *
+     * 三条前提都成立才重启：磁盘读得出来、与正在跑的不是同一个版本、且磁盘上的那个**更新**
+     * （回退不算升级，重启只会把用户拉回旧版本）。重启前推一条通知：进程会走，界面上得有个交代。
+     */
+    private checkDiskVersion;
+    /**
+     * 启动时的单实例自查（architecture §2：发现文件是「这台机器上谁在服务」的唯一真相）。
+     *
+     * 三种情况分开处理：
+     *   - 没有文件：没人服务，正常起；
+     *   - 文件在、pid 活着：有人服务，返回它的地址（调用方据此挂靠）；
+     *   - 文件在、pid 已死（或文件坏了）：留在那儿只会让客户端连一个不存在的进程，清掉再起。
+     */
+    private detectRunningInstance;
+    /** 把持有者交给 handler 层：它只拿引用，不 new 任何东西 */
+    private handlerDeps;
+    /**
+     * `host.shutdown` 的收尾请求。
+     *
+     * 收尾放在下一轮事件循环：回包要先把「受理了」写出去，客户端才知道它没白点。
+     */
+    private requestStop;
+    /** 监听地址：`local` 推默认地址，显式 `host` 覆盖它；`port: 0` 原样交给系统分配 */
+    private resolveTarget;
+    /** 缺省的 Scope 工厂：按 SDK 口径装能力，能力目录由发现服务按 cwd 算好（R54 / L9） */
+    private defaultScopeFactory;
+    /** 缺省的 agent 工厂：SDK 口径装配（硬线、子 Agent 递归、交接线、工具刷新） */
+    private defaultAgentFactory;
+    /**
+     * 这一轮用哪个交接服务（R59：交接插件真的装上，不再因为「没注入」而整体不装）。
+     *
+     * 缺省实现按这一轮 Scope 的 cwd 造一个 SDK 交接服务（文档写进项目，D19）。拿不到时
+     * 说一声（R50：不静默）——这条警告描述的是装配能力，所以一个进程只说一次。
+     */
+    private handoffFor;
+    /** 缺省的交接服务：按这一轮的 cwd 造 SDK 口径的那个（文档落 `<cwd>/.ai-zen/handoffs`） */
+    private defaultHandoffProvider;
+    /**
+     * 一轮结算之后：到了交接线就在对话停下之后问用户（R59 / F-D2 / D22）。
+     *
+     * 三个前提任缺一条都不问：模型配了交接线且这一轮真的越过了它、对话已经停下（不在流式中途）、
+     * 没有已挂着的交接问题（多端看到的是同一行）。问与答之后的事都归 `QuestionService`。
+     */
+    private askHandoffAfterSettle;
+    /** R50 的那一条警告：交接插件没装时至少让人在通知栏里看到 */
+    private notifyMissingHandoff;
+    /**
+     * 服务层要的那个窄接口（`ConversationRuntimePort`）。
+     *
+     * `forget` 指向 `ChatRunner.forget`（中止在跑的轮次、清掉这一轮的内存现场）。它只能晚绑定：
+     * 服务比执行者先造出来，所以这里闭包住 `this`，调用那一刻才去拿 `chatRunner`。
+     */
+    private createConversationRuntime;
+    /** 素材转换要的实发模型与端点（F-H7 的判定依据：模型能不能看图、端点有没有 Files API） */
+    private resolveModelContext;
+    /** 读配置；坏了就是 `config_invalid`（服务层读配置时也是这个口径） */
+    private readConfig;
+    /** 凭证校验：顺手记下「这条进程被用过」（握手成功即算） */
+    private buildVerifier;
+    private nowIso;
+    /**
+     * 记一条普通信息（生命周期事件这类）。
+     *
+     * 注入了外部 logger 时它就是 `HubLogger`（只有 warn / error），所以这条走文件日志那一侧；
+     * 没有文件日志时什么也不做。
+     */
+    private logInfo;
+    /**
+     * 连接没声明语言时用哪一种（PRD D8 / 裁定 R58）。
+     *
+     * 真相在 `config.json` 的 `language`（可经 `config.setDefaults` 改），所以每一跳都现读；
+     * 配置读不出来或没写这个字段时回落英文 —— 语言这件事不该让握手失败。
+     */
+    private configuredLanguage;
+    /**
+     * 推送一个事件（`NoticeService` / `QuestionService` / `ChatRunner` 共用同一个出口）。
+     *
+     * 造好接线层之前没有连接可推，这时的事件只写库不外发（重连之后客户端自己拉，L5）。
+     */
+    private emitEvent;
+    /**
+     * 把「配置变了」这件事办成两件具体的事：回收受影响的能力、合成一条通知。
+     *
+     * 回收的粒度按改动范围分：只改了某个项目的 MCP（`workspace` 作用域）→ 只拆那个项目的
+     * Scope；其余改动（端点 / 模型 / 上限 / 用户级 MCP）影响所有 Scope → 全部回收。
+     * `recycleAll` 对正被持有的 Scope 是「打完标记等它释放」，所以报告里的 id 是
+     * 「将会重建的那些」—— 正在跑的那一轮不会在写到一半时被抽掉能力（R52）。
+     */
+    private createApplyPort;
+    private recycleScopesFor;
+    /**
+     * `host.upgrade`：比一次「磁盘上的版本」与「正在跑的版本」。
+     *
+     * 三种结论（契约里的 `HostUpgradeState`）：磁盘读不出来 → `not_available`；两个版本一样
+     * 且没有要求别的目标 → `already_latest`；磁盘已经是新的（或请求的目标版本已落盘）→
+     * `restart_scheduled`，随后安排一次收尾：进程退出后由启动方式重新拉起（宿主不自己装包，
+     * D4）。
+     */
+    private upgradeHost;
+}
+/** 造一个 `HostApp`（`index.ts` 的 `createHost` 就是它） */
+export declare function createHost(options?: HostAppOptions): Promise<HostApp>;
+/**
+ * 比两个版本号（`1.2.0` 与 `1.10.0`）：返回 `<0` 表示左边旧、`0` 相同、`>0` 左边新。
+ *
+ * 按 `.` 切段逐段比，两段都是数字时按数字比（`1.10.0` 比 `1.9.0` 新）；不是数字的段
+ * （`alpha` 这种预发布标记）按字符串比。够用的理由：升级自检只回答「磁盘上的是不是比我新」，
+ * 不排序、不解析 semver 的完整规则。
+ */
+export declare function compareVersions(left: string, right: string): number;