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

package/dist/handlers/conversationHandlers.js

@@ -0,0 +1,314 @@
+/**
+ * `conversation.*`：一段对话的身份、历史与一轮的运行。
+ *
+ * 这里只做「参数 → 交给服务/运行时 → 把结果翻译成契约形状」。业务判断在
+ * `ConversationService` 与 `ChatRunner` 里：比如「忙就拒」在 `RunRegistry`、
+ * 「模型解析不出来」在服务层，本文件不重新判断一遍。
+ *
+ * 唯一在接线层做的拼装是 `conversation.state` 的现场快照：它要把三处事实合起来
+ * （服务层给的视图、运行时给的这一轮、库里消息求和的用量），而这三样分别属于三个持有者，
+ * 只有接线层同时看得见它们。
+ *
+ * 一段对话的三处跨界钩子也在这里接（它们分属三个服务，契约里的位置却是同一对方法）：
+ *   - `conversation.send` 之前问一句「有挡着的问题吗」（D23）；
+ *   - 结算之后起一次自动命名（D2，幂等）；
+ *   - `conversation.transient` 走不落库的那条执行路径（R1 / R49）。
+ */
+import { addUsage, sumUsage, ZERO_USAGE } from "@ai-zen/agents-core";
+import { render } from "../i18n/index.js";
+import { STATUS_BLOCK_IDS } from "../wire/index.js";
+import { localizeOutcome } from "./assetHandlers.js";
+/**
+ * 注册 `conversation.*`。
+ *
+ * `conversation.transient`（临时对话，PRD D3）注册的前提是注入了 `runTransient`：
+ * 不注入时这个方法仍然落到接线层的 `unsupported`（裁定 R11）。
+ */
+export function createConversationHandlers(deps) {
+    const handlers = {
+        "conversation.list": async (context) => await deps.conversations.list(context.params),
+        "conversation.create": async (context) => await deps.conversations.create(context.params),
+        "conversation.get": async (context) => await deps.conversations.get(context.params),
+        "conversation.rename": async (context) => await deps.conversations.rename(context.params),
+        "conversation.pin": async (context) => await deps.conversations.pin(context.params),
+        "conversation.revert": async (context) => await deps.conversations.revert(context.params),
+        "conversation.setModel": async (context) => await deps.conversations.setModel(context.params),
+        "conversation.delete": async (context) => await removeConversation(deps, context.params),
+        "conversation.send": async (context) => await sendTurn(deps, context.params, context.connection.language),
+        "conversation.state": async (context) => {
+            const snapshot = await conversationStateOf(deps, context.params.conversationId, context.connection.language);
+            // 消息来自同一次读取（用量与上下文已经要了它），要就一起给，不要就整个键不出现
+            return context.params.includeMessages
+                ? { state: snapshot.state, messages: snapshot.messages }
+                : { state: snapshot.state };
+        },
+        "conversation.abort": async (context) => await abort(deps, context.params),
+        "conversation.setThinking": async (context) => {
+            // 档位表先刷新一次再改：改完读回的「展开后的参数」要用当前表
+            await deps.refreshThinkingPresets();
+            return await deps.conversations.setThinking(context.params);
+        },
+    };
+    const runTransient = deps.runTransient;
+    if (runTransient) {
+        // 临时对话没有 id、不落库、不推流式事件：一次调用同步返回结果（R1 / R49）
+        handlers["conversation.transient"] = async (context) => await runTransient(context.params, context.connection.language);
+    }
+    return handlers;
+}
+// ---------------------------------------------------------------------------
+// 跨层补齐
+// ---------------------------------------------------------------------------
+/**
+ * `conversation.send`：受理一轮。
+ *
+ * 先把草稿落成真行（R56：首次 `send` 时才写 `conversations`）：FK 要求消息所属的对话已经存在，
+ * 而且后端的一切（重连、列表、删除）都按「存在即能查」处理。
+ *
+ * 素材关系行不在这里写：它跟着「用户消息落库那一刻」走（`ChatRunner` 注入的
+ * `linkMessageAssets` 扫落库内容里的 `__asset_id`），所以重试与重写都不会重复记。
+ *
+ * 附件结局里的句子是素材层按默认语言渲染的（那一层不知道收件人是谁），这里按**这条连接**的
+ * 语言重渲染一次再出网（D8：库里只留码与参数）。
+ */
+async function sendTurn(deps, params, language) {
+    // D23：有一段挡着的问题（交接确认、不可撤销动作的确认）就先答它再发
+    await deps.assertSendable?.(params.conversationId);
+    // R56：草稿在第一条用户消息之前不落库，这里把它写成真行（同一个 id）
+    await deps.conversations.ensurePersisted(params.conversationId);
+    const turn = await deps.runner.run({
+        conversationId: params.conversationId,
+        input: params.input,
+        language,
+    });
+    // 结算之后的两个收尾：起一次自动命名（D2，条件不成立时它自己什么都不做），
+    // 再让单根重算一次退出判据（这一轮可能是最后一件欠着的事）
+    void turn.done.then(async () => {
+        try {
+            await deps.autoNameAfterTurn?.(params.conversationId, language);
+        }
+        catch (error) {
+            // 起名失败就是「没起成」（D2：保持原名），不影响已经结算的这一轮
+            deps.onHookError?.(error, "autoNaming");
+        }
+        deps.onTurnSettled();
+    }, () => deps.onTurnSettled());
+    return {
+        userMessageId: turn.userMessageId,
+        assistantMessageId: turn.assistantMessageId,
+        attachments: turn.attachments.map((outcome) => localizeOutcome(outcome, language)),
+        acceptedAt: turn.acceptedAt,
+    };
+}
+/**
+ * `conversation.delete`：删掉这段对话，再补齐一件只有接线层知道的事（R33）。
+ *
+ * 运行时里这一轮的现场要丢掉（`ChatRunner.forget`：正在跑就先让它停）；素材字节的清理不在这里
+ * —— 服务层删完之后已经由素材层问过「还剩几张引用」，归零的那几份才删（见
+ * `ConversationService.delete` 的 `sweepAssets`）。
+ */
+async function removeConversation(deps, params) {
+    const report = await deps.conversations.delete(params);
+    if (params.dryRun !== true && report.removed) {
+        deps.runner.forget(params.conversationId);
+    }
+    return { removed: report.removed, consequences: report.consequences };
+}
+/**
+ * `conversation.abort`：中止走 `RunRegistry`（`ChatRunner` 只是把它转发出去）。
+ *
+ * `aborted: false` 表示本来就没在跑 —— 那不是错误。回包同时带上中止之后的运行状态，
+ * 客户端不必再拉一次现场就能把界面收回去。
+ */
+async function abort(deps, params) {
+    const aborted = deps.runner.abort(params.conversationId, params.reason);
+    return { aborted, run: await runStateOf(deps, params.conversationId) };
+}
+// ---------------------------------------------------------------------------
+// 现场快照
+// ---------------------------------------------------------------------------
+/** 这一轮现在的运行状态；没有在跑的一轮时是「空闲」（`state` 与 `abort` 共用） */
+async function runStateOf(deps, conversationId) {
+    const turn = deps.runner.turn(conversationId);
+    if (turn)
+        return turn.runState();
+    const page = await deps.messages.list({ conversationId });
+    return idleRunState(conversationId, usageOfMessages(page.messages, deps.now()));
+}
+/**
+ * 一段对话的现场（PRD L5：重连先拉状态）。
+ *
+ * 拼装顺序：视图（身份 / 思考档 / 目录）→ 运行状态（在跑就用这一轮自己的快照）→
+ * 用量（在跑用这一轮，空闲就用库里消息求和）→ 上下文阈值（跟着模型走）→ 挂在这段对话上的问题
+ * → 状态栏的块（PRD F-I6）。
+ */
+async function conversationStateOf(deps, conversationId, language) {
+    const now = deps.now();
+    const { conversation } = await deps.conversations.get({ conversationId });
+    const turn = deps.runner.turn(conversationId);
+    const page = await deps.messages.list({ conversationId });
+    const usage = turn ? turn.runState().usage : usageOfMessages(page.messages, now);
+    const config = await deps.readConfig();
+    const model = config.models.find((item) => item.id === conversation.model.modelId);
+    const run = turn ? turn.runState() : idleRunState(conversationId, usage);
+    const context = contextOf(page.messages, model);
+    // 助手那条事实只在这里取一次（IO 留在这里，下面拼块的那一步仍是同步纯函数）
+    const agent = await agentFactOf(deps, conversation.agentId);
+    return {
+        state: {
+            conversationId,
+            run,
+            context,
+            thinking: conversation.thinking,
+            usage,
+            questions: deps.questionsFor ? await deps.questionsFor(conversationId) : [],
+            statusBlocks: statusBlocksOf({ conversation, agent, run, context, usage, language }),
+            updatedAt: now,
+        },
+        // 这份消息就是上面算用量与上下文用的那一次读取，不是又读一遍
+        messages: page.messages,
+    };
+}
+// ---------------------------------------------------------------------------
+// 状态栏的块（PRD F-I6 / 裁定 R65）
+// ---------------------------------------------------------------------------
+/**
+ * 助手块的那两条事实（名字 / 能不能用，PRD F-I6）。
+ *
+ * 真相在助手定义那一层，这里只读一次，把它变成块能装的那两格；拼块的 `statusBlocksOf`
+ * 于是仍然是同步纯函数。没注入助手服务、或定义已经没了（被删 / 读不出来）时两格都是 `null`
+ * —— 说「不知道」而不是编一个看起来像真的值。
+ */
+async function agentFactOf(deps, agentId) {
+    const described = await deps.agents?.describe(agentId);
+    if (!described)
+        return { name: null, available: null };
+    return { name: described.name, available: described.available };
+}
+/** 块的标签（`label.agent` / `label.model` …，PRD F-I6：宿主给块名，客户端排版） */
+function blockLabel(id, language) {
+    const messageKey = `label.${id}`;
+    return { code: messageKey, messageKey, params: {}, message: render(language, messageKey) };
+}
+/**
+ * 按 `STATUS_BLOCK_IDS` 的顺序拼装状态栏的块（PRD F-I6 / 裁定 R65）。
+ *
+ * 这里**不产生新事实**：每一块装的都是别处已经算好的那份 —— 对话视图里的身份 / 模型 / 思考档 /
+ * 目录、`conversation.state` 里的上下文与用量、以及这一轮快照里的六态与子 Agent。工具块只取
+ * `awaiting_tools` 态里还在跑的那几个（并行时有几个列几个，正是 L8 要的语义）；其余态下没有
+ * 工具在跑，列表就是空的。
+ *
+ * 助手块的 `name` / `available` 由调用方（`conversationStateOf`）先从助手定义那一层读好传进来
+ * （`input.agent`）：本函数保持同步纯函数，不在这里做 IO。
+ */
+export function statusBlocksOf(input) {
+    const { conversation, agent, run, context, usage, language } = input;
+    const generation = run.generation;
+    const runningTools = generation?.phase === "awaiting_tools" ? generation.runningTools : [];
+    const blocks = {
+        agent: {
+            id: "agent",
+            label: blockLabel("agent", language),
+            facts: { agentId: conversation.agentId, name: agent.name, available: agent.available },
+        },
+        model: {
+            id: "model",
+            label: blockLabel("model", language),
+            facts: conversation.model,
+        },
+        thinking: {
+            id: "thinking",
+            label: blockLabel("thinking", language),
+            facts: conversation.thinking,
+        },
+        context: {
+            id: "context",
+            label: blockLabel("context", language),
+            facts: context,
+        },
+        usage: {
+            id: "usage",
+            label: blockLabel("usage", language),
+            facts: usage,
+        },
+        cwd: {
+            id: "cwd",
+            label: blockLabel("cwd", language),
+            facts: conversation.folder,
+        },
+        tools: {
+            id: "tools",
+            label: blockLabel("tools", language),
+            facts: { running: runningTools },
+        },
+        subagents: {
+            id: "subagents",
+            label: blockLabel("subagents", language),
+            facts: { items: run.subagents },
+        },
+    };
+    // 顺序按 `STATUS_BLOCK_IDS` 给：那是建议的摆放顺序，客户端可以只取自己摆得下的前几块
+    return STATUS_BLOCK_IDS.map((id) => blocks[id]);
+}
+// ---------------------------------------------------------------------------
+// 纯函数：把几处事实拼成契约形状
+// ---------------------------------------------------------------------------
+/** 空闲的现场：没有在跑的一轮，但历史用量还在 */
+export function idleRunState(conversationId, usage) {
+    return {
+        conversationId,
+        status: "idle",
+        assistantMessageId: null,
+        startedAt: null,
+        settledAt: null,
+        generation: null,
+        outcome: null,
+        problem: null,
+        subagents: [],
+        usage,
+    };
+}
+/**
+ * 一批消息的用量快照。
+ *
+ * `total` 与 `subAgent` 用 core 的口径求和（含子 Agent，与计费同口径）；`turn` 在「没有一轮
+ * 在跑」时是零值（没有这一轮这件事，就是零），速率同理。
+ */
+export function usageOfMessages(messages, now) {
+    let subAgent = { ...ZERO_USAGE };
+    for (const message of messages) {
+        if (message.subAgentUsage)
+            subAgent = addUsage(subAgent, message.subAgentUsage);
+    }
+    return {
+        turn: { ...ZERO_USAGE },
+        total: sumUsage(messages),
+        subAgent,
+        rate: { value: 0, unit: "tokens_per_second", basis: "completion" },
+        updatedAt: now,
+    };
+}
+/**
+ * 上下文占用：最近一次请求的用量 + 这个模型的两条阈值（PRD F-D1 / D27）。
+ *
+ * 阈值跟着模型走；模型在配置里被删掉时两条线都是 0（「没有阈值」而不是「阈值为零就超了」）。
+ */
+export function contextOf(messages, model) {
+    let usage = { ...ZERO_USAGE };
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const candidate = messages[index]?.usage;
+        if (candidate) {
+            usage = candidate;
+            break;
+        }
+    }
+    const handoffThreshold = model?.tokenThresholds.handoff ?? 0;
+    const guardThreshold = model?.tokenThresholds.guard ?? 0;
+    return {
+        usage,
+        handoffThreshold,
+        guardThreshold,
+        overHandoff: handoffThreshold > 0 && usage.prompt_tokens >= handoffThreshold,
+        overGuard: guardThreshold > 0 && usage.prompt_tokens >= guardThreshold,
+    };
+}

package/dist/handlers/handoffHandlers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `handoff.*` 两个方法的接线（PRD F-D3 / F-D4 / F-D5 / F-D6 / F-D7 / D18 / D19）。
+ *
+ * `handoff.start` 的失败形态有两种，客户端要能分开看：
+ *   - 用户取消 → 业务码 `handoff_declined`（不是失败，会话回到交接前，F-D7）；
+ *   - 真失败 → `internal` + `error.handoffFailed`（带上原因）。
+ * 降级不是失败：结果是成功的，`degraded` / `problem` 里说明退到了哪一档。
+ */
+import type { HandlerTable } from "../net/WsHub.js";
+import type { HandoffService } from "../services/HandoffService.js";
+export interface HandoffHandlerDeps {
+    /** 只要本域用到的那两个方法（结构上 `HandoffService` 满足，用例可以给替身） */
+    handoff: Pick<HandoffService, "start" | "listDocuments">;
+}
+/** 本域注册的方法 */
+export type HandoffHandlers = Pick<HandlerTable, "handoff.start" | "handoff.listDocuments">;
+export declare function createHandoffHandlers(deps: HandoffHandlerDeps): HandoffHandlers;

package/dist/handlers/handoffHandlers.js

@@ -0,0 +1,14 @@
+/**
+ * `handoff.*` 两个方法的接线（PRD F-D3 / F-D4 / F-D5 / F-D6 / F-D7 / D18 / D19）。
+ *
+ * `handoff.start` 的失败形态有两种，客户端要能分开看：
+ *   - 用户取消 → 业务码 `handoff_declined`（不是失败，会话回到交接前，F-D7）；
+ *   - 真失败 → `internal` + `error.handoffFailed`（带上原因）。
+ * 降级不是失败：结果是成功的，`degraded` / `problem` 里说明退到了哪一档。
+ */
+export function createHandoffHandlers(deps) {
+    return {
+        "handoff.start": async (context) => await deps.handoff.start(context.params, context.connection.language),
+        "handoff.listDocuments": async (context) => await deps.handoff.listDocuments(context.params),
+    };
+}

package/dist/handlers/hostHandlers.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `host.*`：进程事实（PRD F-E5 / D4 / L4）。
+ *
+ * 三件事在这里：
+ *   - `version` / `capabilities`：报事实，供帮助页与指令菜单渲染（能力清单只在配置层维护一份，
+ *     这里不编造）；
+ *   - `upgrade`：比磁盘上的版本与正在跑的版本，确认新版本真的落盘了才安排重启（D4 / F-E3）；
+ *   - `shutdown`：受理一次收尾请求。真正退不退由单根的退出判据决定（PRD L4 / 裁定 R53）。
+ *
+ * `host.hello` / `host.setLanguage` / `asset.*` 由接线层自己接管（语言是连接状态、
+ * 上传要按连接分帧），这里不重复注册。
+ *
+ * `host.reload`（F-E1）在这里只做转发：重载是「让磁盘上的改动生效」，那条路（回收 Scope、
+ * 合成一条通知）的持有者是配置服务。
+ *
+ * 用量不在这一域（裁定 2026-11-13）：F-I5 的「本轮 / 累计（含子 Agent）/ 速率」由
+ * `conversation.state` 的 `usage`（`UsageSnapshot`）给，`host.usage` 的「按项目 / 整机」聚合
+ * 没有任何客户端消费，已从契约面删除。
+ */
+import type { HandlerTable } from "../net/index.js";
+import type { CapabilityView, HostReloadParams, HostReloadResult, HostUpgradeParams, HostUpgradeResult } from "../wire/index.js";
+/** `host.*` 的实现要的持有者 */
+export interface HostHandlerDeps {
+    /** 宿主版本（`hello` 报的那一个） */
+    version: string;
+    /** 进程启动时刻（ISO 8601） */
+    startedAt: string;
+    /** 能力清单（PRD F-E5）；内容归配置层，本轮由单根注入 */
+    capabilities: () => CapabilityView[];
+    /** 请求收尾（`host.shutdown`）：单根排程，先让回包写出去 */
+    requestStop: (reason?: string) => void;
+    /** 从磁盘重载（`host.reload`）：配置服务那边跑「生效」那条路（回收 Scope + 合成通知） */
+    reload: (params: HostReloadParams) => Promise<HostReloadResult>;
+    /** 升级判定与重启排程（磁盘版本归单根去读，这里只把结论转给客户端） */
+    upgrade: HostUpgradeHandler;
+}
+/** `host.upgrade` 的实现（结论由单根算，本文件只转发入参） */
+export type HostUpgradeHandler = (params: HostUpgradeParams) => Promise<HostUpgradeResult>;
+export declare function createHostHandlers(deps: HostHandlerDeps): HandlerTable;

package/dist/handlers/hostHandlers.js

@@ -0,0 +1,56 @@
+/**
+ * `host.*`：进程事实（PRD F-E5 / D4 / L4）。
+ *
+ * 三件事在这里：
+ *   - `version` / `capabilities`：报事实，供帮助页与指令菜单渲染（能力清单只在配置层维护一份，
+ *     这里不编造）；
+ *   - `upgrade`：比磁盘上的版本与正在跑的版本，确认新版本真的落盘了才安排重启（D4 / F-E3）；
+ *   - `shutdown`：受理一次收尾请求。真正退不退由单根的退出判据决定（PRD L4 / 裁定 R53）。
+ *
+ * `host.hello` / `host.setLanguage` / `asset.*` 由接线层自己接管（语言是连接状态、
+ * 上传要按连接分帧），这里不重复注册。
+ *
+ * `host.reload`（F-E1）在这里只做转发：重载是「让磁盘上的改动生效」，那条路（回收 Scope、
+ * 合成一条通知）的持有者是配置服务。
+ *
+ * 用量不在这一域（裁定 2026-11-13）：F-I5 的「本轮 / 累计（含子 Agent）/ 速率」由
+ * `conversation.state` 的 `usage`（`UsageSnapshot`）给，`host.usage` 的「按项目 / 整机」聚合
+ * 没有任何客户端消费，已从契约面删除。
+ */
+import { relocalizeText } from "../services/NoticeService.js";
+import { PROTOCOL_VERSION } from "../wire/index.js";
+export function createHostHandlers(deps) {
+    return {
+        "host.version": () => ({
+            version: deps.version,
+            protocolVersion: PROTOCOL_VERSION,
+            startedAt: deps.startedAt,
+            pid: process.pid,
+        }),
+        "host.capabilities": (context) => ({
+            // 清单按这条连接的语言出句子（裁定 R58）：id / 顺序与语言无关（R57）
+            capabilities: localizeCapabilities(deps.capabilities(), context.connection.language),
+        }),
+        "host.shutdown": (context) => {
+            deps.requestStop(context.params.reason);
+            return { accepted: true };
+        },
+        // 升级即重启（D4 / F-E3）：结论由单根给，它知道磁盘上的版本与重启排程
+        "host.upgrade": async (context) => await deps.upgrade(context.params),
+        // 重载不重启（F-E1 / F-E2 / R63）：与改配置走同一条生效路径，回同一份报告
+        "host.reload": async (context) => await deps.reload(context.params),
+    };
+}
+/**
+ * 能力清单按这条连接的语言重渲染（裁定 R58）。
+ *
+ * 清单本身由配置层按缺省语言产出（每项的标题与说明都带着 `messageKey` + `params`），这里只把
+ * 句子换成收件人的语言 —— 与通知、问题出网前那一跳同一个口径（D8：存码不存句子）。
+ */
+function localizeCapabilities(capabilities, language) {
+    return capabilities.map((capability) => ({
+        ...capability,
+        title: relocalizeText(capability.title, language),
+        description: relocalizeText(capability.description, language),
+    }));
+}

package/dist/handlers/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * handler 表的唯一出口（architecture §3 / §6）。
+ *
+ * `WsHub` 只认一张表：方法名 → 实现。方法名的真相在 `wire/methods.ts`（`MethodMap`），
+ * 这里把每个有实现者的域拼起来交给接线层。
+ *
+ * 各域分文件放，是为了让「这一域要哪些持有者」写在它自己的 `deps` 接口上：接线层照着注入，
+ * 而不是把一个巨大的 `app` 对象塞进每个 handler 里。
+ *
+ * 组装方式仍是显式构造注入：`HostApp` 造好服务与运行时之后，把引用交进来，本模块不 new
+ * 任何东西、不读全局路径、不持有单例。
+ *
+ * 四件事在**接线层**而不是这张表里（`handlers/index.test.ts` 把这份名单钉住）：
+ *   - `host.hello` / `host.setLanguage`：语言与凭证都是连接状态（`net/WsHub`）；
+ *   - `asset.begin` / `asset.end`：上传要按连接分帧落盘（`net/UploadReceiver`）。
+ *
+ * 除这四条以外，契约里的每个方法都必须在这张表里 —— 否则客户端会拿到 `unsupported`，
+ * 而那是「这个宿主没有这个功能」的意思，不该用来掩盖「忘了接」。
+ */
+import type { AppConfig } from "@ai-zen/agents-sdk";
+import type { Language } from "../i18n/index.js";
+import type { HandlerTable } from "../net/index.js";
+import type { ChatRunner, ScopeRegistry } from "../runtime/index.js";
+import type { TransientRunner } from "../runtime/TransientRunner.js";
+import type { AgentService } from "../services/AgentService.js";
+import type { AssetService } from "../services/AssetService.js";
+import type { CompletionService } from "../services/CompletionService.js";
+import type { ConfigService } from "../services/ConfigService.js";
+import type { ConversationService } from "../services/ConversationService.js";
+import type { HandoffService } from "../services/HandoffService.js";
+import type { MessageService } from "../services/MessageService.js";
+import type { ModelService } from "../services/ModelService.js";
+import type { NoticeService } from "../services/NoticeService.js";
+import type { QuestionService } from "../services/QuestionService.js";
+import type { SearchService } from "../services/SearchService.js";
+import type { WorkspaceService } from "../services/WorkspaceService.js";
+import type { CapabilityView, MethodName, QuestionView, HostReloadParams, HostReloadResult } from "../wire/index.js";
+import type { EventMap, EventName } from "../wire/events.js";
+export type { AgentHandlerDeps } from "./agentHandlers.js";
+export type { AssetHandlerDeps } from "./assetHandlers.js";
+export type { CompletionHandlerDeps } from "./completionHandlers.js";
+export type { ConfigHandlerDeps } from "./configHandlers.js";
+export type { ConversationHandlerDeps } from "./conversationHandlers.js";
+export type { HandoffHandlerDeps } from "./handoffHandlers.js";
+export type { MessageHandlerDeps } from "./messageHandlers.js";
+export type { ModelHandlerDeps } from "./modelHandlers.js";
+export type { NoticeHandlerDeps } from "./noticeHandlers.js";
+export type { QuestionHandlerDeps } from "./questionHandlers.js";
+export type { SearchHandlerDeps } from "./searchHandlers.js";
+export type { HostHandlerDeps } from "./hostHandlers.js";
+export type { WorkspaceHandlerDeps } from "./workspaceHandlers.js";
+export { createCapabilities } from "./capabilities.js";
+/**
+ * 由接线层代管、因此不在 handler 表里的方法名。
+ *
+ * 这份名单是「表可以缺哪些」的唯一真相：验收用例按它判「契约里的每个方法要么在表里、
+ * 要么在这里」。往这里加一条就等于说「接线层自己实现了它」——`net/WsHub` 也确实在分发时
+ * 先处理这四个名字。
+ */
+export declare const BRIDGED_METHODS: readonly MethodName[];
+/**
+ * 组装 handler 表要的全部持有者。
+ *
+ * 一个平坦的形状（而不是每域各注入一个对象）是因为单根本来就把这些都拿在手上；
+ * 域函数各自声明自己要哪几样，单根把它们平铺进去，谁需要什么仍然一目了然。
+ */
+export interface HandlerDeps {
+    /** 宿主版本（`hello` 报的那一个） */
+    version: string;
+    /** 进程启动时刻（ISO 8601） */
+    startedAt: string;
+    /** 能力清单（PRD F-E5） */
+    capabilities: () => CapabilityView[];
+    workspaces: WorkspaceService;
+    conversations: ConversationService;
+    messages: MessageService;
+    search: SearchService;
+    assets: AssetService;
+    config: ConfigService;
+    agents: AgentService;
+    models: ModelService;
+    completion: CompletionService;
+    notices: NoticeService;
+    questions: QuestionService;
+    handoff: HandoffService;
+    runner: ChatRunner;
+    scopes: ScopeRegistry;
+    /** 临时对话的执行者（D3 / R49：不落库、不推流式事件） */
+    transient: TransientRunner;
+    /** 读配置（上下文阈值跟着模型走，PRD F-D1 / D27） */
+    readConfig: () => Promise<AppConfig>;
+    /** 刷新思考策略表快照（`conversation.setThinking` 之前调一次） */
+    refreshThinkingPresets: () => Promise<void>;
+    /** 时钟：契约里的时间一律 ISO 8601 字符串 */
+    now: () => string;
+    /** 推事件（`conversation.changed` 这类多端同步信号）；不注入时不推 */
+    emit?: <E extends EventName>(name: E, payload: EventMap[E]) => void;
+    /** 有挡着的问题就拒发（D23）；发之前问一句 */
+    assertSendable: (conversationId: string) => Promise<void>;
+    /** 一轮结算之后起一次自动命名（D2） */
+    autoNameAfterTurn: (conversationId: string, language: Language) => Promise<void>;
+    /** 结算后钩子失败的去处（命名没跑成不该让已经结算的一轮变成失败） */
+    onHookError: (error: unknown, hook: string) => void;
+    /** 现场快照里那段对话的问题（D22：多端看同一批） */
+    questionsFor: (conversationId: string) => Promise<QuestionView[]>;
+    /** 请求收尾（`host.shutdown`）；真正的退出判定在单根 */
+    requestStop: (reason?: string) => void;
+    /** 一轮结算之后重算退出判据（L4：这是「什么都不欠了」的触发源之一） */
+    onTurnSettled: () => void;
+    /** 升级判定与重启排程（`host.upgrade`：比磁盘版本与运行版本） */
+    upgrade: (params: {
+        targetVersion?: string;
+    }) => Promise<{
+        state: "already_latest" | "restart_scheduled" | "not_available";
+        currentVersion: string;
+        diskVersion: string | null;
+        targetVersion: string | null;
+    }>;
+    /** 从磁盘重载（`host.reload`：与改配置同一条生效路径） */
+    reload: (params: HostReloadParams) => Promise<HostReloadResult>;
+}
+/**
+ * 造出整张 handler 表。
+ *
+ * 同名方法不会重复：每个方法名只属于一个域，拼装处若出现重名，后一份会覆盖前一份
+ * （`handlers/index.test.ts` 里断言表里的方法名唯一且都在契约内）。
+ */
+export declare function createHandlers(deps: HandlerDeps): HandlerTable;

package/dist/handlers/index.js

@@ -0,0 +1,92 @@
+/**
+ * handler 表的唯一出口（architecture §3 / §6）。
+ *
+ * `WsHub` 只认一张表：方法名 → 实现。方法名的真相在 `wire/methods.ts`（`MethodMap`），
+ * 这里把每个有实现者的域拼起来交给接线层。
+ *
+ * 各域分文件放，是为了让「这一域要哪些持有者」写在它自己的 `deps` 接口上：接线层照着注入，
+ * 而不是把一个巨大的 `app` 对象塞进每个 handler 里。
+ *
+ * 组装方式仍是显式构造注入：`HostApp` 造好服务与运行时之后，把引用交进来，本模块不 new
+ * 任何东西、不读全局路径、不持有单例。
+ *
+ * 四件事在**接线层**而不是这张表里（`handlers/index.test.ts` 把这份名单钉住）：
+ *   - `host.hello` / `host.setLanguage`：语言与凭证都是连接状态（`net/WsHub`）；
+ *   - `asset.begin` / `asset.end`：上传要按连接分帧落盘（`net/UploadReceiver`）。
+ *
+ * 除这四条以外，契约里的每个方法都必须在这张表里 —— 否则客户端会拿到 `unsupported`，
+ * 而那是「这个宿主没有这个功能」的意思，不该用来掩盖「忘了接」。
+ */
+import { createAgentHandlers } from "./agentHandlers.js";
+import { createAssetHandlers } from "./assetHandlers.js";
+import { createCompletionHandlers } from "./completionHandlers.js";
+import { createConfigHandlers } from "./configHandlers.js";
+import { createConversationHandlers } from "./conversationHandlers.js";
+import { createHandoffHandlers } from "./handoffHandlers.js";
+import { createMessageHandlers } from "./messageHandlers.js";
+import { createModelHandlers } from "./modelHandlers.js";
+import { createNoticeHandlers } from "./noticeHandlers.js";
+import { createQuestionHandlers } from "./questionHandlers.js";
+import { createSearchHandlers } from "./searchHandlers.js";
+import { createHostHandlers } from "./hostHandlers.js";
+import { createWorkspaceHandlers } from "./workspaceHandlers.js";
+export { createCapabilities } from "./capabilities.js";
+/**
+ * 由接线层代管、因此不在 handler 表里的方法名。
+ *
+ * 这份名单是「表可以缺哪些」的唯一真相：验收用例按它判「契约里的每个方法要么在表里、
+ * 要么在这里」。往这里加一条就等于说「接线层自己实现了它」——`net/WsHub` 也确实在分发时
+ * 先处理这四个名字。
+ */
+export const BRIDGED_METHODS = [
+    "host.hello",
+    "host.setLanguage",
+    "asset.begin",
+    "asset.end",
+];
+/**
+ * 造出整张 handler 表。
+ *
+ * 同名方法不会重复：每个方法名只属于一个域，拼装处若出现重名，后一份会覆盖前一份
+ * （`handlers/index.test.ts` 里断言表里的方法名唯一且都在契约内）。
+ */
+export function createHandlers(deps) {
+    return {
+        ...createHostHandlers(deps),
+        ...createWorkspaceHandlers({
+            workspaces: deps.workspaces,
+            conversations: deps.conversations,
+            runner: deps.runner,
+            scopes: deps.scopes,
+            emit: deps.emit,
+            now: deps.now,
+        }),
+        ...createConversationHandlers({
+            conversations: deps.conversations,
+            messages: deps.messages,
+            runner: deps.runner,
+            readConfig: deps.readConfig,
+            // 状态栏助手块的名字与可用性（PRD F-I6）：只借用 `AgentService.describe` 这一个只读口
+            agents: deps.agents,
+            refreshThinkingPresets: deps.refreshThinkingPresets,
+            now: deps.now,
+            onTurnSettled: deps.onTurnSettled,
+            assertSendable: deps.assertSendable,
+            autoNameAfterTurn: deps.autoNameAfterTurn,
+            onHookError: deps.onHookError,
+            questionsFor: deps.questionsFor,
+            // 临时对话：一次调用跑一轮、不落库、不推流式事件（R1 / R49）
+            runTransient: async (params, language) => await deps.transient.run(params, language),
+        }),
+        ...createMessageHandlers(deps),
+        ...createSearchHandlers(deps),
+        ...createAssetHandlers({ assets: deps.assets }),
+        ...createConfigHandlers({ config: deps.config }),
+        ...createAgentHandlers({ agents: deps.agents }),
+        ...createModelHandlers({ models: deps.models }),
+        ...createCompletionHandlers({ completion: deps.completion }),
+        ...createNoticeHandlers({ notices: deps.notices }),
+        ...createQuestionHandlers({ questions: deps.questions }),
+        ...createHandoffHandlers({ handoff: deps.handoff }),
+    };
+}