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

package/dist/runtime/ConversationDrafts.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 会话草稿：`conversation.create` 发出去的那段对话，在第一条用户消息之前只活在这里（R56）。
+ *
+ * PRD F-C2 的原话是「没有用户消息就不写」，所以创建时不落 `conversations` 行：这里只记住
+ * **id 与已经定死的身份**（项目 / 助手，PRD L7；模型与思考档位也在这份行里，只是它们可以改）。
+ * 首次 `conversation.send` 时由对话服务把这一份原样写进库，之后这段对话就与「创建即落库」的对话
+ * 没有区别。
+ *
+ * 两处刻意的选择：
+ *
+ * 1. **存的是存储层的行形状**（`Conversation`），不是另造一份 DTO：草稿与真行在服务层走同一批
+ *    代码路径（视图拼装、换模型、写思考档位），差别只在「有没有写进库」。
+ * 2. **不持久化、不共享**：进程没了草稿就没了，这是预期结果（没发过消息的会话重连后消失）。
+ *    所以这里没有计时器，也没有落盘。
+ */
+import type { Conversation } from "../storage/types.js";
+/**
+ * 对话服务要用到的草稿读写口（结构上 {@link ConversationDrafts} 满足，用例可给替身）。
+ *
+ * 只暴露服务层真正需要的三个动作：取出、放进、扔掉；「换成一个真行」是服务层自己做的事。
+ */
+export interface ConversationDraftStore {
+    get(conversationId: string): Conversation | undefined;
+    /** 取出并摘掉（落库那一刻用：先摘再写，并发的第二次就抢不到同一份草稿） */
+    take(conversationId: string): Conversation | undefined;
+    put(draft: Conversation): void;
+    forget(conversationId: string): void;
+}
+export declare class ConversationDrafts implements ConversationDraftStore {
+    private readonly drafts;
+    get(conversationId: string): Conversation | undefined;
+    put(draft: Conversation): void;
+    /**
+     * 取出并摘掉（落库那一刻用）。
+     *
+     * 摘除与落库分开是故意的：先同步摘掉，两次并发的 `send` 里后到的那一次就看不到草稿，
+     * 不会两次插同一行。
+     */
+    take(conversationId: string): Conversation | undefined;
+    forget(conversationId: string): void;
+    /** 现在挂着几份草稿（诊断与用例用；不参与业务判断） */
+    size(): number;
+}

package/dist/runtime/ConversationDrafts.js

@@ -0,0 +1,47 @@
+/**
+ * 会话草稿：`conversation.create` 发出去的那段对话，在第一条用户消息之前只活在这里（R56）。
+ *
+ * PRD F-C2 的原话是「没有用户消息就不写」，所以创建时不落 `conversations` 行：这里只记住
+ * **id 与已经定死的身份**（项目 / 助手，PRD L7；模型与思考档位也在这份行里，只是它们可以改）。
+ * 首次 `conversation.send` 时由对话服务把这一份原样写进库，之后这段对话就与「创建即落库」的对话
+ * 没有区别。
+ *
+ * 两处刻意的选择：
+ *
+ * 1. **存的是存储层的行形状**（`Conversation`），不是另造一份 DTO：草稿与真行在服务层走同一批
+ *    代码路径（视图拼装、换模型、写思考档位），差别只在「有没有写进库」。
+ * 2. **不持久化、不共享**：进程没了草稿就没了，这是预期结果（没发过消息的会话重连后消失）。
+ *    所以这里没有计时器，也没有落盘。
+ */
+export class ConversationDrafts {
+    drafts = new Map();
+    get(conversationId) {
+        return this.drafts.get(conversationId);
+    }
+    put(draft) {
+        const id = typeof draft.id === "string" ? draft.id.trim() : "";
+        if (id === "")
+            return;
+        this.drafts.set(id, { ...draft, id });
+    }
+    /**
+     * 取出并摘掉（落库那一刻用）。
+     *
+     * 摘除与落库分开是故意的：先同步摘掉，两次并发的 `send` 里后到的那一次就看不到草稿，
+     * 不会两次插同一行。
+     */
+    take(conversationId) {
+        const draft = this.drafts.get(conversationId);
+        if (!draft)
+            return undefined;
+        this.drafts.delete(conversationId);
+        return draft;
+    }
+    forget(conversationId) {
+        this.drafts.delete(conversationId);
+    }
+    /** 现在挂着几份草稿（诊断与用例用；不参与业务判断） */
+    size() {
+        return this.drafts.size;
+    }
+}

package/dist/runtime/RunRegistry.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `RunRegistry` —— 「这段对话正在跑哪一轮」的唯一一处（architecture §4 / PRD D14）。
+ *
+ * 为什么要有它：一段对话同时跑一轮（PRD D14）。再来请求时**直接拒**并说明「正忙」，
+ * 不排队也不自动打断 —— 中止是用户的显式动作，只有用户能按。
+ *
+ * 为什么它是注册表而不是散在服务里的布尔：服务层要问「现在忙不忙」，接线层的
+ * `conversation.abort` 要找到那一轮去中止；两处问的必须是同一份事实，所以只留一处
+ * （`isRunning` 只有这里一个实现，见 PRD D14）。服务层只需要窄接口 `RunsView`，
+ * 本类结构上就满足它，不必包一层。
+ *
+ * 环的内存真相在 `ChatRunner` 那一轮自己手里（消息、生成态），本文件只记「谁在跑」——
+ * 跑的内容不往这里存第二份。
+ */
+import type { Clock } from "./ScopeRegistry.js";
+/** 一轮的开始时刻与中止状态：`list()` 与重连快照要用的最小事实 */
+export interface RunSummary {
+    conversationId: string;
+    /** ISO 8601 */
+    startedAt: string;
+    /** 用户是否已经要求中止（中止请求已送达，那一轮还没结算） */
+    aborted: boolean;
+}
+/**
+ * 一轮的句柄：拿到它的人可以中止这一轮。
+ *
+ * 中止是注册表转达给执行者的（`onAbort`）：注册表不认识 Agent，执行者才认识；
+ * 这样「谁在跑」与「怎么停」各自只有一处。
+ */
+export interface RunHandle extends RunSummary {
+    /** 用户是否已经要求中止 */
+    readonly aborted: boolean;
+    /**
+     * 要求中止。
+     *
+     * 重复调用无副作用；中止之后仍然等执行者写库、结算才算真正结束（`finish` 由执行者叫）。
+     */
+    abort(reason?: string): void;
+    /**
+     * 登记中止时要做什么（执行者在这里挂 `agent.abort()`）。返回取消登记的函数。
+     *
+     * 允许在 `abort()` 之后才登记：那样会立刻执行一次，免得「中止来得太早」被丢掉。
+     */
+    onAbort(listener: (reason: string | undefined) => void): () => void;
+}
+/** 服务层要用窄接口：只问忙不忙（`RunRegistry` 直接满足，不必适配） */
+export interface RunsView {
+    isRunning(conversationId: string): boolean;
+}
+export interface RunRegistryOptions {
+    /** 计时入口，缺省真实时钟（`startedAt` 与测试里的假时间用它） */
+    clock?: Clock;
+}
+export declare class RunRegistry implements RunsView {
+    private readonly runs;
+    private readonly clock;
+    constructor(options?: RunRegistryOptions);
+    /**
+     * 占位：这段对话开始跑一轮。
+     *
+     * 已经在跑就抛 `HostError("busy")` —— PRD D14：直接拒并说明「正忙」，不排队、不自动打断。
+     * `detail` 带上「上一次是什么时候开始的」，让界面能说清「它在忙什么」而不是干巴巴一句忙。
+     */
+    start(conversationId: string): RunHandle;
+    /** 结算：这一轮结束（正常、出错、被中止都走这里）。返回是否真的有这一轮 */
+    finish(conversationId: string): boolean;
+    /** 这段对话现在忙不忙 —— 服务层注入的就是这个方法 */
+    isRunning(conversationId: string): boolean;
+    /** 当前在跑的全部轮次（根对象判「能不能退出」时用） */
+    list(): RunSummary[];
+    /**
+     * 按对话中止（接线层的 `conversation.abort` 用）：返回是否真的有在跑的一轮。
+     *
+     * `false` 表示本来就没在跑 —— 那不是错误，客户端只是按了一下没东西可停的按钮。
+     */
+    abort(conversationId: string, reason?: string): boolean;
+    /** 正在跑的轮次数量 */
+    size(): number;
+}

package/dist/runtime/RunRegistry.js

@@ -0,0 +1,108 @@
+/**
+ * `RunRegistry` —— 「这段对话正在跑哪一轮」的唯一一处（architecture §4 / PRD D14）。
+ *
+ * 为什么要有它：一段对话同时跑一轮（PRD D14）。再来请求时**直接拒**并说明「正忙」，
+ * 不排队也不自动打断 —— 中止是用户的显式动作，只有用户能按。
+ *
+ * 为什么它是注册表而不是散在服务里的布尔：服务层要问「现在忙不忙」，接线层的
+ * `conversation.abort` 要找到那一轮去中止；两处问的必须是同一份事实，所以只留一处
+ * （`isRunning` 只有这里一个实现，见 PRD D14）。服务层只需要窄接口 `RunsView`，
+ * 本类结构上就满足它，不必包一层。
+ *
+ * 环的内存真相在 `ChatRunner` 那一轮自己手里（消息、生成态），本文件只记「谁在跑」——
+ * 跑的内容不往这里存第二份。
+ */
+import { HostError } from "../wire/errors.js";
+import { systemClock } from "./ScopeRegistry.js";
+/** 一轮的内部记录 */
+class Run {
+    conversationId;
+    startedAt;
+    /** 中止原因（用户没给就是 undefined） */
+    abortReason;
+    abortRequested = false;
+    abortListeners = new Set();
+    constructor(conversationId, clock) {
+        this.conversationId = conversationId;
+        this.startedAt = new Date(clock.now()).toISOString();
+    }
+    get aborted() {
+        return this.abortRequested;
+    }
+    abort(reason) {
+        if (this.abortRequested)
+            return;
+        this.abortRequested = true;
+        this.abortReason = reason;
+        for (const listener of [...this.abortListeners])
+            listener(reason);
+    }
+    onAbort(listener) {
+        this.abortListeners.add(listener);
+        // 中止已经发生过了：登记得太晚也要收到，否则执行者会一直以为没人叫它停
+        if (this.abortRequested)
+            listener(this.abortReason);
+        return () => {
+            this.abortListeners.delete(listener);
+        };
+    }
+    summary() {
+        return {
+            conversationId: this.conversationId,
+            startedAt: this.startedAt,
+            aborted: this.abortRequested,
+        };
+    }
+}
+export class RunRegistry {
+    runs = new Map();
+    clock;
+    constructor(options = {}) {
+        this.clock = options.clock ?? systemClock;
+    }
+    /**
+     * 占位：这段对话开始跑一轮。
+     *
+     * 已经在跑就抛 `HostError("busy")` —— PRD D14：直接拒并说明「正忙」，不排队、不自动打断。
+     * `detail` 带上「上一次是什么时候开始的」，让界面能说清「它在忙什么」而不是干巴巴一句忙。
+     */
+    start(conversationId) {
+        const existing = this.runs.get(conversationId);
+        if (existing) {
+            throw new HostError("busy", {
+                detail: { conversationId, startedAt: existing.startedAt, aborted: existing.aborted },
+            });
+        }
+        const run = new Run(conversationId, this.clock);
+        this.runs.set(conversationId, run);
+        return run;
+    }
+    /** 结算：这一轮结束（正常、出错、被中止都走这里）。返回是否真的有这一轮 */
+    finish(conversationId) {
+        return this.runs.delete(conversationId);
+    }
+    /** 这段对话现在忙不忙 —— 服务层注入的就是这个方法 */
+    isRunning(conversationId) {
+        return this.runs.has(conversationId);
+    }
+    /** 当前在跑的全部轮次（根对象判「能不能退出」时用） */
+    list() {
+        return [...this.runs.values()].map((run) => run.summary());
+    }
+    /**
+     * 按对话中止（接线层的 `conversation.abort` 用）：返回是否真的有在跑的一轮。
+     *
+     * `false` 表示本来就没在跑 —— 那不是错误，客户端只是按了一下没东西可停的按钮。
+     */
+    abort(conversationId, reason) {
+        const run = this.runs.get(conversationId);
+        if (!run)
+            return false;
+        run.abort(reason);
+        return true;
+    }
+    /** 正在跑的轮次数量 */
+    size() {
+        return this.runs.size;
+    }
+}

package/dist/runtime/ScopeRegistry.d.ts

@@ -0,0 +1,153 @@
+/**
+ * `ScopeRegistry` —— workspaceId → `Scope` 的持有者、依赖计数与空闲回收（architecture §4 / PRD D28）。
+ *
+ * 一个 Workspace 一个 Scope（PRD D9）：同一 Workspace 下的多段对话复用同一个 Scope，
+ * 所以这里记的是**依赖计数**而不是「谁在打开它」。计数归零之后不立刻拆，而是起一个
+ * 10 分钟的空闲计时；计时到点才真正销毁 —— 销毁就是 `Scope.dispose()`，它会逆序调用各插件的
+ * `dispose()`，MCP 插件在那里断开它自持的全部连接，于是「Scope 与 MCP 连接同生共死」
+ * 不用第二套代码来表达。
+ *
+ * 计时器只有这一处（architecture §4 A10）：L4 说的「10 分钟无活动」与 D28 说的
+ * 「Scope 空闲 10 分钟」是同一个计时器的两个说法，别处不再另起一份。
+ *
+ * Scope 会被销毁的三种场合（architecture §4）：空闲到点、Workspace 被删、配置变更要重连 MCP。
+ * 三者都收敛到本文件的 `dispose`，区别只在「谁来叫」。
+ *
+ * 时间与 Scope 的创建方式都从构造参数进来：测试用假时钟推进十分钟，接线层提供真实的
+ * SDK 装配（见本文件末尾的 `createWorkspaceScopeFactory`）。
+ */
+import type { AppConfig, ToolEnvDeps } from "@ai-zen/agents-sdk";
+import { Scope } from "@ai-zen/agents-sdk";
+/** 空闲回收的缺省时长：10 分钟（PRD D28） */
+export declare const DEFAULT_SCOPE_IDLE_TIMEOUT_MS: number;
+/**
+ * 计时入口。
+ *
+ * `setTimeout` 返回「取消函数」而不是句柄：假时钟与真定时器都能实现它，调用方不必知道
+ * 句柄长什么样，也就不需要 `clearTimeout` 的第二个入口。
+ */
+export interface Clock {
+    /** 当前时刻（毫秒，`Date.now()` 口径） */
+    now(): number;
+    /** 到点后执行 `handler`，返回取消函数 */
+    setTimeout(handler: () => void, ms: number): () => void;
+}
+/**
+ * 真实时钟。无状态，可以放心共享；需要可控时间的地方（测试、或将来把时钟挂到根对象上）
+ * 通过构造参数换成别的实现。
+ */
+export declare const systemClock: Clock;
+/**
+ * 造一个 Scope 的方式（按 workspaceId）。
+ *
+ * 之所以是外部注入而不是本文件自己 `new Scope(...)`：装配 Scope 需要配置快照、能力路径、
+ * MCP 配置的 5 层链（PRD L9）—— 那些都是配置层的财产；本文件只管「什么时候有、什么时候拆」。
+ * 接线层若不想自己写，用本文件末尾的 `createWorkspaceScopeFactory`。
+ */
+export type ScopeFactory = (workspaceId: string) => Promise<Scope>;
+export interface ScopeRegistryOptions {
+    /** 懒创建：只有 `acquire` 到不存在的 workspaceId 时才叫它 */
+    createScope: ScopeFactory;
+    /** 空闲回收时长，缺省 10 分钟 */
+    idleTimeoutMs?: number;
+    /** 计时入口，缺省真实时钟 */
+    clock?: Clock;
+    /** 销毁 Scope 时抛出的错误往哪里报（缺省吞掉：回收失败不该让调用方以为业务失败了） */
+    onError?: (error: unknown, workspaceId: string) => void;
+}
+export declare class ScopeRegistry {
+    private readonly entries;
+    private readonly createScope;
+    private readonly idleTimeoutMs;
+    private readonly clock;
+    private readonly onError?;
+    private readonly allRecycledListeners;
+    constructor(options: ScopeRegistryOptions);
+    /**
+     * 借一个 Scope：没有就懒创建，依赖计数 +1，并取消空闲计时。
+     *
+     * 并发的两次 `acquire` 只会创建一次（两个调用方等同一个 Promise）。
+     */
+    acquire(workspaceId: string): Promise<Scope>;
+    /** 创建失败时不留下坏条目：下一次 acquire 重新尝试 */
+    private create;
+    /**
+     * 归还：依赖计数 −1。归零后按两种场合分叉 ——
+     * 平时起 10 分钟空闲计时；若期间发生过配置变更（`recycleAll`）要求它重建，就立刻销毁。
+     */
+    release(workspaceId: string): void;
+    /** 看而不借：已经建好就返回它，没有或还在建就返回 `undefined` */
+    peek(workspaceId: string): Scope | undefined;
+    /** 当前持有几个 Scope（含正在创建的） */
+    size(): number;
+    /** 当前持有哪几个（配置改动后要报告「回收了哪些项目的 Scope」） */
+    workspaceIds(): string[];
+    /**
+     * 全部回收 —— 配置改完要重连 MCP 时用（PRD F-E2：改完即生效，靠重连而不是重启）。
+     *
+     * 没人用的立刻销毁；正被持有的打上标记，等最后一次 `release` 再销毁。这样正在跑的那一轮
+     * 不会在写到一半时被抽掉能力，而它结束后下一段对话拿到的已经是按新配置建的 Scope。
+     */
+    recycleAll(): Promise<void>;
+    /**
+     * 销毁某一个 Workspace 的 Scope —— Workspace 被删时用。
+     *
+     * 与 `recycleAll` 的区别：这里不等引用归零，因为 Workspace 已经不在了，
+     * 再留着这个 Scope 也没有下一个调用方。
+     */
+    disposeWorkspace(workspaceId: string): Promise<void>;
+    /**
+     * 全部回收之后通知根对象（architecture §4：根对象据此判断进程能不能退出）。
+     *
+     * 返回取消订阅的函数。
+     */
+    onAllRecycled(listener: () => void): () => void;
+    private scheduleIdle;
+    private cancelIdle;
+    /**
+     * 销毁：先把条目从表里摘掉（之后 acquire 会重建），再等创建完成并 `dispose()`。
+     *
+     * 创建还没完成就得销毁时也要等它 —— 否则刚建出来的 Scope 没人拆，MCP 连接会漏。
+     */
+    private dispose;
+    private doDispose;
+    private notifyAllRecycled;
+}
+/**
+ * 按 SDK 口径装配 Scope 的现成工厂。
+ *
+ * 装配内容：`new Scope({ config, cwd, agentsDir })` + `allInOne(...)`（内置工具、用户工具、
+ * Skill、MCP、子 Agent 五类插件），然后 `init()` 做首次能力发现。MCP 插件自带连接管理器，
+ * 于是「Scope 建好 = MCP 配置已发现」，`dispose()` 时连接一起断。
+ *
+ * 工作目录、配置、各能力路径都由接线层给：本文件不去问进程当前目录，也不猜数据根。
+ */
+export interface WorkspaceScopeFactoryOptions {
+    /** 按 workspaceId 取工作目录（Workspace 的 cwd 不可变，PRD D9） */
+    resolveWorkspace(workspaceId: string): Promise<{
+        cwd: string;
+    } | undefined>;
+    /** 取当前配置：配置改过之后再 acquire 会拿到新的那一份 */
+    getConfig(): AppConfig | Promise<AppConfig>;
+    /** Agent 定义目录（SDK 的 `createAgent` 从这里读定义） */
+    agentsDir: string;
+    /** Skill 目录（可多层，越靠前优先级越高）；也能给一个「按 cwd 算」的函数 */
+    skillsPaths?: AbilityPathOption;
+    /** 用户工具目录 */
+    toolsPaths?: AbilityPathOption;
+    /** 子 Agent 目录 */
+    subAgentsPaths?: AbilityPathOption;
+    /** MCP 配置文件的 5 层链（PRD L9），按 cwd 算好 */
+    mcpPaths?: (cwd: string) => string[];
+    /** 出网/外部依赖的注入点（测试替身） */
+    deps?: ToolEnvDeps;
+}
+/**
+ * 一组能力目录：可以是固定的一份，也可以是「按 cwd 算」的函数。
+ *
+ * Skill / 工具 / 子 Agent 的目录跟项目走（L9：离项目越近越优先），而 Scope 是按 cwd 装配的，
+ * 所以装配处需要把「按 cwd 算」这件事交进来，而不是在构造时先算一份死的。
+ */
+export type AbilityPathOption = string[] | ((cwd: string) => string[]);
+/** 造一个「按 SDK 装能力」的工厂；返回值直接喂给 `ScopeRegistry` 的 `createScope` */
+export declare function createWorkspaceScopeFactory(options: WorkspaceScopeFactoryOptions): ScopeFactory;