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

package/dist/storage/migrations.js

@@ -0,0 +1,207 @@
+/**
+ * 建表与迁移。
+ *
+ * `meta.schemaVersion` 是唯一的版本真相：`migrate` 从当前版本往上逐级执行，
+ * 每一级的所有语句 + 版本号推进都在**同一个事务**里 —— 结构改了一半而版本号没动，
+ * 或者版本号动了而结构没改，都会让下次启动跑在错误的假设上。
+ *
+ * 不识别任何旧数据、不做数据搬迁（PRD L1：新库从空开始）。
+ */
+import { MetaRepository } from "./MetaRepository.js";
+/**
+ * 迁移列表。眼下只有 v1：这套表结构还没随版本发出去，PM 在 W1 之后的裁定（cwd 唯一、
+ * 身份列非空）直接落进了 v1 的建表语句。再往后改结构时追加新条目 —— 已经装上升过级的库
+ * 不会重跑旧条目，改旧条目会让两台机器的表结构悄悄分叉。
+ */
+export const MIGRATIONS = [
+    {
+        version: 1,
+        statements: [
+            // meta：单行表（id 固定为 1），存 schemaVersion 与建库时间
+            `CREATE TABLE IF NOT EXISTS meta (
+         id            INTEGER PRIMARY KEY CHECK (id = 1),
+         schemaVersion INTEGER NOT NULL,
+         createdAt     INTEGER NOT NULL
+       )`,
+            // workspaces：一个工作目录登记一次。cwd 不可变（PRD D9），所以没有更新的入口。
+            // cwd 唯一：同一个目录登记两次会出现两个 Scope 抢同一目录；唯一约束自带的索引
+            // 就是「这个 cwd 登记过没有」（PRD D10 的问一次）的查询路径，不再另建普通索引
+            `CREATE TABLE IF NOT EXISTS workspaces (
+         id        TEXT PRIMARY KEY,
+         name      TEXT NOT NULL,
+         cwd       TEXT NOT NULL UNIQUE,
+         createdAt INTEGER NOT NULL
+       )`,
+            // conversations：项目 / 助手创建时定死，模型与思考档位是这段会话自己的（可以改）。
+            // agentId / modelId 不允许为空 —— 解析不出助手或模型时在创建处就失败，不落半成品行。
+            // nameIsAuto 记住「这个名字是不是自动起的」（R35）：创建时的原名算自动，用户改名置 0，
+            // 自动命名写入新名并置 1。
+            // thinkingLevel 存档位名（可空）：空 = 跟随助手定义上的那份参数；非空 = 这一段会话选的档位，
+            // 装配 agent 时按该模型的思考策略表展开成参数补丁。
+            `CREATE TABLE IF NOT EXISTS conversations (
+         id            TEXT PRIMARY KEY,
+         workspaceId   TEXT NOT NULL REFERENCES workspaces (id) ON DELETE CASCADE,
+         name          TEXT NOT NULL,
+         nameIsAuto    INTEGER NOT NULL DEFAULT 1,
+         pinned        INTEGER NOT NULL DEFAULT 0,
+         agentId       TEXT NOT NULL,
+         modelId       TEXT NOT NULL,
+         thinkingLevel TEXT,
+         createdAt     INTEGER NOT NULL,
+         updatedAt     INTEGER NOT NULL
+       )`,
+            // 侧栏排序 = 置顶优先、再按创建时间倒序（PRD D13）；活动/改名不影响顺序
+            `CREATE INDEX IF NOT EXISTS idx_conversations_workspace
+         ON conversations (workspaceId, pinned DESC, createdAt DESC)`,
+            // messages：边流边写，同一条消息按 id 反复覆盖（PRD D15）。
+            // parentToolCallId 记录子 Agent 消息挂在哪次工具调用上（R37），顶层消息为空。
+            `CREATE TABLE IF NOT EXISTS messages (
+         id               TEXT PRIMARY KEY,
+         conversationId   TEXT NOT NULL REFERENCES conversations (id) ON DELETE CASCADE,
+         seq              INTEGER NOT NULL,
+         role             TEXT NOT NULL,
+         status           TEXT NOT NULL,
+         omit             INTEGER NOT NULL DEFAULT 0,
+         content          TEXT NOT NULL DEFAULT '',
+         data             TEXT,
+         searchText       TEXT NOT NULL DEFAULT '',
+         parentToolCallId TEXT,
+         createdAt        INTEGER NOT NULL,
+         updatedAt        INTEGER NOT NULL,
+         UNIQUE (conversationId, seq)
+       )`,
+            // 按对话顺序读取，以及 `after=<消息 id>` 定位
+            `CREATE INDEX IF NOT EXISTS idx_messages_conversation_seq
+         ON messages (conversationId, seq)`,
+            // 按父工具调用取子 Agent 的消息（R37 的读取路径）；NULL 行不进索引，顶层消息不受影响
+            `CREATE INDEX IF NOT EXISTS idx_messages_parent_tool_call
+         ON messages (parentToolCallId)`,
+            // assets：二进制素材的唯一真相（PRD L2 / F-H8）—— 文件在 assets/ 下，这一行记的是引用、
+            // 大小、类型、内容摘要与像素尺寸。
+            // 去重是**全局**的：sha256 唯一，同一份字节在整台机器上只有一行、一份磁盘。所以这张表
+            // 不再记「属于哪段对话 / 哪条消息」：归属在 conversation_assets 里，一张图贴到两个项目
+            // 就是一行素材 + 两行关系。
+            // width / height 可空：落定时按文件头解（PNG / JPEG），解不出来就是 NULL。
+            `CREATE TABLE IF NOT EXISTS assets (
+         id        TEXT PRIMARY KEY,
+         name      TEXT,
+         path      TEXT NOT NULL,
+         mime      TEXT NOT NULL,
+         bytes     INTEGER NOT NULL,
+         sha256    TEXT NOT NULL UNIQUE,
+         width     INTEGER,
+         height    INTEGER,
+         createdAt INTEGER NOT NULL
+       )`,
+            // conversation_assets：谁引用了哪份素材（消息 × 素材的关系行）。
+            // 写入时机是消息落库那一刻（扫 content 里的 `__asset_id`，同一 message+asset 一行）；
+            // 撤回 / 删对话 / 删消息都由外键级联删掉关系行，不需要谁去减计数。
+            // assetId 用 RESTRICT：还有人引用时物理删不掉素材行（护栏），真正的删除条件由
+            // 「COUNT(*) = 0」判定（见 AssetRepository.deleteIfUnreferenced）。
+            // 「几张会话引用了它」= COUNT(DISTINCT conversationId)，走 idx_conversation_assets_asset。
+            `CREATE TABLE IF NOT EXISTS conversation_assets (
+         conversationId TEXT NOT NULL REFERENCES conversations (id) ON DELETE CASCADE,
+         messageId      TEXT NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
+         assetId        TEXT NOT NULL REFERENCES assets (id) ON DELETE RESTRICT,
+         createdAt      INTEGER NOT NULL,
+         UNIQUE (messageId, assetId)
+       )`,
+            `CREATE INDEX IF NOT EXISTS idx_conversation_assets_asset ON conversation_assets (assetId)`,
+            `CREATE INDEX IF NOT EXISTS idx_conversation_assets_conversation
+         ON conversation_assets (conversationId)`,
+            // asset_vendor_files：厂商侧文件 id 的缓存（端点维度）。
+            // 它**不是**真相：删光之后从 assets 重建即可（下次发送时重新上传一遍），所以这里只记
+            // 「哪个素材在哪个端点上对应哪个 file_id」；素材没了就跟着走。
+            `CREATE TABLE IF NOT EXISTS asset_vendor_files (
+         assetId      TEXT NOT NULL REFERENCES assets (id) ON DELETE CASCADE,
+         endpointId   TEXT NOT NULL,
+         vendorFileId TEXT NOT NULL,
+         createdAt    INTEGER NOT NULL,
+         UNIQUE (assetId, endpointId)
+       )`,
+            // 缓存行的两种查法靠 UNIQUE (assetId, endpointId)：
+            // 「这个端点上有没有」与「别的端点上有没有」都走这条（都是 assetId 前缀查询）
+            // notices：持久化，durationMs 为 null 表示永久（PRD L3）。
+            // conversationId 是「这条通知与哪段对话有关」的真值（可空 = 全局通知）：按对话过滤、
+            // 按对话清都走这一列；对话没了它也就没有意义，所以跟着级联删除。
+            `CREATE TABLE IF NOT EXISTS notices (
+         id             TEXT PRIMARY KEY,
+         level          TEXT NOT NULL,
+         code           TEXT NOT NULL,
+         params         TEXT,
+         durationMs     INTEGER,
+         conversationId TEXT REFERENCES conversations (id) ON DELETE CASCADE,
+         createdAt      INTEGER NOT NULL
+       )`,
+            `CREATE INDEX IF NOT EXISTS idx_notices_createdAt ON notices (createdAt)`,
+            `CREATE INDEX IF NOT EXISTS idx_notices_conversation ON notices (conversationId)`,
+            // questions：有状态、可持久化、多端共享（PRD D22 / F-I9）
+            `CREATE TABLE IF NOT EXISTS questions (
+         id             TEXT PRIMARY KEY,
+         conversationId TEXT NOT NULL REFERENCES conversations (id) ON DELETE CASCADE,
+         kind           TEXT NOT NULL,
+         payload        TEXT NOT NULL,
+         state          TEXT NOT NULL,
+         answer         TEXT,
+         createdAt      INTEGER NOT NULL,
+         updatedAt      INTEGER NOT NULL,
+         answeredAt     INTEGER
+       )`,
+            `CREATE INDEX IF NOT EXISTS idx_questions_conversation
+         ON questions (conversationId, createdAt)`,
+            // credentials：只存 sha256 摘要，明文不在库里（PRD L11：多串、带备注、可单独吊销）
+            `CREATE TABLE IF NOT EXISTS credentials (
+         id        TEXT PRIMARY KEY,
+         note      TEXT NOT NULL DEFAULT '',
+         hash      TEXT NOT NULL,
+         createdAt INTEGER NOT NULL,
+         revokedAt INTEGER
+       )`,
+            `CREATE UNIQUE INDEX IF NOT EXISTS idx_credentials_hash ON credentials (hash)`,
+            // 全文检索：外部内容表挂在 messages 上，只索引 searchText（正文纯文本，不含 JSON 键名）。
+            // tokenize='trigram'：默认的 unicode61 会把整段中文当成一个 token，那样中文搜索永远
+            // 命中不了；trigram 按三字符切分，中文子串才搜得到（代价是查询词至少 3 个字符，
+            // 少于 3 个字符的查询在仓储里退化到 LIKE，见 MessageRepository.search）
+            `CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5 (
+         searchText,
+         content='messages',
+         content_rowid='rowid',
+         tokenize='trigram'
+       )`,
+            // 用触发器同步索引：写路径只有一条（都走 messages 表），不存在「仓储忘了同步」的情况
+            `CREATE TRIGGER IF NOT EXISTS messages_fts_after_insert AFTER INSERT ON messages BEGIN
+         INSERT INTO messages_fts (rowid, searchText) VALUES (new.rowid, new.searchText);
+       END`,
+            `CREATE TRIGGER IF NOT EXISTS messages_fts_after_delete AFTER DELETE ON messages BEGIN
+         INSERT INTO messages_fts (messages_fts, rowid, searchText)
+           VALUES ('delete', old.rowid, old.searchText);
+       END`,
+            `CREATE TRIGGER IF NOT EXISTS messages_fts_after_update AFTER UPDATE OF searchText ON messages BEGIN
+         INSERT INTO messages_fts (messages_fts, rowid, searchText)
+           VALUES ('delete', old.rowid, old.searchText);
+         INSERT INTO messages_fts (rowid, searchText) VALUES (new.rowid, new.searchText);
+       END`,
+        ],
+    },
+];
+/**
+ * 把库升到最新版本。重复调用是幂等的：已经跑过的版本会跳过，不会再执行一遍语句。
+ */
+export async function migrate(db) {
+    const meta = new MetaRepository(db);
+    let current = await meta.getSchemaVersion();
+    const now = Date.now();
+    for (const migration of MIGRATIONS) {
+        if (migration.version <= current)
+            continue;
+        const target = migration.version;
+        await db.tx((tx) => {
+            for (const statement of migration.statements)
+                tx.run(statement);
+            // 版本号与结构改动同一次事务提交，两者不会分叉
+            tx.run(`INSERT INTO meta (id, schemaVersion, createdAt) VALUES (1, ?, ?)
+         ON CONFLICT (id) DO UPDATE SET schemaVersion = excluded.schemaVersion`, [target, now]);
+        });
+        current = target;
+    }
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,298 @@
+/**
+ * 存储层的行类型与入参类型。
+ *
+ * 约定：
+ * - 列名与字段名都是 camelCase（SQLite 的列名并不强制风格，这里让「行类型 = 列名」，
+ *   读写两侧不用再维护一张映射表）。
+ * - 所有时间戳都是 `Date.now()` 的毫秒数，列类型 INTEGER（见各表注释）。
+ * - 带 `Row` 后缀的是**数据库原样行**（JSON 列还是字符串），不带后缀的是仓储解好的对象。
+ * - 消息正文直接用 core 的 `AgentNS.MessageContent`（R21 / R30）：列里存的就是它的 JSON，
+ *   仓储反序列化后就是同一个形状，服务层与运行时不必在两种形状之间翻译。
+ * - `role` / `status` 仍以字符串存取（取值与 `AgentNS.Role` / `AgentNS.MessageStatus` 一致），
+ *   收敛成 core 的枚举发生在服务层。
+ */
+import type { AgentNS } from "@ai-zen/agents-core";
+/** 消息角色，取值与 core 的 `AgentNS.Role` 对齐 */
+export type MessageRole = "system" | "user" | "assistant" | "tool" | "function" | "unknown";
+/** 消息状态，取值与 core 的 `AgentNS.MessageStatus` 对齐 */
+export type MessageStatus = "pending" | "writing" | "completed" | "error" | "aborted" | "unknown";
+export interface WorkspaceRow {
+    id: string;
+    name: string;
+    /** 工作目录：创建后不可变（PRD D9），因此这里没有更新方法 */
+    cwd: string;
+    createdAt: number;
+}
+export interface WorkspaceCreateInput {
+    id: string;
+    name: string;
+    cwd: string;
+    createdAt: number;
+}
+export interface ConversationRow {
+    id: string;
+    workspaceId: string;
+    name: string;
+    /** 0 / 1：这个名字是不是自动起的（R35）。创建时的原名算自动，用户改名置 0，自动命名置 1 */
+    nameIsAuto: number;
+    /** 0 / 1：侧栏置顶（PRD D13） */
+    pinned: number;
+    /** 创建时定死的助手（PRD L7），此处只存 id；定义本身在配置层 */
+    agentId: string;
+    /** 这段会话现在用的模型：创建时取助手定义上那个，之后可以由 `conversation.setModel` 改 */
+    modelId: string;
+    /**
+     * 这段会话选的思考档位名；`null` = 跟随助手定义上的那份参数。
+     *
+     * 存的是档位名而不是展开后的参数：档位属于模型（同一个档位名在不同模型的策略表里
+     * 对应不同参数），换模型时这一列被清空，展开只在装配 agent 那一刻做。
+     */
+    thinkingLevel: string | null;
+    createdAt: number;
+    /** 最后一次结构性变化的时间；排序只看 pinned + createdAt，不看它（D13） */
+    updatedAt: number;
+}
+export interface Conversation extends Omit<ConversationRow, "pinned" | "nameIsAuto"> {
+    pinned: boolean;
+    /** 名字仍是自动起的那个（真值来自 `conversations.nameIsAuto` 列，不由名字反推） */
+    nameIsAuto: boolean;
+}
+export interface ConversationCreateInput {
+    id: string;
+    workspaceId: string;
+    name: string;
+    /** 助手是对话身份的一部分，创建时必须已知（解析不出来就先解析、不建行） */
+    agentId: string;
+    /** 模型创建时也必须有值（取助手定义上那个，或创建时点名的那一个） */
+    modelId: string;
+    /** 创建时就能定的思考档位（草稿期间用户先调过档、首次发消息才落库）；缺省 `null` = 跟随助手 */
+    thinkingLevel?: string | null;
+    createdAt: number;
+    updatedAt?: number;
+}
+export interface MessageRow {
+    id: string;
+    conversationId: string;
+    /** 同一对话内单调递增的序号，用于稳定排序与 `after` 游标 */
+    seq: number;
+    role: string;
+    status: string;
+    /** 0 / 1：是否已被移出上下文（PRD D15 要求 status / omit 必须落盘） */
+    omit: number;
+    /** JSON：消息正文（core 内容形状的 JSON 文本） */
+    content: string;
+    /** JSON：其余字段（tool_calls / reasoning_content / usage / name / finish_reason …） */
+    data: string | null;
+    /** 供全文检索的纯文本（从 content 抽出来的正文，不含 JSON 键名） */
+    searchText: string;
+    /** 子 Agent 消息挂在哪次工具调用上；顶层消息为 NULL（R37） */
+    parentToolCallId: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface StoredMessage {
+    id: string;
+    conversationId: string;
+    /** 子 Agent 消息所属的父工具调用 id；顶层消息为 `null`（R37） */
+    parentToolCallId: string | null;
+    seq: number;
+    role: string;
+    status: string;
+    omit: boolean;
+    /** 已反序列化的正文：core 的内容形状；`null` 表示这条消息没有正文 */
+    content: AgentNS.MessageContent | null;
+    data: Record<string, unknown> | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * 边流边写的入参：同一条消息按 id 反复 upsert，每次覆盖正文 / 状态 / omit，
+ * 但 `seq` 与 `createdAt` 保持第一次写入时的值。
+ */
+export interface MessageUpsertInput {
+    id: string;
+    conversationId: string;
+    role: string;
+    status: string;
+    /** core 的内容形状；不给表示这条消息没有正文 */
+    content?: AgentNS.MessageContent | null;
+    data?: Record<string, unknown> | null;
+    omit?: boolean;
+    /** 子 Agent 消息要挂的父工具调用 id；不给表示顶层消息（R37） */
+    parentToolCallId?: string | null;
+    createdAt: number;
+}
+/**
+ * 全文搜索的范围：一段对话内，或一个 Workspace 下的全部对话。
+ *
+ * 之所以做成二选一的联合类型而不是两个可选字段，是因为「两个都没给」在语义上等于
+ * 全库搜索，而 PRD D16 只要求「按 Workspace 过滤」，不给就不该搜全库。
+ */
+export type MessageSearchScope = {
+    conversationId: string;
+} | {
+    workspaceId: string;
+} | undefined;
+/** 全文搜索命中项：带上对话名与命中附近的片段，前端不用再查一遍 */
+export interface MessageSearchHit {
+    id: string;
+    conversationId: string;
+    conversationName: string;
+    workspaceId: string;
+    role: string;
+    /** 命中位置前后截取的正文片段 */
+    snippet: string;
+    createdAt: number;
+}
+export interface AssetRow {
+    id: string;
+    /** 原始文件名（可空：粘贴的图片未必有名字） */
+    name: string | null;
+    /** 数据根下 `assets/` 的相对路径，库里只存引用（PRD L2） */
+    path: string;
+    mime: string;
+    bytes: number;
+    /** 内容摘要（上传时宿主自己算的那一份）：全库唯一，即全局去重的键 */
+    sha256: string;
+    /** 像素宽度：落定时按文件头解出（PNG / JPEG），解不出来是 null */
+    width: number | null;
+    /** 像素高度；口径同 `width` */
+    height: number | null;
+    createdAt: number;
+}
+export interface AssetCreateInput {
+    id: string;
+    name?: string | null;
+    path: string;
+    mime: string;
+    bytes: number;
+    sha256: string;
+    width?: number | null;
+    height?: number | null;
+    createdAt: number;
+}
+/**
+ * 关系行：某条消息引用了某份素材。
+ *
+ * 一行就是一次「引用」；同一对 `(messageId, assetId)` 只有一行（唯一约束）。
+ * 素材的归属、以及「几张会话引用了它」都从这张表算，`assets` 行上不再记对话 / 消息。
+ */
+export interface ConversationAssetRow {
+    conversationId: string;
+    messageId: string;
+    assetId: string;
+    createdAt: number;
+}
+/**
+ * 厂商侧文件 id 的缓存行。
+ *
+ * `vendorFileId` 是**端点维度**的资源：同一个素材在 A 端点上传得到的 id 拿到 B 端点用会 not found。
+ * 所以这张表是缓存：这个端点上有就直接用，没有就按素材服务那三条规则走。
+ */
+export interface AssetVendorFileRow {
+    assetId: string;
+    endpointId: string;
+    vendorFileId: string;
+    createdAt: number;
+}
+export interface AssetVendorFileUpsertInput {
+    assetId: string;
+    endpointId: string;
+    vendorFileId: string;
+    createdAt: number;
+}
+export interface NoticeRow {
+    id: string;
+    /** 语气档位（PRD L3 的三档），取值由上层定义，存储层不判断 */
+    level: string;
+    /** 文案码：库里存码 + 参数，读出时按连接语言渲染（architecture.md §6） */
+    code: string;
+    /** JSON：文案参数 */
+    params: string | null;
+    /** 毫秒数；null 表示永久存在，只能手动清（PRD L3） */
+    durationMs: number | null;
+    /** 这条通知与哪段对话有关；null 表示全局通知（对话删掉时随之级联删除） */
+    conversationId: string | null;
+    createdAt: number;
+}
+export interface Notice {
+    id: string;
+    level: string;
+    code: string;
+    params: Record<string, unknown> | null;
+    durationMs: number | null;
+    /** 这条通知与哪段对话有关；null 表示全局通知 */
+    conversationId: string | null;
+    createdAt: number;
+}
+export interface NoticeCreateInput {
+    id: string;
+    level: string;
+    code: string;
+    params?: Record<string, unknown> | null;
+    durationMs?: number | null;
+    /** 挂在哪段对话上；不给表示全局通知 */
+    conversationId?: string | null;
+    createdAt: number;
+}
+export interface QuestionRow {
+    id: string;
+    conversationId: string;
+    /** 问题种类，取值由上层定义（交接确认、二次确认） */
+    kind: string;
+    /** JSON：候选项、正文等载荷 */
+    payload: string;
+    /** 状态机取值由上层定义，存储层原样存取（PRD D22：有状态、可持久化） */
+    state: string;
+    /** JSON：用户的回答 */
+    answer: string | null;
+    createdAt: number;
+    updatedAt: number;
+    answeredAt: number | null;
+}
+export interface Question {
+    id: string;
+    conversationId: string;
+    kind: string;
+    payload: unknown;
+    state: string;
+    answer: unknown;
+    createdAt: number;
+    updatedAt: number;
+    answeredAt: number | null;
+}
+export interface QuestionCreateInput {
+    id: string;
+    conversationId: string;
+    kind: string;
+    payload: unknown;
+    state: string;
+    createdAt: number;
+}
+export interface CredentialRow {
+    id: string;
+    note: string;
+    /** 凭证的 sha256 摘要；明文不进库（PRD L11） */
+    hash: string;
+    createdAt: number;
+    /** 吊销时间；null 表示仍然有效 */
+    revokedAt: number | null;
+}
+/** 对外展示用：不含 hash */
+export interface CredentialInfo {
+    id: string;
+    note: string;
+    createdAt: number;
+    revokedAt: number | null;
+}
+export interface CredentialCreateInput {
+    id: string;
+    note: string;
+    hash: string;
+    createdAt: number;
+}
+export interface MetaRow {
+    id: number;
+    schemaVersion: number;
+    createdAt: number;
+}

package/dist/storage/types.js

@@ -0,0 +1,14 @@
+/**
+ * 存储层的行类型与入参类型。
+ *
+ * 约定：
+ * - 列名与字段名都是 camelCase（SQLite 的列名并不强制风格，这里让「行类型 = 列名」，
+ *   读写两侧不用再维护一张映射表）。
+ * - 所有时间戳都是 `Date.now()` 的毫秒数，列类型 INTEGER（见各表注释）。
+ * - 带 `Row` 后缀的是**数据库原样行**（JSON 列还是字符串），不带后缀的是仓储解好的对象。
+ * - 消息正文直接用 core 的 `AgentNS.MessageContent`（R21 / R30）：列里存的就是它的 JSON，
+ *   仓储反序列化后就是同一个形状，服务层与运行时不必在两种形状之间翻译。
+ * - `role` / `status` 仍以字符串存取（取值与 `AgentNS.Role` / `AgentNS.MessageStatus` 一致），
+ *   收敛成 core 的枚举发生在服务层。
+ */
+export {};

package/dist/wire/errors.d.ts

@@ -0,0 +1,105 @@
+import { type Language, type MessageKey } from "../i18n/index.js";
+/**
+ * 业务码与错误类。
+ *
+ * 分工（architecture §6）：JSON-RPC 的 `error.code` 是数字（协议层），`error.data` 里才是
+ * 产品要用的三样东西 ——
+ *   - `data.code`：**稳定业务码**，小写下划线，客户端据此分支（换文案不该改它）；
+ *   - `data.message`：已按连接语言渲染好的人话（PRD D8：宿主自己做多语言）；
+ *   - `data.detail` / `data.params`：结构化事实与渲染参数，让客户端不必解析句子去猜原因。
+ *
+ * 业务码本身只增不改语义：一个码的含义一旦发出去，客户端就可能已经按它写了分支。
+ */
+/**
+ * 稳定业务码。命名小写下划线，客户端按它分支。
+ *
+ * 逐条对应的用户可见处境（文案见 `i18n/en.ts` 的 `error.*`）：
+ */
+export type BizCode = 
+/** 凭证没被接受（含未 `hello` 就发别的请求） */
+"unauthorized"
+/** 参数形状 / 取值不对（含帧解析失败的字段级原因） */
+ | "invalid_params"
+/** 目标对象不存在（对话、消息、问题、附件……） */
+ | "not_found"
+/** 这段对话正在跑上一轮（PRD D14：忙就拒，不排队） */
+ | "busy"
+/** 上传或请求体超限（PRD D5：图片 20MB/张） */
+ | "payload_too_large"
+/** 协议里我们不用的那部分，或某个能力在本宿主不提供（PRD A4） */
+ | "unsupported"
+/** 宿主内部错误，细节只在日志里 */
+ | "internal"
+/** 配置读得出来但用不了（PRD F-A8：结构化原因，能当场修） */
+ | "config_invalid"
+/** MCP 服务器连不上或没响应（PRD F-G1） */
+ | "mcp_unavailable"
+/** 目标模型不具备所需能力，例如读不了历史里的图片（PRD D20 / F-B8） */
+ | "model_unsupported"
+/** 用户选择了不交接（PRD F-D2 的三个选项之一 / F-D7 取消不等于失败） */
+ | "handoff_declined"
+/** 还有问题挂着没答，且它在挡着这段对话（PRD D22 / D23 / F-D10） */
+ | "question_pending"
+/** 上下文到了硬线，本轮不再发出请求（PRD F-D1 / D23） */
+ | "context_guard";
+/** 全部业务码；用于校验与测试遍历 */
+export declare const BIZ_CODES: readonly BizCode[];
+/** 业务码对应的 JSON-RPC 数字码 */
+export declare function jsonRpcCode(code: BizCode): number;
+/** 业务码对应的默认文案键 */
+export declare function defaultMessageKey(code: BizCode): MessageKey;
+/** 运行时判断一个值是不是已知业务码 */
+export declare function isBizCode(value: unknown): value is BizCode;
+/**
+ * 错误帧里 `error.data` 的形状。
+ *
+ * 客户端读 `code` 分支、显示 `message`、按 `detail` 做「该往哪个输入框填什么」这类动作。
+ */
+export interface ErrorData {
+    /** 稳定业务码 */
+    code: BizCode;
+    /** 已按连接语言渲染的人话 */
+    message: string;
+    /** 结构化事实：哪个字段不对、还差什么（形状由各码约定，客户端不解析句子） */
+    detail?: unknown;
+    /** 渲染 `message` 用到的参数，客户端如需自己重排文案可直接用 */
+    params: Record<string, unknown>;
+}
+/** 构造 `HostError` 的可选项 */
+export interface HostErrorOptions {
+    /** 文案键；缺省按 `code` 取（见 `defaultMessageKey`） */
+    messageKey?: MessageKey;
+    /** 渲染参数（`{name}` 形式占位） */
+    params?: Record<string, unknown>;
+    /** 结构化事实 */
+    detail?: unknown;
+    /** 原始错误，留给日志 */
+    cause?: unknown;
+}
+/**
+ * 宿主抛给接线的错误：带业务码、文案键与渲染参数，出网时按连接语言渲染。
+ *
+ * 业务层只管用码与参数描述「哪里不对」，不拼句子、不碰语言 —— 语言是连接的事。
+ */
+export declare class HostError extends Error {
+    readonly code: BizCode;
+    readonly messageKey: MessageKey;
+    readonly params?: Record<string, unknown>;
+    readonly detail?: unknown;
+    constructor(code: BizCode, options?: HostErrorOptions);
+    /** 渲染成错误帧里的 `data`（PRD D8：按连接语言出人话） */
+    toErrorData(language?: Language): ErrorData;
+    /** 换一条更适合当前上下文的文案键（例如带上具体实体名），返回新实例 */
+    withMessage(messageKey: MessageKey, params?: Record<string, unknown>): HostError;
+    /** 追加结构化事实后返回新实例 */
+    withDetail(detail: unknown): HostError;
+    /** 判断任意值是不是 `HostError`（跨模块实例判断用不到 `instanceof` 的场合） */
+    static is(value: unknown): value is HostError;
+}
+/**
+ * 把任意抛出物收敛成 `ErrorData`。
+ *
+ * 接线层只会写一次 `catch`，其它错误（`TypeError`、SDK 抛的、字符串）都在这里被兜成
+ * `internal`，原始信息进 `detail.reason` 供排查 —— 于是界面上是一句人话，而不是一堆堆栈。
+ */
+export declare function toErrorData(error: unknown, language?: Language): ErrorData;