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

package/dist/handlers/agentHandlers.js

@@ -0,0 +1,20 @@
+/**
+ * `agent.*` 的接线壳（F-B1…F-B7 / F-F5 / F-G3）。
+ *
+ * 与 `config.*` 同一套口径：入参直接交给服务，出参里的句子按这条连接的语言重渲染
+ * （D8）。业务判断在 `services/AgentService.ts`。
+ */
+import { localizeLocalizedTexts } from "./configHandlers.js";
+/** 造出 `agent.*` 的 handler 表 */
+export function createAgentHandlers(deps) {
+    return {
+        "agent.list": async (context) => localizeLocalizedTexts(await deps.agents.list(context.params), context.connection.language),
+        "agent.get": async (context) => localizeLocalizedTexts(await deps.agents.get(context.params), context.connection.language),
+        "agent.create": async (context) => localizeLocalizedTexts(await deps.agents.create(context.params), context.connection.language),
+        "agent.update": async (context) => localizeLocalizedTexts(await deps.agents.update(context.params), context.connection.language),
+        "agent.delete": async (context) => localizeLocalizedTexts(await deps.agents.delete(context.params), context.connection.language),
+        "agent.setModel": async (context) => localizeLocalizedTexts(await deps.agents.setModel(context.params), context.connection.language),
+        "agent.setThinking": async (context) => localizeLocalizedTexts(await deps.agents.setThinking(context.params), context.connection.language),
+        "agent.restoreFactory": async (context) => localizeLocalizedTexts(await deps.agents.restoreFactory(context.params), context.connection.language),
+    };
+}

package/dist/handlers/assetHandlers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `asset.*`：上传入口与取回（PRD D5 / F-H7 / F-H8）。
+ *
+ * `asset.begin` / `asset.end` 不在这张表里：它们长在 WebSocket 上（分片要直接写进 `assets/`
+ * 的临时文件、要能按连接清理），由接线层（`net/WsHub` + `net/UploadReceiver`）直接接管，
+ * 这里再注册一份就成了两处实现，客户端会看到两个不同的答案。
+ *
+ * `asset.get` 在这一格里：它不需要连接状态（不问「你是谁这条连接在做什么」），一条 WS 上的
+ * JSON 请求/响应就够 —— 内容走 base64 回包，因此不涉及二进制下行帧的关联问题。
+ *
+ * 这一域还有一件翻译工作留在这里：附件结局（`AttachmentOutcome`）里的句子是在素材层（不知道
+ * 收件人是谁）按默认语言渲染的，重渲染发生在接线层。
+ */
+import type { Language } from "../i18n/index.js";
+import type { HandlerTable } from "../net/index.js";
+import type { AssetService } from "../services/AssetService.js";
+import type { AttachmentOutcome } from "../wire/index.js";
+/** `asset.*` 的 handler 依赖 */
+export interface AssetHandlerDeps {
+    assets: AssetService;
+}
+/**
+ * `asset.*` 的 handler 表。
+ *
+ * 只有 `asset.get`：另外两个方法由接线层接管（见文件头），返回空表才是结论而不是占位。
+ */
+export declare function createAssetHandlers(deps: AssetHandlerDeps): HandlerTable;
+/** 一个附件结局的句子按这条连接的语言重渲染（码与参数不动，PRD D8） */
+export declare function localizeOutcome(outcome: AttachmentOutcome, language: Language): AttachmentOutcome;

package/dist/handlers/assetHandlers.js

@@ -0,0 +1,35 @@
+/**
+ * `asset.*`：上传入口与取回（PRD D5 / F-H7 / F-H8）。
+ *
+ * `asset.begin` / `asset.end` 不在这张表里：它们长在 WebSocket 上（分片要直接写进 `assets/`
+ * 的临时文件、要能按连接清理），由接线层（`net/WsHub` + `net/UploadReceiver`）直接接管，
+ * 这里再注册一份就成了两处实现，客户端会看到两个不同的答案。
+ *
+ * `asset.get` 在这一格里：它不需要连接状态（不问「你是谁这条连接在做什么」），一条 WS 上的
+ * JSON 请求/响应就够 —— 内容走 base64 回包，因此不涉及二进制下行帧的关联问题。
+ *
+ * 这一域还有一件翻译工作留在这里：附件结局（`AttachmentOutcome`）里的句子是在素材层（不知道
+ * 收件人是谁）按默认语言渲染的，重渲染发生在接线层。
+ */
+import { render } from "../i18n/index.js";
+/**
+ * `asset.*` 的 handler 表。
+ *
+ * 只有 `asset.get`：另外两个方法由接线层接管（见文件头），返回空表才是结论而不是占位。
+ */
+export function createAssetHandlers(deps) {
+    return {
+        // 按 id 取回内容：`assets` 是资源的唯一真相，历史里的 `__asset_id` 靠它重放
+        "asset.get": async (context) => await deps.assets.getAsset(context.params),
+    };
+}
+/** 一个附件结局的句子按这条连接的语言重渲染（码与参数不动，PRD D8） */
+export function localizeOutcome(outcome, language) {
+    if (outcome.problem === null)
+        return outcome;
+    const problem = {
+        ...outcome.problem,
+        message: render(language, outcome.problem.messageKey, outcome.problem.params),
+    };
+    return { ...outcome, problem };
+}

package/dist/handlers/capabilities.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 能力清单（PRD F-E5 / F-E6 / F-F9，裁定 R6）。
+ *
+ * 清单是「帮助页与指令菜单渲染用的那一份真相」，所以它必须与契约同步：每一项对应
+ * `MethodMap` 里的一个方法名，编号取 PRD §4 那一行的能力号（`wire/methods.ts` 里每个方法
+ * 的注释就写着自己的编号）。没有编号的方法用契约注释里记的那条决定编号（`workspace.*` 是
+ * `D9`/`D10`/`D11`：PRD §4 当初没给项目单列能力行），不另编一个。
+ *
+ * 三件事刻意分开：
+ *   - **标题与说明**：`LocalizedText`，按连接语言渲染（D8），文案键在 `i18n/`；
+ *   - **`blocking`**：执行期间会不会占住这段对话（F-E6 让界面显示「正在执行什么」）；
+ *   - **`destructive`**：有不可撤销的后果（F-F9 的二次确认）。
+ *
+ * 编号撞车的场合（几个方法服务同一条能力，例如 `config.saveEndpoint` / `config.deleteEndpoint`
+ * 都属于 F-F2）用 `<编号>#<动作>` 做 id：编号仍是 PRD 的那个，id 保持唯一，客户端可以按 id 存
+ * 展开状态。顺序与 `METHOD_NAMES` 一致，帮助页读起来就是「按域分组的办法清单」。
+ */
+import type { Language } from "../i18n/index.js";
+import type { CapabilityView } from "../wire/index.js";
+/**
+ * 造能力清单。
+ *
+ * 默认语言渲染一份：`host.hello` 与 `host.capabilities` 的出参都要能在不知道收件人语言时
+ * 先给出形状，客户端按自己的语言用 `messageKey` + `params` 重渲染（D8 的同一套口径）。
+ */
+export declare function createCapabilities(language?: Language): CapabilityView[];

package/dist/handlers/capabilities.js

@@ -0,0 +1,138 @@
+/**
+ * 能力清单（PRD F-E5 / F-E6 / F-F9，裁定 R6）。
+ *
+ * 清单是「帮助页与指令菜单渲染用的那一份真相」，所以它必须与契约同步：每一项对应
+ * `MethodMap` 里的一个方法名，编号取 PRD §4 那一行的能力号（`wire/methods.ts` 里每个方法
+ * 的注释就写着自己的编号）。没有编号的方法用契约注释里记的那条决定编号（`workspace.*` 是
+ * `D9`/`D10`/`D11`：PRD §4 当初没给项目单列能力行），不另编一个。
+ *
+ * 三件事刻意分开：
+ *   - **标题与说明**：`LocalizedText`，按连接语言渲染（D8），文案键在 `i18n/`；
+ *   - **`blocking`**：执行期间会不会占住这段对话（F-E6 让界面显示「正在执行什么」）；
+ *   - **`destructive`**：有不可撤销的后果（F-F9 的二次确认）。
+ *
+ * 编号撞车的场合（几个方法服务同一条能力，例如 `config.saveEndpoint` / `config.deleteEndpoint`
+ * 都属于 F-F2）用 `<编号>#<动作>` 做 id：编号仍是 PRD 的那个，id 保持唯一，客户端可以按 id 存
+ * 展开状态。顺序与 `METHOD_NAMES` 一致，帮助页读起来就是「按域分组的办法清单」。
+ */
+import { DEFAULT_LANGUAGE, render } from "../i18n/index.js";
+import { methodDomain } from "../wire/index.js";
+/**
+ * 清单本体：**每个方法一条**，且与 `METHOD_NAMES` 一一对应（用例会钉住这条）。
+ *
+ * `blocking` 只标「跑起来时这段对话不能发下一条」的那几个：一轮对话、交接回合、
+ * 临时对话（它借的 Scope 与项目共用，跑的时候同样不能被打断）。
+ * `destructive` 只标「做下去就回不来」的那几个：删项目 / 删对话 / 撤回 / 删端点 /
+ * 删助手 / 删模型（含图片模型）/ 删 MCP 条目 / 恢复出厂。清通知不算：它清的是
+ * 界面上的一条提示，为它弹二次确认反而是打扰。
+ *
+ * 两样东西刻意不在这份清单里（裁定 2026-11-13）：
+ *   - `host.usage`：「按项目 / 整机」的用量聚合没有任何客户端消费，F-I5 的落点在
+ *     `conversation.state` 的 `usage`；
+ *   - `credential.*`：凭据由宿主自己管理（`agents-host token create|list|revoke`），
+ *     客户端只有「连接管理 + 记住密码」，那里没有可渲染的能力。
+ */
+const FACTS = [
+    { method: "host.hello", prd: "F-A1", blocking: false, destructive: false },
+    { method: "host.version", prd: "F-E3", blocking: false, destructive: false },
+    { method: "host.upgrade", prd: "F-E3", blocking: false, destructive: false },
+    { method: "host.shutdown", prd: "F-E1", blocking: false, destructive: false },
+    { method: "host.capabilities", prd: "F-E5", blocking: false, destructive: false },
+    { method: "host.reload", prd: "F-E1", blocking: false, destructive: false },
+    { method: "host.setLanguage", prd: "F-E4", blocking: false, destructive: false },
+    { method: "workspace.list", prd: "D9", blocking: false, destructive: false },
+    { method: "workspace.create", prd: "D10", blocking: false, destructive: false },
+    { method: "workspace.get", prd: "D9", blocking: false, destructive: false },
+    { method: "workspace.rename", prd: "D9", blocking: false, destructive: false },
+    { method: "workspace.remove", prd: "D11", blocking: false, destructive: true },
+    { method: "conversation.list", prd: "F-C5", blocking: false, destructive: false },
+    { method: "conversation.create", prd: "F-C7", blocking: false, destructive: false },
+    { method: "conversation.get", prd: "F-A6", blocking: false, destructive: false },
+    { method: "conversation.state", prd: "F-I3", blocking: false, destructive: false },
+    { method: "conversation.rename", prd: "F-C3", blocking: false, destructive: false },
+    { method: "conversation.pin", prd: "F-C5", blocking: false, destructive: false },
+    { method: "conversation.delete", prd: "F-C10", blocking: false, destructive: true },
+    { method: "conversation.send", prd: "F-C2", blocking: true, destructive: false },
+    { method: "conversation.abort", prd: "F-E1", blocking: false, destructive: false },
+    { method: "conversation.revert", prd: "F-C8", blocking: false, destructive: true },
+    { method: "conversation.setModel", prd: "F-B4", blocking: false, destructive: false },
+    { method: "conversation.setThinking", prd: "F-B6", blocking: false, destructive: false },
+    { method: "conversation.transient", prd: "F-A2", blocking: true, destructive: false },
+    { method: "message.list", prd: "F-I7", blocking: false, destructive: false },
+    { method: "question.list", prd: "F-I9", blocking: false, destructive: false },
+    { method: "question.answer", prd: "F-I9", blocking: false, destructive: false },
+    { method: "notice.list", prd: "F-I8", blocking: false, destructive: false },
+    { method: "notice.dismiss", prd: "F-I8", blocking: false, destructive: false },
+    { method: "notice.clear", prd: "F-I8", blocking: false, destructive: false },
+    { method: "config.get", prd: "F-F1", blocking: false, destructive: false },
+    { method: "config.patch", prd: "F-F1", blocking: false, destructive: false },
+    { method: "config.setDefaults", prd: "F-F7", blocking: false, destructive: false },
+    { method: "config.getDiscovery", prd: "F-G1", blocking: false, destructive: false },
+    { method: "config.saveMcp", prd: "F-F6", blocking: false, destructive: false },
+    { method: "config.deleteMcp", prd: "F-G1", blocking: false, destructive: true },
+    { method: "config.saveEndpoint", prd: "F-F2", blocking: false, destructive: false },
+    { method: "config.deleteEndpoint", prd: "F-F2", blocking: false, destructive: true },
+    { method: "agent.list", prd: "F-B2", blocking: false, destructive: false },
+    { method: "agent.get", prd: "F-B2", blocking: false, destructive: false },
+    { method: "agent.create", prd: "F-B2", blocking: false, destructive: false },
+    { method: "agent.update", prd: "F-B2", blocking: false, destructive: false },
+    { method: "agent.delete", prd: "F-F5", blocking: false, destructive: true },
+    { method: "agent.setModel", prd: "F-B4", blocking: false, destructive: false },
+    { method: "agent.setThinking", prd: "F-B6", blocking: false, destructive: false },
+    { method: "agent.restoreFactory", prd: "F-F5", blocking: false, destructive: true },
+    { method: "model.list", prd: "F-F3", blocking: false, destructive: false },
+    { method: "model.listImages", prd: "F-F4", blocking: false, destructive: false },
+    { method: "model.create", prd: "F-F3", blocking: false, destructive: false },
+    { method: "model.update", prd: "F-F3", blocking: false, destructive: false },
+    { method: "model.delete", prd: "F-F3", blocking: false, destructive: true },
+    { method: "model.restoreFactory", prd: "F-F3", blocking: false, destructive: true },
+    { method: "model.saveImage", prd: "F-F4", blocking: false, destructive: false },
+    { method: "model.deleteImage", prd: "F-F4", blocking: false, destructive: true },
+    { method: "asset.begin", prd: "F-H8", blocking: false, destructive: false },
+    { method: "asset.end", prd: "F-H8", blocking: false, destructive: false },
+    { method: "asset.get", prd: "F-H7", blocking: false, destructive: false },
+    { method: "completion.files", prd: "F-H5", blocking: false, destructive: false },
+    { method: "handoff.start", prd: "F-D5", blocking: true, destructive: false },
+    { method: "handoff.listDocuments", prd: "F-D6", blocking: false, destructive: false },
+    { method: "search.conversations", prd: "F-C6", blocking: false, destructive: false },
+    { method: "search.messages", prd: "F-C6", blocking: false, destructive: false },
+];
+/** 标题的文案键（`capability.<方法名>`） */
+function titleKey(method) {
+    return `capability.${method}`;
+}
+/** 说明的文案键（`capability.<方法名>.detail`） */
+function detailKey(method) {
+    return `capability.${method}.detail`;
+}
+/** 一句话：码 + 参数 + 按给定语言渲染的句子（存码不存句子，D8） */
+function text(key, language) {
+    return { code: key, messageKey: key, params: {}, message: render(language, key) };
+}
+/** 动作名（`conversation.send` → `send`），编号撞车时用来给 id 去重 */
+function actionOf(method) {
+    return method.slice(method.indexOf(".") + 1);
+}
+/**
+ * 造能力清单。
+ *
+ * 默认语言渲染一份：`host.hello` 与 `host.capabilities` 的出参都要能在不知道收件人语言时
+ * 先给出形状，客户端按自己的语言用 `messageKey` + `params` 重渲染（D8 的同一套口径）。
+ */
+export function createCapabilities(language = DEFAULT_LANGUAGE) {
+    const used = new Set();
+    return FACTS.map((fact) => {
+        // 同一个编号下的第二个及以后的方法：`<编号>#<动作>`
+        const id = used.has(fact.prd) ? `${fact.prd}#${actionOf(fact.method)}` : fact.prd;
+        used.add(fact.prd);
+        return {
+            id,
+            domain: methodDomain(fact.method),
+            title: text(titleKey(fact.method), language),
+            description: text(detailKey(fact.method), language),
+            method: fact.method,
+            blocking: fact.blocking,
+            destructive: fact.destructive,
+        };
+    });
+}

package/dist/handlers/completionHandlers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `completion.*` 的接线壳（F-H5 / D7）：`@` 补全的数据来源。
+ *
+ * 业务判断在 `services/CompletionService.ts`；这里只转发 + 按连接语言重渲染「未就绪要说话」
+ * 的那句说明（D8）。
+ */
+import type { HandlerTable } from "../net/WsHub.js";
+import type { CompletionService } from "../services/CompletionService.js";
+/** 本文件负责的方法名 */
+export type CompletionHandlerName = "completion.files";
+/** 本文件产出的 handler 表片段 */
+export type CompletionHandlers = Pick<HandlerTable, CompletionHandlerName>;
+/** 接线壳的依赖 */
+export interface CompletionHandlerDeps {
+    completion: CompletionService;
+}
+/** 造出 `completion.*` 的 handler 表 */
+export declare function createCompletionHandlers(deps: CompletionHandlerDeps): CompletionHandlers;

package/dist/handlers/completionHandlers.js

@@ -0,0 +1,13 @@
+/**
+ * `completion.*` 的接线壳（F-H5 / D7）：`@` 补全的数据来源。
+ *
+ * 业务判断在 `services/CompletionService.ts`；这里只转发 + 按连接语言重渲染「未就绪要说话」
+ * 的那句说明（D8）。
+ */
+import { localizeLocalizedTexts } from "./configHandlers.js";
+/** 造出 `completion.*` 的 handler 表 */
+export function createCompletionHandlers(deps) {
+    return {
+        "completion.files": async (context) => localizeLocalizedTexts(await deps.completion.files(context.params), context.connection.language),
+    };
+}

package/dist/handlers/configHandlers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `config.*` 的接线壳（F-F1 / F-F2 / F-F6 / F-F7 / F-E2 / F-A8）。
+ *
+ * 这一层只做两件事：把入参交给服务，把出参里那些「已经按默认语言渲染好的句子」按**这条连接**
+ * 的语言重渲染一次（PRD D8：语言挂在连接上，服务层存的是码 + 参数）。
+ *
+ * 业务判断都在 `services/ConfigService.ts`；这里没有一条分支是在决定「该怎么算」。
+ */
+import { type Language } from "../i18n/index.js";
+import type { HandlerTable, MethodHandler } from "../net/WsHub.js";
+import type { ConfigService } from "../services/ConfigService.js";
+/** 本文件负责的方法名（其余域各有各的文件） */
+export type ConfigHandlerName = "config.get" | "config.patch" | "config.setDefaults" | "config.getDiscovery" | "config.saveMcp" | "config.deleteMcp" | "config.saveEndpoint" | "config.deleteEndpoint";
+/** 本文件产出的 handler 表片段（单根把它摊进总表） */
+export type ConfigHandlers = Pick<HandlerTable, ConfigHandlerName>;
+/** 接线壳的依赖 */
+export interface ConfigHandlerDeps {
+    config: ConfigService;
+}
+/**
+ * 把一段结构化结果里所有 `LocalizedText` 的句子换成目标语言。
+ *
+ * 判定按形状（`code` + `messageKey` + `params` + `message`）而不是认某个类：这些事实要能穿过
+ * JSON-RPC 边界，形状本身就是契约（`wire/states.ts` 的 `LocalizedText`）。认不出来的原样留着
+ * —— 渲染不出来时保留原句子比丢字段好。
+ */
+export declare function localizeLocalizedTexts<T>(value: T, language: Language): T;
+/** 造出 `config.*` 的 handler 表 */
+export declare function createConfigHandlers(deps: ConfigHandlerDeps): ConfigHandlers;
+/** 单个方法也导出，便于用例直接调（不必造整张表） */
+export type ConfigMethodHandler<M extends ConfigHandlerName> = MethodHandler<M>;

package/dist/handlers/configHandlers.js

@@ -0,0 +1,59 @@
+/**
+ * `config.*` 的接线壳（F-F1 / F-F2 / F-F6 / F-F7 / F-E2 / F-A8）。
+ *
+ * 这一层只做两件事：把入参交给服务，把出参里那些「已经按默认语言渲染好的句子」按**这条连接**
+ * 的语言重渲染一次（PRD D8：语言挂在连接上，服务层存的是码 + 参数）。
+ *
+ * 业务判断都在 `services/ConfigService.ts`；这里没有一条分支是在决定「该怎么算」。
+ */
+import { hasMessage, render } from "../i18n/index.js";
+/**
+ * 把一段结构化结果里所有 `LocalizedText` 的句子换成目标语言。
+ *
+ * 判定按形状（`code` + `messageKey` + `params` + `message`）而不是认某个类：这些事实要能穿过
+ * JSON-RPC 边界，形状本身就是契约（`wire/states.ts` 的 `LocalizedText`）。认不出来的原样留着
+ * —— 渲染不出来时保留原句子比丢字段好。
+ */
+export function localizeLocalizedTexts(value, language) {
+    return walk(value, language, 0);
+}
+function walk(value, language, depth) {
+    if (depth > 12)
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => walk(item, language, depth + 1));
+    if (typeof value !== "object" || value === null)
+        return value;
+    const record = value;
+    if (isLocalizedText(record) && hasMessage(record.messageKey)) {
+        const message = render(language, record.messageKey, record.params);
+        const detail = "detail" in record ? { detail: walk(record.detail, language, depth + 1) } : {};
+        return { ...record, message, ...detail };
+    }
+    const result = {};
+    for (const [key, item] of Object.entries(record)) {
+        result[key] = walk(item, language, depth + 1);
+    }
+    return result;
+}
+function isLocalizedText(record) {
+    return (typeof record.code === "string" &&
+        typeof record.messageKey === "string" &&
+        typeof record.message === "string" &&
+        typeof record.params === "object" &&
+        record.params !== null &&
+        !Array.isArray(record.params));
+}
+/** 造出 `config.*` 的 handler 表 */
+export function createConfigHandlers(deps) {
+    return {
+        "config.get": async (context) => localizeLocalizedTexts(await deps.config.get(context.params), context.connection.language),
+        "config.patch": async (context) => localizeLocalizedTexts(await deps.config.patch(context.params), context.connection.language),
+        "config.setDefaults": async (context) => localizeLocalizedTexts(await deps.config.setDefaults(context.params), context.connection.language),
+        "config.getDiscovery": async (context) => localizeLocalizedTexts(await deps.config.getDiscovery(context.params), context.connection.language),
+        "config.saveMcp": async (context) => localizeLocalizedTexts(await deps.config.saveMcp(context.params), context.connection.language),
+        "config.deleteMcp": async (context) => localizeLocalizedTexts(await deps.config.deleteMcp(context.params), context.connection.language),
+        "config.saveEndpoint": async (context) => localizeLocalizedTexts(await deps.config.saveEndpoint(context.params), context.connection.language),
+        "config.deleteEndpoint": async (context) => localizeLocalizedTexts(await deps.config.deleteEndpoint(context.params), context.connection.language),
+    };
+}

package/dist/handlers/conversationHandlers.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `conversation.*`：一段对话的身份、历史与一轮的运行。
+ *
+ * 这里只做「参数 → 交给服务/运行时 → 把结果翻译成契约形状」。业务判断在
+ * `ConversationService` 与 `ChatRunner` 里：比如「忙就拒」在 `RunRegistry`、
+ * 「模型解析不出来」在服务层，本文件不重新判断一遍。
+ *
+ * 唯一在接线层做的拼装是 `conversation.state` 的现场快照：它要把三处事实合起来
+ * （服务层给的视图、运行时给的这一轮、库里消息求和的用量），而这三样分别属于三个持有者，
+ * 只有接线层同时看得见它们。
+ *
+ * 一段对话的三处跨界钩子也在这里接（它们分属三个服务，契约里的位置却是同一对方法）：
+ *   - `conversation.send` 之前问一句「有挡着的问题吗」（D23）；
+ *   - 结算之后起一次自动命名（D2，幂等）；
+ *   - `conversation.transient` 走不落库的那条执行路径（R1 / R49）。
+ */
+import type { AgentNS } from "@ai-zen/agents-core";
+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 } from "../runtime/index.js";
+import type { AgentDescription } from "../services/AgentService.js";
+import type { ConversationService } from "../services/ConversationService.js";
+import type { MessageService } from "../services/MessageService.js";
+import type { ContextState, ConversationTransientParams, ConversationTransientResult, ConversationView, QuestionView, RunState, StatusBlock, UsageSnapshot } from "../wire/index.js";
+/** `conversation.*` 的实现要的持有者 */
+export interface ConversationHandlerDeps {
+    conversations: ConversationService;
+    messages: MessageService;
+    /** 一轮的执行者（受理、现场、中止、忘掉） */
+    runner: ChatRunner;
+    /** 挂在这段对话上的问题（`conversation.state` 现场快照的一部分，D22；不注入时为空） */
+    questionsFor?: (conversationId: string) => Promise<QuestionView[]>;
+    /** 读配置：上下文阈值跟着模型走（PRD F-D1） */
+    readConfig: () => Promise<AppConfig>;
+    /**
+     * 读助手定义那一层的最小事实（名字 + 能不能用，PRD F-I6 的状态栏助手块）。
+     *
+     * 只用到 `describe`（`AgentService.describe` 是唯一实现者）：接线层不碰定义文件，
+     * 也不把 `AgentService` 整个搬进来。不注入时助手块的名字与可用性都是 `null`。
+     */
+    agents?: {
+        describe: (agentId: string) => Promise<AgentDescription | null>;
+    };
+    /** 刷新思考档位表快照（`setThinking` 之前调一次：改完读回的参数要用当前表） */
+    refreshThinkingPresets: () => Promise<void>;
+    /** 时钟（ISO 8601 时间戳） */
+    now: () => string;
+    /** 一轮结算之后的通知点：单根据此重算退出判据 */
+    onTurnSettled: () => void;
+    /** 有挡着的问题就拒绝（`QuestionService.assertSendable`，D23）；不注入时不检查 */
+    assertSendable?: (conversationId: string) => Promise<void>;
+    /** 一轮结算之后起一次自动命名（`AutoNaming.afterTurn`，D2：幂等，可无条件调） */
+    autoNameAfterTurn?: (conversationId: string, language: Language) => Promise<void>;
+    /**
+     * 结算后钩子的失败去处（命名没跑成不影响这一轮，但要让组装层看得见）。
+     *
+     * 不注入时静默：钩子是「顺手做的事」，它的失败不能反过来把已经结算的一轮弄成失败。
+     */
+    onHookError?: (error: unknown, hook: string) => void;
+    /** 临时对话的执行者（`TransientRunner`，D3 / R49）；不注入时这个方法回 `unsupported` */
+    runTransient?: (params: ConversationTransientParams, language: Language) => Promise<ConversationTransientResult>;
+}
+/**
+ * 注册 `conversation.*`。
+ *
+ * `conversation.transient`（临时对话，PRD D3）注册的前提是注入了 `runTransient`：
+ * 不注入时这个方法仍然落到接线层的 `unsupported`（裁定 R11）。
+ */
+export declare function createConversationHandlers(deps: ConversationHandlerDeps): HandlerTable;
+/** 造状态栏块要的那几处事（每一项都已经在别处算好了，这里只负责装箱） */
+export interface StatusBlockInput {
+    /** 服务层给的对话视图（身份、模型、思考档、目录事实） */
+    conversation: ConversationView;
+    /**
+     * 助手块的两条事实（名字 / 能不能用），由 {@link conversationStateOf} 从助手定义那一层读来。
+     * 拿不到时两格都是 `null`（助手已被删、或定义文件读不出来）。
+     */
+    agent: {
+        name: string | null;
+        available: boolean | null;
+    };
+    /** 这一轮的快照（六态、工具、子 Agent、本轮用量） */
+    run: RunState;
+    /** 上下文占用与两条阈值 */
+    context: ContextState;
+    /** 累计用量 */
+    usage: UsageSnapshot;
+    /** 收件人的语言（块的标签是给人看的一句话） */
+    language: Language;
+}
+/**
+ * 按 `STATUS_BLOCK_IDS` 的顺序拼装状态栏的块（PRD F-I6 / 裁定 R65）。
+ *
+ * 这里**不产生新事实**：每一块装的都是别处已经算好的那份 —— 对话视图里的身份 / 模型 / 思考档 /
+ * 目录、`conversation.state` 里的上下文与用量、以及这一轮快照里的六态与子 Agent。工具块只取
+ * `awaiting_tools` 态里还在跑的那几个（并行时有几个列几个，正是 L8 要的语义）；其余态下没有
+ * 工具在跑，列表就是空的。
+ *
+ * 助手块的 `name` / `available` 由调用方（`conversationStateOf`）先从助手定义那一层读好传进来
+ * （`input.agent`）：本函数保持同步纯函数，不在这里做 IO。
+ */
+export declare function statusBlocksOf(input: StatusBlockInput): StatusBlock[];
+/** 空闲的现场：没有在跑的一轮，但历史用量还在 */
+export declare function idleRunState(conversationId: string, usage: UsageSnapshot): RunState;
+/**
+ * 一批消息的用量快照。
+ *
+ * `total` 与 `subAgent` 用 core 的口径求和（含子 Agent，与计费同口径）；`turn` 在「没有一轮
+ * 在跑」时是零值（没有这一轮这件事，就是零），速率同理。
+ */
+export declare function usageOfMessages(messages: readonly AgentNS.Message[], now: string): UsageSnapshot;
+/**
+ * 上下文占用：最近一次请求的用量 + 这个模型的两条阈值（PRD F-D1 / D27）。
+ *
+ * 阈值跟着模型走；模型在配置里被删掉时两条线都是 0（「没有阈值」而不是「阈值为零就超了」）。
+ */
+export declare function contextOf(messages: readonly AgentNS.Message[], model: AppConfig["models"][number] | undefined): ContextState;