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

package/dist/services/Logger.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 日志落文件（PRD F-J2）：`<dataRoot>/logs/host.log` + 按大小轮转 + warn/error 同时上通知。
+ *
+ * 为什么要有它：界面被一段对话占满时，`process.stdout` 里的话没人看得到。宿主是常驻后台
+ * 进程，出事的那一刻只有磁盘上的文件是还在的（PRD F-J2 的原话就是这个理由）。
+ *
+ * 三件事在这里定死：
+ *
+ * 1. **按大小轮转**：单份到 `maxBytes`（缺省 5MB）就换下一份，保留 `maxFiles` 份（缺省 5，含
+ *    正在写的那份）。命名是 `host.log`（正在写）、`host.log.1`（上一份）……，最老的一份在
+ *    轮转时删掉。不引依赖：`node:fs` 的 `rename` / `rm` 就够。
+ * 2. **warn / error 上通知**（F-J2）：调注入的 `notifier`（组装处接的是 `NoticeService.log`，
+ *    永久通知）。**防回环**靠一个重入标记：发通知这件事本身产生的日志只落文件、不再上通知，
+ *    否则通知写库失败会再产生一条通知，一路循环下去。
+ * 3. **退出时 flush**（`close()`）：先停止接纳新行，再把已经排队的行写完，最后关流。
+ *    进程退出前没写出去的行等于没写，所以 `HostApp.stop()` 里等它。
+ *
+ * 行格式：`<ISO 时间> <级别> <来源> <消息> [detail JSON]`。级别定宽（`INFO ` / `WARN ` /
+ * `ERROR`），于是 grep 一列就能筛。时间取注入的时钟，缺省 `Date.now`。
+ */
+import type { HubLogger } from "../net/WsHub.js";
+/** 日志级别（三档：信息 / 警告 / 错误；warn 与 error 会同时上通知） */
+export type LogLevel = "info" | "warn" | "error";
+/** 单份日志文件的上限（5MB；到点换下一份） */
+export declare const DEFAULT_MAX_BYTES: number;
+/** 保留几份（含正在写的那一份） */
+export declare const DEFAULT_MAX_FILES = 5;
+/** 日志文件的缺省名字 */
+export declare const DEFAULT_LOG_FILE_NAME = "host.log";
+/**
+ * 「这条 warn / error 也让用户在通知栏里看到」（PRD F-J2）。
+ *
+ * 组装处接的是 `NoticeService.log`（永久通知）。这里刻意不传 `Error` 对象：通知只带一句
+ * 给人看的摘要，栈留在文件里。
+ */
+export type LogNotifier = (level: "warning" | "error", summary: string) => void | Promise<void>;
+/** 带来源的日志口子（`withSource` 的返回类型）：比 `HubLogger` 多一档 info */
+export interface SourceLogger extends HubLogger {
+    info(message: string, detail?: unknown): void;
+}
+export interface LoggerOptions {
+    /** 日志目录（`HostPaths.logsDir` = `<dataRoot>/logs`）；首次落盘时创建 */
+    dir: string;
+    /** 文件名，缺省 `host.log` */
+    fileName?: string;
+    /** 单份上限（字节），缺省 5MB */
+    maxBytes?: number;
+    /** 保留几份（含正在写的那份），缺省 5 */
+    maxFiles?: number;
+    /** 缺省来源标签（`withSource` 之外的写法用它），缺省 `host` */
+    source?: string;
+    /** warn / error 上通知的出口；不给时只落文件 */
+    notifier?: LogNotifier;
+    /** 时钟，用例注入用；缺省 `Date.now` */
+    now?: () => number;
+}
+export declare class Logger implements HubLogger, SourceLogger {
+    private readonly dir;
+    private readonly fileName;
+    private readonly maxBytes;
+    private readonly maxFiles;
+    private readonly source;
+    private readonly now;
+    private notifier;
+    /** 正在发通知：这期间产生的 warn / error 只落文件（防回环） */
+    private notifying;
+    private stream;
+    /** 正在写的那份已经写了多少字节（轮转判据） */
+    private bytes;
+    /** 写盘按到达顺序串行（轮转要等当前流关掉，不能被打断） */
+    private queue;
+    /** 收尾已经开始 / 结束：之后的行不再落盘（否则 `close()` 之后还会长出新内容） */
+    private closed;
+    private closing;
+    constructor(options: LoggerOptions);
+    info(message: string, detail?: unknown): void;
+    warn(message: string, detail?: unknown): void;
+    error(message: string, detail?: unknown): void;
+    /**
+     * 写一行（级别 + 来源 + 消息 + 可选的 detail），warn / error 顺带上通知。
+     *
+     * 落盘是排队的（`queue`），所以调用方不必等：一行日志的代价不该被写盘拖住。
+     */
+    log(level: LogLevel, source: string, message: string, detail?: unknown): void;
+    /** 换一个来源标签的视图：接线层写 `ws`、单根写 `host`、素材层写 `assets`，落盘时带来源 */
+    withSource(source: string): SourceLogger;
+    /**
+     * 接上（或换掉）通知出口。
+     *
+     * 单根里日志口子比通知服务先造出来（早造的那些服务也要能记日志），所以这里允许后接一次。
+     */
+    setNotifier(notifier: LogNotifier | null): void;
+    /** 现在这份日志写到哪（`host.log` 的完整路径），供启动提示与用例读 */
+    get filePath(): string;
+    /** 收尾是否已经做完（用例断言「退出后流关闭」用它） */
+    get isClosed(): boolean;
+    /**
+     * 收尾：停止接纳新行 → 把排队的行写完 → 关流。
+     *
+     * 幂等：`HostApp.stop()` 可能被多个触发源先后叫到。
+     */
+    close(): Promise<void>;
+    private doClose;
+    private writeLine;
+    /** 拿当前要写的流（懒开：没写过日志的进程不必在数据根下留一个空文件） */
+    private ensureStream;
+    /**
+     * 轮转：关掉当前流 → `host.log` 改名为 `.1`，其余依次后移 → 最老的一份删掉。
+     *
+     * 下一行由调用方重新开流（`ensureStream` 会按新文件从 0 开始计数）。
+     */
+    private rotate;
+    /** 关闭当前流并把它写完（这一步就是 flush） */
+    private endStream;
+    /** 第 index 份文件的路径；`0` 是正在写的那份 */
+    private pathOf;
+    /**
+     * warn / error 也上通知栏。
+     *
+     * 重入标记是防回环的那一处：发通知会写库、会推事件，那些动作里万一又冒出日志，
+     * 这条判断把它们挡在「只落文件」这一侧。通知本身失败只吞掉——再记一条日志就是回环。
+     */
+    private raiseNotice;
+}
+/**
+ * 造一行日志。
+ *
+ * 级别定宽（5 列），`detail` 压成一行 JSON —— 一行一条记录，`tail -f` 与 grep 都直接可用。
+ */
+export declare function formatLine(timestamp: number, level: LogLevel, source: string, message: string, detail?: unknown): string;

package/dist/services/Logger.js

@@ -0,0 +1,256 @@
+/**
+ * 日志落文件（PRD F-J2）：`<dataRoot>/logs/host.log` + 按大小轮转 + warn/error 同时上通知。
+ *
+ * 为什么要有它：界面被一段对话占满时，`process.stdout` 里的话没人看得到。宿主是常驻后台
+ * 进程，出事的那一刻只有磁盘上的文件是还在的（PRD F-J2 的原话就是这个理由）。
+ *
+ * 三件事在这里定死：
+ *
+ * 1. **按大小轮转**：单份到 `maxBytes`（缺省 5MB）就换下一份，保留 `maxFiles` 份（缺省 5，含
+ *    正在写的那份）。命名是 `host.log`（正在写）、`host.log.1`（上一份）……，最老的一份在
+ *    轮转时删掉。不引依赖：`node:fs` 的 `rename` / `rm` 就够。
+ * 2. **warn / error 上通知**（F-J2）：调注入的 `notifier`（组装处接的是 `NoticeService.log`，
+ *    永久通知）。**防回环**靠一个重入标记：发通知这件事本身产生的日志只落文件、不再上通知，
+ *    否则通知写库失败会再产生一条通知，一路循环下去。
+ * 3. **退出时 flush**（`close()`）：先停止接纳新行，再把已经排队的行写完，最后关流。
+ *    进程退出前没写出去的行等于没写，所以 `HostApp.stop()` 里等它。
+ *
+ * 行格式：`<ISO 时间> <级别> <来源> <消息> [detail JSON]`。级别定宽（`INFO ` / `WARN ` /
+ * `ERROR`），于是 grep 一列就能筛。时间取注入的时钟，缺省 `Date.now`。
+ */
+import { createWriteStream, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** 单份日志文件的上限（5MB；到点换下一份） */
+export const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+/** 保留几份（含正在写的那一份） */
+export const DEFAULT_MAX_FILES = 5;
+/** 日志文件的缺省名字 */
+export const DEFAULT_LOG_FILE_NAME = "host.log";
+export class Logger {
+    dir;
+    fileName;
+    maxBytes;
+    maxFiles;
+    source;
+    now;
+    notifier;
+    /** 正在发通知：这期间产生的 warn / error 只落文件（防回环） */
+    notifying = false;
+    stream = null;
+    /** 正在写的那份已经写了多少字节（轮转判据） */
+    bytes = 0;
+    /** 写盘按到达顺序串行（轮转要等当前流关掉，不能被打断） */
+    queue = Promise.resolve();
+    /** 收尾已经开始 / 结束：之后的行不再落盘（否则 `close()` 之后还会长出新内容） */
+    closed = false;
+    closing = null;
+    constructor(options) {
+        this.dir = options.dir;
+        this.fileName = options.fileName ?? DEFAULT_LOG_FILE_NAME;
+        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.maxFiles = Math.max(1, options.maxFiles ?? DEFAULT_MAX_FILES);
+        this.source = options.source ?? "host";
+        this.notifier = options.notifier ?? null;
+        this.now = options.now ?? Date.now;
+    }
+    // -------------------------------------------------------------------------
+    // 对外：三档写法
+    // -------------------------------------------------------------------------
+    info(message, detail) {
+        this.log("info", this.source, message, detail);
+    }
+    warn(message, detail) {
+        this.log("warn", this.source, message, detail);
+    }
+    error(message, detail) {
+        this.log("error", this.source, message, detail);
+    }
+    /**
+     * 写一行（级别 + 来源 + 消息 + 可选的 detail），warn / error 顺带上通知。
+     *
+     * 落盘是排队的（`queue`），所以调用方不必等：一行日志的代价不该被写盘拖住。
+     */
+    log(level, source, message, detail) {
+        if (this.closed)
+            return;
+        const line = formatLine(this.now(), level, source, message, detail);
+        this.queue = this.queue.then(() => this.writeLine(line)).catch(() => undefined);
+        if (level !== "info")
+            this.raiseNotice(level, message);
+    }
+    /** 换一个来源标签的视图：接线层写 `ws`、单根写 `host`、素材层写 `assets`，落盘时带来源 */
+    withSource(source) {
+        return {
+            info: (message, detail) => this.log("info", source, message, detail),
+            warn: (message, detail) => this.log("warn", source, message, detail),
+            error: (message, detail) => this.log("error", source, message, detail),
+        };
+    }
+    /**
+     * 接上（或换掉）通知出口。
+     *
+     * 单根里日志口子比通知服务先造出来（早造的那些服务也要能记日志），所以这里允许后接一次。
+     */
+    setNotifier(notifier) {
+        this.notifier = notifier;
+    }
+    /** 现在这份日志写到哪（`host.log` 的完整路径），供启动提示与用例读 */
+    get filePath() {
+        return join(this.dir, this.fileName);
+    }
+    /** 收尾是否已经做完（用例断言「退出后流关闭」用它） */
+    get isClosed() {
+        return this.closed;
+    }
+    // -------------------------------------------------------------------------
+    // 收尾
+    // -------------------------------------------------------------------------
+    /**
+     * 收尾：停止接纳新行 → 把排队的行写完 → 关流。
+     *
+     * 幂等：`HostApp.stop()` 可能被多个触发源先后叫到。
+     */
+    close() {
+        this.closing ??= this.doClose();
+        return this.closing;
+    }
+    async doClose() {
+        this.closed = true;
+        await this.queue;
+        await this.endStream();
+    }
+    // -------------------------------------------------------------------------
+    // 落盘
+    // -------------------------------------------------------------------------
+    async writeLine(line) {
+        const size = Buffer.byteLength(line);
+        // 这一行自己就超上限时照写：写不进去比多占一份文件更糟
+        if (this.bytes > 0 && this.bytes + size > this.maxBytes)
+            await this.rotate();
+        const stream = this.ensureStream();
+        if (stream === null)
+            return;
+        this.bytes += size;
+        stream.write(line);
+    }
+    /** 拿当前要写的流（懒开：没写过日志的进程不必在数据根下留一个空文件） */
+    ensureStream() {
+        if (this.stream !== null)
+            return this.stream;
+        try {
+            mkdirSync(this.dir, { recursive: true });
+            this.bytes = sizeOf(this.filePath);
+            const stream = createWriteStream(this.filePath, { flags: "a" });
+            // 写盘本身失败时没有更好的去处（日志不能再抱怨日志），关掉它、后续行直接丢
+            stream.on("error", () => {
+                this.stream = null;
+            });
+            this.stream = stream;
+            return stream;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 轮转：关掉当前流 → `host.log` 改名为 `.1`，其余依次后移 → 最老的一份删掉。
+     *
+     * 下一行由调用方重新开流（`ensureStream` 会按新文件从 0 开始计数）。
+     */
+    async rotate() {
+        await this.endStream();
+        const oldest = this.pathOf(this.maxFiles - 1);
+        if (this.maxFiles > 1)
+            rmSync(oldest, { force: true });
+        for (let index = this.maxFiles - 2; index >= 1; index -= 1) {
+            const from = this.pathOf(index);
+            if (!exists(from))
+                continue;
+            renameSync(from, this.pathOf(index + 1));
+        }
+        if (exists(this.filePath))
+            renameSync(this.filePath, this.pathOf(1));
+    }
+    /** 关闭当前流并把它写完（这一步就是 flush） */
+    async endStream() {
+        const stream = this.stream;
+        this.stream = null;
+        this.bytes = 0;
+        if (stream === null)
+            return;
+        await new Promise((resolve) => {
+            stream.end(() => resolve());
+            // 已经坏掉的流不会再触发 finish：不让收尾挂在这里
+            stream.once("error", () => resolve());
+        });
+    }
+    /** 第 index 份文件的路径；`0` 是正在写的那份 */
+    pathOf(index) {
+        return index === 0 ? this.filePath : `${this.filePath}.${index}`;
+    }
+    // -------------------------------------------------------------------------
+    // 通知（F-J2）
+    // -------------------------------------------------------------------------
+    /**
+     * warn / error 也上通知栏。
+     *
+     * 重入标记是防回环的那一处：发通知会写库、会推事件，那些动作里万一又冒出日志，
+     * 这条判断把它们挡在「只落文件」这一侧。通知本身失败只吞掉——再记一条日志就是回环。
+     */
+    raiseNotice(level, summary) {
+        const notifier = this.notifier;
+        if (notifier === null || this.notifying)
+            return;
+        const noticeLevel = level === "error" ? "error" : "warning";
+        this.notifying = true;
+        void Promise.resolve()
+            .then(() => notifier(noticeLevel, summary))
+            .catch(() => undefined)
+            .finally(() => {
+            this.notifying = false;
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// 纯函数
+// ---------------------------------------------------------------------------
+/**
+ * 造一行日志。
+ *
+ * 级别定宽（5 列），`detail` 压成一行 JSON —— 一行一条记录，`tail -f` 与 grep 都直接可用。
+ */
+export function formatLine(timestamp, level, source, message, detail) {
+    const head = `${new Date(timestamp).toISOString()} ${level.toUpperCase().padEnd(5)} ${source} ${message}`;
+    const tail = detail === undefined ? "" : ` ${stringify(detail)}`;
+    return `${head}${tail}\n`;
+}
+function stringify(detail) {
+    if (detail instanceof Error) {
+        return JSON.stringify({ message: detail.message, stack: detail.stack });
+    }
+    try {
+        const text = JSON.stringify(detail);
+        return text === undefined ? String(detail) : text;
+    }
+    catch {
+        // 循环引用之类结构：给一个能看出「有这么个东西」的占位，不让整行丢掉
+        return "[unserializable]";
+    }
+}
+function exists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sizeOf(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/services/MessageService.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 消息服务：按对话读消息，以及把库里的一行还原成 core 的消息对象。
+ *
+ * 对应能力编号：A12 / L5（按消息 id 续拉：命中则从它开始且含它自身的最新内容，不命中返回全部）、
+ * F-C6（`around` 定位取窗，供客户端把搜索命中的那条摆到眼前）、F-I7（`toolCallId` 取子 Agent
+ * 自己的消息）、F-D9（会话创建时那条 `hidden` 的 cwd 消息默认不出网）、
+ * R21 / R22（消息原样用 core 的 `AgentNS.Message`，不额外挂时间戳这类外壳字段）。
+ *
+ * `toAgentMessage` 是这个仓库里「存储行 → core 消息」的唯一一份实现：对话服务算用量、判断
+ * 历史里有没有图也要走它，免得同一行在两处被读出两个样子。
+ *
+ * 正文不做转换（R30）：仓储反序列化出来的就是 core 的 `AgentNS.MessageContent`，这里原样
+ * 搬上消息。剩下要做的是把「列里的字符串」收敛成 core 的取值（角色 / 状态 / 结束原因）
+ * 与把 `data` 列的 JSON 逐字段收窄到 core 的类型。
+ */
+import { AgentNS } from "@ai-zen/agents-core";
+import type { ConversationRepository } from "../storage/ConversationRepository.js";
+import type { MessageRepository } from "../storage/MessageRepository.js";
+import type { Conversation, StoredMessage } from "../storage/types.js";
+import type { MessageListParams, MessageListResult } from "../wire/index.js";
+/**
+ * 草稿（R56）：刚建出来、还没发过消息的对话在库里没有行。
+ *
+ * 只暴露「按 id 取」，取到的就是存储层的行形状 —— 它没有消息可读，但存在本身足以让
+ * 读取路径不把一段刚建好的对话当成「不存在」。
+ */
+export interface MessageDraftLookup {
+    get(conversationId: string): Conversation | undefined;
+}
+/** 消息服务依赖 */
+export interface MessageServiceDeps {
+    conversations: ConversationRepository;
+    messages: MessageRepository;
+    /** 草稿注册表（R56）；不注入时只认库里已有的行 */
+    drafts?: MessageDraftLookup;
+}
+/** 库里的角色字符串 → core 的角色；搜索命中项也要用它，故对外导出 */
+export declare function toCoreRole(value: string): AgentNS.Role;
+/**
+ * 库里一行 → core 的消息对象。
+ *
+ * 正文原样透传（R30）：仓储反序列化出来的就是 core 的 `MessageContent`，逐段重建会把 core
+ * 新增的段类型 / 字段丢掉，也会让同一条消息在不同读取路径上读出两个样子。
+ *
+ * 其余字段名与取值也全部照 core（R21）：`role` / `status` / `finish_reason` 从列里的字符串
+ * 收敛成 core 的取值，`data` 列的 JSON 逐字段收窄，认不出的不往消息上搬。
+ */
+export declare function toAgentMessage(row: StoredMessage): AgentNS.Message;
+/** 从消息的其余字段里读最近一次请求的用量；没有就是 `null`（对话服务算上下文占用用） */
+export declare function readUsage(data: Record<string, unknown> | null | undefined): AgentNS.Usage | null;
+export declare class MessageService {
+    private readonly conversations;
+    private readonly messages;
+    private readonly drafts?;
+    constructor(deps: MessageServiceDeps);
+    /**
+     * 读一段对话的消息（architecture A12 / PRD F-C6）。
+     *
+     * - 不给 `after`、也不给 `around`：整段历史；
+     * - 给了 `after` 且该 id 就在这段对话里：**从这条开始**（含它，内容是最新的，可能是流式中那条的
+     *   部分内容）+ 其后全部，并把 `anchor` 报成它；
+     * - 给了 `after` 但这段对话里没有这个 id（已删、或换过库）：退回整段历史，`anchor` 为空 ——
+     *   客户端据此知道这是一次全量；
+     * - 给了 `around`：以这条为中心取 {@link AROUND_WINDOW} 条（命中那条一定在里面），
+     *   `anchor` 报成它；命中不在可见集里时给空页 + 空 `anchor`，**不报错**（消息可能刚被撤回）。
+     *   `around` 与 `after` 同时给时**只认 `around`**：两者是两种取法（一个「从这里往下」、一个
+     *   「围绕这里」），混在一起没有唯一答案。
+     *
+     * `toolCallId` 取某个子 Agent 自己的消息（PRD F-I7）：它按消息落库时记下的
+     * `parentToolCallId` 取（那次委派的工具调用 id），走的是另一条查询 —— 子 Agent 的消息不在
+     * 主线历史里（`listByConversation` 只给主线），所以两个参数同时给时 `after` 只用来定 `anchor`，
+     * 结果集仍是那个子 Agent 的全部消息。`around` 同此：`toolCallId` 决定读哪一段，`around`
+     * 只在那一段里定位。
+     *
+     * `hidden` 的消息（会话创建时那条 cwd 消息、交接摘要）默认不回：core 的这个字段就是
+     * 「这条不给人看」。要看到它们（排查、或客户端显式要）就传 `includeHidden`。
+     */
+    list(params: MessageListParams): Promise<MessageListResult>;
+    /** 把一次读到的行拼成出参；`around` 给了就收成一窗（命中不在里面就是空页） */
+    private respond;
+    /**
+     * 这段对话存不存在：库里那一行，或者一份还没落库的草稿（R56）。
+     *
+     * 草稿还没有任何消息，所以读它总是得到空集 —— 但它不该被读成「找不到这段对话」：
+     * 客户端刚 `create` 完就会拉一次消息与现场。
+     */
+    private requireConversation;
+}