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

package/dist/runtime/ChatRunner.d.ts

@@ -0,0 +1,374 @@
+/**
+ * `ChatRunner` —— 一轮对话的执行者（architecture §4 那张时序）。
+ *
+ * ## 一轮的骨架
+ *
+ * ```
+ * RunRegistry.start（忙即拒，PRD D14）
+ *   → 借 Scope（ScopeRegistry.acquire：懒创建或复用，依赖 +1）
+ *   → 分配两个消息 id 并落库（用户消息 + 助手占位，PRD L6：id 在请求发出前就有）
+ *   → 装配 agent（可注入的工厂；跑完即弃，PRD D28）
+ *   → 流式：每片增量推 `message.delta`；同一时刻更新六态并推 `run.state`；同一条消息边流边写（D15）
+ *   → 内循环结束：写一次最终版（F-C2）→ 释放 agent → RunRegistry.finish → ScopeRegistry.release
+ *   → 推结算态 `run.state` + `usage`
+ * ```
+ *
+ * ## 三处刻意交给 core 的事
+ *
+ * 1. **消息与增量不重新定义**：`AgentNS.Message` / `AgentNS.Delta` / `AgentNS.MessageStatus` /
+ *    `Usage` 全部原样用 core 的导出；攒消息用 core 的 `applyChunk`，求和用 core 的 `sumUsage`，
+ *    中止修复用 core 的 `reconcileAbortedToolRounds` / `reconcileAbortedMessages`。
+ * 2. **agent 循环不重写**：装配好的 agent 由 core 的 `send()` 驱动（内循环、工具并行、中止、
+ *    收尾归一都在 core 里）。本文件只订阅它广播出来的事件，把「发生了什么」变成持久化与推送。
+ * 3. **状态不存两处**：运行中的消息以内存（core 手里那份 `agent.messages`）为真相，库里的行是
+ *    快照；`isRunning` 只在 `RunRegistry` 一处。
+ *
+ * ## 为什么要认领 core 追加的消息 id
+ *
+ * 消息 id 由宿主分配（PRD L6），而 assistant 占位是 core 在 `run()` 里自己 `append` 的
+ * （它的 `Message` 构造会自己生成 id）。所以本文件在 `message` 事件里把「这一轮头两条」认领成
+ * 宿主已经发给客户端的 id —— 客户端的 `message.delta` 与 `message.list` 才接得上同一条消息。
+ * 后续工具轮次里 core 追加的消息同样在这一处被换成宿主分配的 id（`id` 不参与 core 的任何
+ * 判断，换掉只会让它对客户端更一致）。
+ */
+import type { AgentNS } from "@ai-zen/agents-core";
+import type { AppConfig, HandoffService, Model, ModelParams, ReasoningPresets, Scope } from "@ai-zen/agents-sdk";
+import type { Language } from "../i18n/index.js";
+import type { Conversation, MessageUpsertInput, StoredMessage } from "../storage/types.js";
+import type { EventMap, EventName } from "../wire/events.js";
+import type { AttachmentOutcome, MessageInput, ProblemFact, RunOutcome, RunState, UsageSnapshot } from "../wire/states.js";
+import type { RunRegistry } from "./RunRegistry.js";
+import type { Clock, ScopeRegistry } from "./ScopeRegistry.js";
+/** 消息仓储里本文件用到的部分（`MessageRepository` 结构上满足） */
+export interface MessageStore {
+    upsert(input: MessageUpsertInput): Promise<void>;
+    upsertMany(inputs: MessageUpsertInput[]): Promise<void>;
+    /**
+     * 按对话取主线消息。
+     *
+     * 历史装载传 `includeHidden`（`hidden` 的消息也在模型的上下文里，只是不给人看）；
+     * 其余用途默认只要用户看得到的那部分。
+     */
+    listByConversation(conversationId: string, after?: string, options?: {
+        includeHidden?: boolean;
+    }): Promise<StoredMessage[]>;
+}
+/** 对话仓储里本文件用到的部分（`ConversationRepository` 结构上满足） */
+export interface ConversationStore {
+    get(id: string): Promise<Conversation | undefined>;
+}
+/** 推事件：接线层把它变成 JSON-RPC 通知（`WsHub.push`） */
+export type ChatEventEmitter = <E extends EventName>(name: E, payload: EventMap[E]) => void;
+/**
+ * 装配 agent 时交给工厂的事实。
+ *
+ * 模型和助手的解析口径在 SDK 里（`createAgent` 三级解析：会话级 > 助手定义 > 全局兜底），
+ * 所以这里只给 id 与 Scope，不给「用哪个模型」的结论。
+ */
+export interface AgentBuildContext {
+    conversationId: string;
+    workspaceId: string;
+    /** 这段对话创建时定死的助手（PRD L7） */
+    agentId: string;
+    /** 这段会话现在用的模型（存在会话行上）；`null` 时交给 SDK 三级解析 */
+    modelId: string | null;
+    /**
+     * 这段会话选的思考档位名（存在会话行上）；`null` = 跟随助手定义上的那份参数。
+     *
+     * 存名不存参数：档位属于模型，同名档位在不同模型的策略表里对应不同参数，展开在装配这一刻做。
+     */
+    thinkingLevel: string | null;
+    scope: Scope;
+    /** 这一轮开始前的历史（core 原样消息），工厂可以把它当作给 agent 的初始消息 */
+    history: AgentNS.Message[];
+}
+/** 造 agent。测试注入假 agent，生产用 `createSdkAgentFactory()` */
+export type AgentFactory = (context: AgentBuildContext) => Promise<ChatAgent>;
+/**
+ * 交接服务（SDK 口径）按这一轮的装配事实现场取一个。
+ *
+ * 给 `undefined` 就是「这一轮不装交接线插件」（R50：装配处会推一条警告，不静默）。
+ */
+export type HandoffProvider = (context: AgentBuildContext) => HandoffService | undefined;
+/**
+ * 本文件驱动的那部分 agent 表面。
+ *
+ * core 的 `Agent` 与 SDK 的 `SdkAgent` 都满足它；测试里的假 agent 也满足它，
+ * 于是「一轮怎么跑」的用例不必真的连模型。
+ */
+export interface ChatAgent {
+    /** 这一轮的消息数组（内存真相；本文件只往里追加历史、读它算用量） */
+    messages: AgentNS.Message[];
+    append(message: AgentNS.Message): AgentNS.Message;
+    /** core 的 `send()`：跑完整组内循环（含多轮工具调用）后返回消息数组 */
+    send(content: AgentNS.MessageContent): Promise<AgentNS.Message[]>;
+    abort(): void;
+    /** 事件广播口（core 的 `EventBus`）；本文件只用 `on` */
+    events: {
+        on(name: string, handler: (...args: never[]) => void): unknown;
+    };
+}
+/** 把已上传的素材变成真正发出去的内容段（PRD F-H7）；不给就原样用 `input.content` */
+export interface AttachmentPreparation {
+    /** 真正发给模型的内容（已按实发模型换成文件引用 / 内联 / 文字） */
+    content: AgentNS.MessageContent;
+    attachments: AttachmentOutcome[];
+    /**
+     * 落库用的内容（消息里只存我们自己的引用：段上的 `__asset_id`）。
+     *
+     * 不给时落库的就是 `content`：不是每个注入方都有“厂商产物不能进库”这回事。
+     */
+    storedContent?: AgentNS.MessageContent;
+}
+export type AttachmentPreparer = (context: {
+    conversationId: string;
+    agentId: string;
+    modelId: string | null;
+    input: MessageInput;
+}) => Promise<AttachmentPreparation>;
+/**
+ * 历史里的素材引用还原成当前模型能吃的内容段（PRD F-H7）：每轮发送之前跑一次。
+ *
+ * 每轮都要跑一次：能不能吃跟着实发模型 / 端点变，而历史里存的是与端点无关的 `__asset_id`。
+ * 不给就原样把历史交给 agent。
+ */ export type AttachmentHistoryResolver = (context: {
+    conversationId: string;
+    modelId: string | null;
+    messages: AgentNS.Message[];
+}) => Promise<AgentNS.Message[]>;
+/**
+ * 消息落库那一刻登记「这条消息引用了哪些素材」（`conversation_assets` 关系行）。
+ *
+ * 扫的是**落库的那一份内容**（段上的 `__asset_id`），所以调用点紧跟用户消息的 upsert；
+ * 不注入时关系行就不记（引用计数少一份，删字节会晚一步）。
+ */
+export type MessageAssetLinker = (context: {
+    conversationId: string;
+    messageId: string;
+    content: AgentNS.MessageContent | undefined;
+}) => Promise<number>;
+/** 一轮的入参（`conversation.send` 的 params 去掉 wire 外壳） */
+export interface ChatRunParams {
+    conversationId: string;
+    input: MessageInput;
+    /** 这一轮是哪条连接发起的语言（D8；缺省用注入的默认语言） */
+    language?: Language;
+}
+/**
+ * 一轮结算之后的事实（R59：交接线问题由宿主自己在这个时机问）。
+ *
+ * 「到交接线了没有」只在宿主算得出来：`promptTokens` 是这一轮实际用量，`handoffTokens`
+ * 是生效模型上配的那条线（0 表示这个模型没配）。带着 `language` 一起给，是因为问用户的话
+ * 要按发起这条连接的语言渲染（D8）。
+ */
+export interface TurnSettledFacts {
+    conversationId: string;
+    outcome: RunOutcome;
+    /** 这一轮的 `prompt_tokens`（结算快照里的本轮用量） */
+    promptTokens: number;
+    /** 生效模型的交接线；`0` 表示没配 */
+    handoffTokens: number;
+    language: Language;
+}
+/** 受理之后立刻给客户端的东西（PRD F-I12 / L6） */
+export interface ChatTurn {
+    conversationId: string;
+    userMessageId: string;
+    assistantMessageId: string;
+    /** 每个附件这一轮最后是怎么走的 */
+    attachments: AttachmentOutcome[];
+    /** 受理时刻（ISO 8601） */
+    acceptedAt: string;
+    /** 结算之后 resolve（写库、释放 agent 与 Scope、推结算态都已完成） */
+    readonly done: Promise<TurnSettlement>;
+    /** 中止这一轮（与 `conversation.abort` 走同一条路：用户显式动作，PRD D14） */
+    abort(reason?: string): void;
+    /**
+     * 此刻的现场快照（六态、子 Agent、用量）。
+     *
+     * 重连的客户端拉 `conversation.state` 时用这一份（PRD L5）；它读的是这一轮自己的内存，
+     * 不是第二份「谁在跑」：那个事实只在 `RunRegistry`。
+     */
+    runState(): RunState;
+}
+/** 一轮的结局 */
+export interface TurnSettlement {
+    conversationId: string;
+    assistantMessageId: string;
+    outcome: RunOutcome;
+    problem: ProblemFact | null;
+    /** 这一轮结束后内存里的全部消息（历史 + 本轮产出，core 原样） */
+    messages: AgentNS.Message[];
+    /** 这一轮产出的消息（写进库里的就是这些） */
+    produced: AgentNS.Message[];
+    usage: UsageSnapshot;
+    run: RunState;
+}
+/** 装载/重启后的修复结果 */
+export interface ReconcileResult {
+    /** 修好之后的消息（顺序即对话顺序，core 原样） */
+    messages: AgentNS.Message[];
+    /** 被改写的消息 id（状态或 `omit` 变了） */
+    repairedIds: string[];
+}
+export interface ChatRunnerOptions {
+    messages: MessageStore;
+    conversations: ConversationStore;
+    scopes: ScopeRegistry;
+    runs: RunRegistry;
+    /** 造 agent 的工厂；不注入时按 SDK 口径装配（交接服务由 `handoff` 提供） */
+    createAgent?: AgentFactory;
+    /**
+     * 交接服务：注入之后每一轮都装交接线插件（R59 / R50）；不注入时那个插件就不装。
+     *
+     * 只在不注入 `createAgent` 时生效（两边都注入时以 `createAgent` 为准）。
+     */
+    handoff?: HandoffProvider;
+    emit: ChatEventEmitter;
+    clock?: Clock;
+    /** 宿主分配消息 id；缺省用 `crypto.randomUUID` */
+    newId?: () => string;
+    /** 边流边写的节流时长（毫秒）；0 表示每到一片就写一次 */
+    streamWriteIntervalMs?: number;
+    prepareAttachments?: AttachmentPreparer;
+    /**
+     * 历史里的素材引用 → 当前模型能吃的段（F-H7）。不给时历史原样交给 agent。
+     *
+     * 与 `prepareAttachments` 分开两个注入点，是因为它们错在不同时机：一个在受理时算一次，
+     * 一个是每次装配 agent 之前按当时的模型 / 端点算。
+     */
+    prepareHistory?: AttachmentHistoryResolver;
+    /**
+     * 用户消息落库那一刻登记素材关系行（`conversation_assets`）。不注入就不记。
+     */
+    linkMessageAssets?: MessageAssetLinker;
+    /** 这一轮没带语言时用哪种语言渲染宿主注入的那段话（D8） */
+    defaultLanguage?: Language;
+    /** 一轮结算之后的回调（R59：交接线问题由它触发） */
+    onTurnSettled?: (facts: TurnSettledFacts) => void;
+    /** 内部错误的去处（写库失败、回收失败等）；缺省忽略 */
+    onError?: (error: unknown, context: string) => void;
+}
+/** 边流边写的缺省节流：200ms 一次，兼顾「客户端断了丢得少」与「写盘次数」 */
+export declare const DEFAULT_STREAM_WRITE_INTERVAL_MS = 200;
+/**
+ * 会话创建时那条 cwd 消息的正文（PRD F-D9：告诉模型「当前目录是哪儿」）。
+ *
+ * 这条消息在对话落库时写一次，之后不再重写、也不随每轮拼接（说了两遍模型会以为目录变了）。
+ * 目录取的是这个对话所属项目的 cwd（不是进程工作目录）；句子用的是「这是宿主加的，不是
+ * 用户输入的」那条文案（R21：不新造消息类型）。
+ */
+export declare function injectedContextOf(cwd: string, language: Language): string;
+export declare class ChatRunner {
+    private readonly options;
+    private readonly clock;
+    /**
+     * 正在跑的轮次（对话 id → 那一轮的现场）。
+     *
+     * 存的是**这一轮自己的内存对象**，供 `conversation.state` 拿到流中的六态与用量；
+     * 「有没有在跑」仍然只问 `RunRegistry.isRunning`，两张表不由这里合并。
+     */
+    private readonly turns;
+    constructor(options: ChatRunnerOptions);
+    /** 宿主分配消息 id（PRD L6）：缺省 `crypto.randomUUID`，测试可注入递增 id */
+    private newId;
+    /** 缺省的 agent 工厂（不注入 `createAgent` 时用）：按 SDK 口径装配，交接服务来自 `handoff` */
+    private agentFactory;
+    /**
+     * 受理一轮：占位、落两条消息、把执行放到后台，然后把两个 id 还给调用方（PRD L6 / F-I12）。
+     *
+     * 忙即拒（`HostError("busy")`，D14）；对话不存在则 `not_found`。任何一种失败都不会
+     * 留下一个占着不动的轮次，也不会让 Scope 的依赖计数多算一次。
+     */
+    run(params: ChatRunParams): Promise<ChatTurn>;
+    /**
+     * 历史装载完之后的第一件事情：把里面的 `__asset_id` 还原成当前模型能吃的段（F-H7）。
+     *
+     * 还原失败不让整轮发不出去：打一条日志、带着原样的历史继续。
+     */
+    private resolveHistory;
+    /**
+     * 用户消息落库之后登记素材关系行（`conversation_assets`）。
+     *
+     * 记不下来不让这一轮失败（消息已经发出去了）：打一条日志继续 —— 后果只是这份素材的
+     * 引用计数少一行，删字节会晚一步。
+     */
+    private linkMessageAssets;
+    /** 这一段对话正在跑的那一轮（没有就 `undefined`）：拉现场用 */
+    turn(conversationId: string): ChatTurn | undefined;
+    /** 中止（转发给 `RunRegistry`：中止的唯一入口在那里） */
+    abort(conversationId: string, reason?: string): boolean;
+    /**
+     * 对话（或它所在的项目）被删之后，把这一轮的内存现场丢掉。
+     *
+     * 正在跑的那一轮会先被要求停下，再等它自己结算写库（删对话的人已经先确认过代价）。
+     */
+    forget(conversationId: string): void;
+    /**
+     * 装载/重启后修复（PRD D15）。
+     *
+     * 两步：
+     *   1. 在途（`pending` / `writing`）消息当作被中断 —— 进程是在写它们的时候没的；
+     *   2. 交 core 的两支归一：工具轮次 `fill`（整轮进出，补上未完成的原因）、
+     *      被中断的 assistant `keep`（已输出的内容留在上下文里，模型下一轮能接着半截说）。
+     *
+     * 只写回状态/`omit` 真的变了的那些行，于是「启动时扫一遍」不会把整段历史重写一次。
+     */
+    reconcile(conversationId: string): Promise<ReconcileResult>;
+    private prepare;
+}
+export interface SdkAgentFactoryOptions {
+    /**
+     * 交接服务（写交接文档 + 迁移）。给了才装交接线插件（`AutoMigratePlugin`）；
+     * 交接服务自己会在交接回合往 agent 上装工具守卫。
+     */
+    handoff?: HandoffProvider;
+    /**
+     * 工具刷新时机；缺省读 SDK 配置的 `autoRefreshTools`，再缺省 `inner-loop-start`。
+     *
+     * 取值直接用 SDK `AppConfig` 里那一字段的类型，不在这里再定义一份（`off` 表示不装插件）。
+     */
+    autoRefreshTools?: AppConfig["autoRefreshTools"];
+    /**
+     * 思考策略表（档位名 → 参数补丁）的现读入口。
+     *
+     * 装配是异步的，所以这里给一个取快照的函数而不是快照本身：接线层在配置变更后会重新
+     * 读一次表（`refreshThinkingPresets`），拿旧快照会把已删掉的档位展开成空补丁。
+     */
+    thinkingPresets?: () => ReasoningPresets | null;
+}
+/**
+ * 这一段会话该带哪些模型参数（PRD F-B6）。
+ *
+ * 两件事合在这里：
+ *   1. 助手定义上的 `modelParams`（用户给这个助手配的参数，也是「跟随默认」所指的那份）；
+ *   2. 会话行上的思考档位展开出的补丁（档位名 → 参数），盖在 1 上面。
+ *
+ * 只在「会话定的模型就是助手定义那个模型」时才叠上 1：会话把模型换掉之后，定义上那份参数
+ * 是配给旧模型的（可能带着旧模型才认的键），发给新模型只会换来一句 400。换模型时档位会被
+ * 清空，所以那之后这里通常什么都不带，让模型走自己的出厂参数。
+ */
+export declare function conversationModelParams(input: {
+    /** 会话行上的模型（从 `scope.config` 里找到的那个；找不到时为空） */
+    model: Model | undefined;
+    /** 助手定义上的模型 id（未绑定时为 `undefined`） */
+    agentModelId: string | undefined;
+    /** 配置里的兜底模型（`AppConfig.defaultModel`） */
+    defaultModelId: string | undefined;
+    /** 助手定义上的参数（`AgentDefinition.modelParams`） */
+    agentParams: ModelParams | undefined;
+    /** 会话行上的思考档位名；`null` = 跟随助手定义 */
+    thinkingLevel: string | null;
+    presets: ReasoningPresets | null;
+}): ModelParams | undefined;
+/**
+ * 造一个按 SDK 口径装配的 agent 工厂。
+ *
+ * 装的东西与阈值来源（PRD D27：阈值属 SDK 的 `AppConfig` / 模型配置，不在这里另起一套）：
+ *   - `ContextGuardPlugin`：硬线，`tokenThresholds.guard`；
+ *   - `SubAgentGuardInstallerPlugin`：同一个硬线递归装到子 Agent 与孙级（PRD F-D8）；
+ *   - `AutoMigratePlugin`：交接线，`tokenThresholds.handoff`（需注入交接服务）；
+ *   - `AutoRefreshToolsPlugin`：改完能力不用重启（PRD F-E2）；
+ *   - `UnknownToolHintPlugin`：未知工具时给出 MCP 场景的引导。
+ */
+export declare function createSdkAgentFactory(options?: SdkAgentFactoryOptions): AgentFactory;