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

package/dist/services/NoticeService.js

@@ -0,0 +1,217 @@
+/**
+ * 通知服务：一条**独立通道**（PRD F-I8），它不进消息流。
+ *
+ * 三件事在这里定死：
+ *
+ * 1. **持久化**（PRD L3）：通知落 `notices` 表，重启之后还在；永久通知的消失只有「手动清」
+ *    这一条路径（`notice.dismiss` / `notice.clear`），带持续时间的到点自己消失。
+ * 2. **持续时间的两套单位**（R15）：契约用**秒**（用户语义：「这条提示留 3 秒」），
+ *    库里存**毫秒**（`notices.durationMs`）。换算只有本文件这一处 —— 别处再换一次，
+ *    迟早有一条通知留 3 毫秒或 3 天。
+ * 3. **存码不存句子**（D8 / architecture §6）：库里存的是「码 + 参数」，读出时按**调用方
+ *    给的语言**渲染。语言挂在连接上，一条通知存死一种语言、换个语言连回来就错了。
+ *
+ * 语气三档 `info | warning | error`（R4）：「已保存」这种一秒提示是 `info` + 短 duration，
+ * 不新增 success 档；`warning` / `error` 同时是宿主日志上浮的通道（PRD F-J2）。
+ */
+import { randomUUID } from "node:crypto";
+import { DEFAULT_LANGUAGE, hasMessage, render } from "../i18n/index.js";
+import { HostError } from "../wire/errors.js";
+import { NOTICE_LEVELS } from "../wire/states.js";
+/** 库里那条 `code` 认不出来时用的文案键（配置被手改坏、旧版本写进去的码） */
+const UNKNOWN_CODE_KEY = "notice.unknown";
+/** 时间戳转 wire 上的 ISO 8601 */
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+/** 库里的语气档位：认不出来就按 `info` 摆（手改坏的数据不该让整条列表读不出来） */
+function toLevel(value) {
+    return NOTICE_LEVELS.includes(value) ? value : "info";
+}
+/**
+ * 秒 → 毫秒（R15 的唯一一处换算）。
+ *
+ * 不是数字、负数、`NaN`、无穷大都按「参数不对」拒：这条通知要么留一段确定的时间，
+ * 要么永久留着，不存在「留一段说不清多久」。
+ */
+function toDurationMs(duration, field) {
+    if (duration === undefined || duration === null)
+        return null;
+    if (typeof duration !== "number" || !Number.isFinite(duration) || duration < 0) {
+        throw new HostError("invalid_params", {
+            params: { field },
+            detail: { field, reason: "not_a_duration", value: duration },
+        });
+    }
+    return Math.round(duration * 1000);
+}
+/**
+ * 一行库记录 → 契约上的 `NoticeView`（按给定语言渲染）。
+ *
+ * `duration` 在这里由毫秒换回秒：库里是机器口径，出网是用户口径。
+ */
+function toView(notice, language) {
+    const params = notice.params ?? {};
+    const known = hasMessage(notice.code);
+    const messageKey = known ? notice.code : UNKNOWN_CODE_KEY;
+    // 认不出来的码：把原码当参数交给兜底那句，用户至少能看到它是什么
+    const renderParams = known ? params : { ...params, code: notice.code };
+    const text = {
+        code: notice.code,
+        messageKey,
+        params: renderParams,
+        message: render(language, messageKey, renderParams),
+    };
+    return {
+        id: notice.id,
+        level: toLevel(notice.level),
+        duration: notice.durationMs === null ? null : notice.durationMs / 1000,
+        text,
+        conversationId: notice.conversationId,
+        createdAt: iso(notice.createdAt),
+    };
+}
+/** 按语言重渲染一句已存的文案（`messageKey` + `params` 都在 `LocalizedText` 里） */
+export function relocalizeText(text, language) {
+    const messageKey = hasMessage(text.messageKey) ? text.messageKey : UNKNOWN_CODE_KEY;
+    return { ...text, message: render(language, messageKey, text.params) };
+}
+/** 按语言重渲染一个问题的提示与候选（多端各自的语言，PRD D8） */
+function relocalizeQuestion(question, language) {
+    return {
+        ...question,
+        prompt: relocalizeText(question.prompt, language),
+        options: question.options.map((option) => ({
+            ...option,
+            label: relocalizeText(option.label, language),
+            detail: option.detail === null ? null : relocalizeText(option.detail, language),
+        })),
+    };
+}
+/** 造上面那个本地化器（接线层把它注入 `WsHub` 的 `localizeEvent`） */
+export function createEventLocalizer() {
+    return (event, payload, language) => {
+        if (event === "notice") {
+            const noticePayload = payload;
+            const notice = noticePayload.notice;
+            const localized = {
+                ...noticePayload,
+                notice: { ...notice, text: relocalizeText(notice.text, language) },
+            };
+            return localized;
+        }
+        if (event === "question") {
+            const questionPayload = payload;
+            const localized = {
+                ...questionPayload,
+                question: relocalizeQuestion(questionPayload.question, language),
+            };
+            return localized;
+        }
+        return payload;
+    };
+}
+export class NoticeService {
+    notices;
+    emit;
+    now;
+    newId;
+    constructor(deps) {
+        this.notices = deps.notices;
+        this.emit = deps.emit;
+        this.now = deps.now ?? Date.now;
+        this.newId = deps.newId ?? randomUUID;
+    }
+    /**
+     * 发一条通知（内部入口）。
+     *
+     * 落库 → 推 `notice` 事件 → 返回渲染好的视图。落库在推送之前：推送只对在线连接有意义
+     * （D5：断线即作废），而库里的那条是重连之后还能看到的真相（L3）。
+     */
+    async create(input, language = DEFAULT_LANGUAGE) {
+        if (!NOTICE_LEVELS.includes(input.level)) {
+            throw new HostError("invalid_params", {
+                params: { field: "level" },
+                detail: { field: "level", value: input.level, levels: NOTICE_LEVELS },
+            });
+        }
+        if (!hasMessage(input.code)) {
+            throw new HostError("invalid_params", {
+                params: { field: "code" },
+                detail: { field: "code", reason: "unknown_message_key", value: input.code },
+            });
+        }
+        const durationMs = toDurationMs(input.duration, "duration");
+        const params = { ...(input.params ?? {}) };
+        const id = this.newId();
+        const createdAt = this.now();
+        const row = {
+            id,
+            level: input.level,
+            code: input.code,
+            params: Object.keys(params).length > 0 ? params : null,
+            durationMs,
+            conversationId: input.conversationId ?? null,
+            createdAt,
+        };
+        await this.notices.create(row);
+        const notification = toView(row, language);
+        this.emit?.("notice", { notice: notification, at: iso(createdAt) });
+        return notification;
+    }
+    /**
+     * 日志上浮（PRD F-J2：warn / error 也要上通知栏）。
+     *
+     * 没有持续时间 = 永久：界面上的一闪而过不适合承载「宿主出了什么事」，
+     * 这类通知要留到用户看过并手动清掉。
+     */
+    async log(level, summary, language = DEFAULT_LANGUAGE) {
+        return await this.create({
+            level,
+            code: level === "warning" ? "notice.logWarning" : "notice.logError",
+            params: { summary },
+            duration: null,
+        }, language);
+    }
+    /**
+     * 现在该显示的通知（PRD L3）。
+     *
+     * 先清掉已经到点的（`deleteExpired`），再按「永久 + 还没到点」读一遍：只按时间过滤而不清，
+     * 表会一直涨；只清不按时间过滤，同一毫秒内到点的那条仍会被读出来。
+     */
+    async list(params = {}, language = DEFAULT_LANGUAGE) {
+        const now = this.now();
+        await this.notices.deleteExpired(now);
+        const active = await this.notices.listActive(now);
+        const views = active
+            .map((notice) => toView(notice, language))
+            .filter((view) => (params.level === undefined ? true : view.level === params.level))
+            .filter((view) => params.conversationId === undefined ? true : view.conversationId === params.conversationId);
+        return { notices: views };
+    }
+    /**
+     * 清掉一条（PRD L3：永久通知唯一能消失的方式）。
+     *
+     * 已经不存在时回 `dismissed: false`（这次有没有真的改动库），与 `notice.clear` 的口径一致。
+     */
+    async dismiss(params) {
+        const id = typeof params.noticeId === "string" ? params.noticeId.trim() : "";
+        if (id.length === 0) {
+            throw new HostError("invalid_params", {
+                params: { field: "noticeId" },
+                detail: { field: "noticeId", reason: "empty" },
+            });
+        }
+        const changes = await this.notices.clear(id);
+        return { dismissed: changes > 0 };
+    }
+    /** 清掉一批（不给 `conversationId` 就清全部） */
+    async clear(params = {}) {
+        if (params.conversationId === undefined) {
+            const cleared = await this.notices.clearAll();
+            return { cleared };
+        }
+        const cleared = await this.notices.clearByConversation(params.conversationId);
+        return { cleared };
+    }
+}

package/dist/services/QuestionService.d.ts

@@ -0,0 +1,184 @@
+/**
+ * 问题服务：把「要不要交接 / 要不要登记这个目录 / 确认一下」变成**对象**（PRD D22 / F-I9）。
+ *
+ * 一个问题的四件事实都在这里：有 id、有状态、有生命周期、可持久化。多端看到的是同一个
+ * 对象（库里那一行），所以「另一个窗口已经答过了」这件事不需要另开一条同步通道 ——
+ * 第二次拉 `question.list` 就能看到状态变了。
+ *
+ * 三条贯穿本文件的边界：
+ *
+ * 1. **存码不存句子**（D8）：`questions.payload` 里存的是文案键 + 参数 + 候选项的值，
+ *    读出时按调用方给的语言渲染。一条问题存死一种语言，换个连接就错了。
+ * 2. **答完之后接着往下走**（D22）：`answer` 的副作用是宿主自己做掉的 —— 答「自交接 /
+ *    独立摘要」就当场开始交接，客户端不必再发一次 `handoff.start`。
+ * 3. **越线两端都拒绝时问题继续挂着**（D23 / F-D10）：答不下去的那些路径（对话正在跑、
+ *    已经过了硬线而用户选了「就在这段里继续」）都不动这一行状态，所以问题不会被悄悄关掉。
+ *    本文件里没有「自动过期」「答错一次就作废」这类隐式转移。
+ */
+import type { ConfigManager } from "@ai-zen/agents-sdk";
+import type { Language, MessageKey } from "../i18n/index.js";
+import type { ChatEventEmitter } from "../runtime/ChatRunner.js";
+import type { RunsView } from "../runtime/RunRegistry.js";
+import type { ConversationRepository } from "../storage/ConversationRepository.js";
+import type { MessageRepository } from "../storage/MessageRepository.js";
+import type { QuestionRepository } from "../storage/QuestionRepository.js";
+import type { HandoffStartParams, QuestionAnswerParams, QuestionAnswerResult, QuestionKind, QuestionListParams, QuestionListResult, QuestionView } from "../wire/index.js";
+/** 一句话的「码 + 参数」（库里存的是它，读出时才渲染成一句人话） */
+export interface LocalizedSource {
+    messageKey: MessageKey;
+    params?: Record<string, unknown>;
+}
+/** 一个候选答案的入参 */
+export interface QuestionOptionInput {
+    /** 提交回答时回传的值 */
+    value: string;
+    label: LocalizedSource;
+    detail?: LocalizedSource | null;
+}
+/** 内部「问一个问题」的入口（交接线、登记项目、二次确认都走它） */
+export interface AskQuestionInput {
+    /** 挂在哪段对话上（问题总是为某一段对话停下来问的） */
+    conversationId: string;
+    kind: QuestionKind;
+    prompt: LocalizedSource;
+    options: QuestionOptionInput[];
+    /**
+     * 是否挡着这段对话（挡着时 `conversation.send` 会被拒，业务码 `question_pending`）。
+     *
+     * 缺省按种类定：交接确认与不可撤销动作的确认挡着对话，登记项目不挡 —— 后者与某一段
+     * 对话的生成无关，挡了就变成「必须先答一个跟这次发送没关系的问题」。
+     */
+    blocking?: boolean;
+    /** 出网的稳定码；缺省用 `prompt.messageKey` */
+    code?: string;
+    /**
+     * 与界面无关、但答完之后用得到的事实（例如「哪个目录待登记」、要接着建哪段对话）。
+     *
+     * 存进 `questions.payload.data`：它不是文案，不跟着语言变；也不是契约上的东西（客户端
+     * 只看得到渲染好的句子与候选项），宿主答完后自己取用。
+     */
+    data?: Record<string, unknown>;
+}
+/** 回答时的现场事实：哪条连接答的、用哪种语言回话 */
+export interface QuestionAnswerContext {
+    language?: Language;
+    /** 回答它的那条连接（多端时用来显示「别的窗口答了」） */
+    answeredBy?: string | null;
+}
+/**
+ * 答完之后的副作用入口（交接那一步）。
+ *
+ * 类型故意只声明本服务用得到的那一部分（`newConversationId`）：交接服务返回的字段比这多，
+ * 结构上照样满足，免得两个服务为了一个字段互相 import 具体类。
+ */
+export interface QuestionHandoffPort {
+    start(params: HandoffStartParams, language?: Language): Promise<{
+        newConversationId: string | null;
+    }>;
+}
+/** 硬线判定口：这段对话现在是不是已经过了硬线（PRD F-D1 / D23） */
+export interface QuestionGuardProbe {
+    overGuard(conversationId: string): Promise<boolean>;
+}
+export interface QuestionServiceDeps {
+    questions: QuestionRepository;
+    /** 「这段对话正在跑一轮」的唯一真相；不注入时按「没在跑」处理 */
+    runs?: RunsView;
+    /** 硬线判定；不注入时按「没过线」处理 */
+    guard?: QuestionGuardProbe;
+    /** 交接入口（答完接着交接，D22）；不注入时答完只改状态、不触发交接 */
+    handoff?: QuestionHandoffPort;
+    /** 推 `question` 事件（多端看到同一个，D22） */
+    emit?: ChatEventEmitter;
+    now?: () => number;
+    newId?: () => string;
+}
+/** 交接问题的三个候选值（F-D2：自交接 / 独立摘要 / 不交接） */
+export declare const HANDOFF_OPTION_SELF = "self";
+export declare const HANDOFF_OPTION_SUMMARY = "summary";
+export declare const HANDOFF_OPTION_DECLINE = "decline";
+export declare class QuestionService {
+    private readonly questions;
+    private readonly runs?;
+    private readonly guard?;
+    private readonly handoff?;
+    private readonly emit?;
+    private readonly now;
+    private readonly newId;
+    constructor(deps: QuestionServiceDeps);
+    /**
+     * 问一个问题（内部入口）。
+     *
+     * 先落库再推事件：库里那一行是「多端看同一个」的真相（D22），推送只是提醒在线的那几个
+     * 窗口去拉（L5 断线即作废）。
+     */
+    ask(input: AskQuestionInput, language?: Language): Promise<QuestionView>;
+    /**
+     * 到交接线时问「自交接 / 独立摘要 / 不交接」（PRD F-D2 / D22）。
+     *
+     * 触发点在**对话停下之后**：这里只负责把问题摆出来，不参与任何流式过程。
+     * `percent` 是给人看的那个数（用量 / 交接线），数字本身留在库里与状态里。
+     */
+    askHandoff(input: {
+        conversationId: string;
+        promptTokens: number;
+        handoffTokens: number;
+        blocking?: boolean;
+    }, language?: Language): Promise<QuestionView>;
+    /**
+     * 列出问题（PRD D22：多端看同一个）。
+     *
+     * `conversationId` 可选（R61）：给了就只看那段对话的；不给就看全库（含没挂对话的那些，
+     * 例如「要不要把这个目录登记成项目」）。`state` 两种情况下都生效。
+     */
+    list(params?: QuestionListParams, language?: Language): Promise<QuestionListResult>;
+    /** 这段对话上还挂着、且正在挡着它的那些问题（`conversation.send` 的前置检查用它） */
+    blockingQuestions(conversationId: string): Promise<QuestionView[]>;
+    /**
+     * 有挡着的问题就拒绝（PRD D23 / F-D10 的「宿主也拒绝」）。
+     *
+     * 只在真有 `blocking` 的问题时抛 `question_pending`，并把那条问题的提问当参数带上：
+     * 用户看到的是「哪个问题在挡着」，不是一句抽象的「还有问题没答」。
+     */
+    assertSendable(conversationId: string): Promise<void>;
+    /**
+     * 回答一个问题（PRD D22 / F-I9）。
+     *
+     * 顺序是刻意的：
+     *   1. 已经答过 / 已失效的直接回当前状态（多端同时点，后到的那一端看到的是「已经答了」，
+     *      不重复触发副作用）；
+     *   2. 值不在候选里 → `invalid_params`；
+     *   3. 对话正在跑一轮 → `busy`（D22：交接在对话停下之后触发，不在流式中途）；
+     *   4. 过了硬线又选了「就在这段里继续」 → `context_guard`，**问题继续挂着**（D23）；
+     *   5. 改状态 → 该交接就当场交接。
+     *
+     * 第 3、4 两步都在写状态之前返回，所以「答不下去」不会把问题弄成一个半答的中间态。
+     */
+    answer(params: QuestionAnswerParams, context?: QuestionAnswerContext): Promise<QuestionAnswerResult>;
+    /**
+     * 显式取消一个问题（生命周期里的 `cancelled`）。
+     *
+     * 只有调用方明确要关掉时才用（例如对话被删、工作流换了方向）。没有任何自动取消的路径 ——
+     * 越线拒绝之后问题要继续挂着（D23），所以「答不下去」与「关掉它」是两件事。
+     */
+    cancel(questionId: string, language?: Language): Promise<QuestionView>;
+    /**
+     * 答完之后接着往下走：交接（D22）。
+     *
+     * 只在问题已经落成 `answered` 之后才跑：答不下去的那些情况（越线、对话在跑）
+     * 在写状态之前就返回了，所以这里不需要再判断一遍。
+     */
+    private applyEffects;
+    private requireQuestion;
+}
+/**
+ * 按配置与历史算「这段对话是不是已经过了硬线」。
+ *
+ * 硬线跟着模型走（`tokenThresholds.guard`，D27），用量取最近一条带用量的消息：
+ * 与 `conversation.state` 里那份 `ContextState` 是同一个口径（都看 `usage.prompt_tokens`）。
+ */
+export declare function createConversationGuardProbe(deps: {
+    conversations: ConversationRepository;
+    messages: MessageRepository;
+    configManager: ConfigManager;
+}): QuestionGuardProbe;