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

package/dist/services/CredentialService.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 凭证服务：多串访问凭证的列出、新建、吊销。
+ *
+ * 对应能力编号：L11（凭证靠复制 + 手动输入、可以有多串、创建时带备注、权限相同、可单独吊销）、
+ * F-E4（直达入口里的一项）。不做账号与按人分权限（L12）—— 凭证代表的是「一台设备」。
+ *
+ * 明文的去处只有一处：`create` 的返回值。库里存的是 `hashCredential` 算出的摘要，服务层
+ * 拿不到明文也就无法再吐出来第二次（吊销用 id，不用明文）。
+ */
+import type { CredentialRepository } from "../storage/CredentialRepository.js";
+import type { CredentialCreateParams, CredentialCreateResult, CredentialListResult, CredentialRevokeParams, CredentialRevokeResult } from "../wire/index.js";
+/** 凭证服务依赖 */
+export interface CredentialServiceDeps {
+    credentials: CredentialRepository;
+    /** 时钟，测试注入用；缺省 `Date.now` */
+    now?: () => number;
+}
+export declare class CredentialService {
+    private readonly credentials;
+    private readonly now;
+    constructor(deps: CredentialServiceDeps);
+    /** 列出全部凭证（含已吊销的，吊销状态在 `revokedAt` 上） */
+    list(): Promise<CredentialListResult>;
+    /** 新建一串：备注自己写，明文只在这个返回值里出现一次 */
+    create(params: CredentialCreateParams): Promise<CredentialCreateResult>;
+    /**
+     * 吊销一串（置 `revokedAt`，不删行：留着能看出这串曾经存在过）。
+     *
+     * `revoked` 表示这次调用是否真的改动了库：对一串已经吊销过的凭证再吊销一次，返回 false
+     * 而不是报错（端状态一样是「已吊销」）。
+     */
+    revoke(params: CredentialRevokeParams): Promise<CredentialRevokeResult>;
+}

package/dist/services/CredentialService.js

@@ -0,0 +1,86 @@
+/**
+ * 凭证服务：多串访问凭证的列出、新建、吊销。
+ *
+ * 对应能力编号：L11（凭证靠复制 + 手动输入、可以有多串、创建时带备注、权限相同、可单独吊销）、
+ * F-E4（直达入口里的一项）。不做账号与按人分权限（L12）—— 凭证代表的是「一台设备」。
+ *
+ * 明文的去处只有一处：`create` 的返回值。库里存的是 `hashCredential` 算出的摘要，服务层
+ * 拿不到明文也就无法再吐出来第二次（吊销用 id，不用明文）。
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { hashCredential } from "../storage/CredentialRepository.js";
+import { HostError } from "../wire/errors.js";
+/** 明文凭证的字节数（base64url 编码后 43 个字符） */
+const TOKEN_BYTES = 32;
+/** 时间戳转 wire 上的 ISO 8601 */
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+/** 库里的一行 → 对外视图（不含摘要） */
+function toView(row) {
+    return {
+        id: row.id,
+        note: row.note,
+        createdAt: iso(row.createdAt),
+        revokedAt: row.revokedAt === null ? null : iso(row.revokedAt),
+    };
+}
+export class CredentialService {
+    credentials;
+    now;
+    constructor(deps) {
+        this.credentials = deps.credentials;
+        this.now = deps.now ?? Date.now;
+    }
+    /** 列出全部凭证（含已吊销的，吊销状态在 `revokedAt` 上） */
+    async list() {
+        const rows = await this.credentials.list();
+        return { credentials: rows.map((row) => toView(row)) };
+    }
+    /** 新建一串：备注自己写，明文只在这个返回值里出现一次 */
+    async create(params) {
+        const note = typeof params.note === "string" ? params.note.trim() : "";
+        const token = randomBytes(TOKEN_BYTES).toString("base64url");
+        const id = randomUUID();
+        const createdAt = this.now();
+        await this.credentials.create({
+            id,
+            note,
+            hash: hashCredential(token),
+            createdAt,
+        });
+        const row = await this.credentials.get(id);
+        if (!row) {
+            throw new HostError("internal", { detail: { reason: "credential vanished after insert", id } });
+        }
+        return {
+            credential: {
+                id: row.id,
+                note: row.note,
+                createdAt: iso(row.createdAt),
+                revokedAt: row.revokedAt === null ? null : iso(row.revokedAt),
+            },
+            token,
+        };
+    }
+    /**
+     * 吊销一串（置 `revokedAt`，不删行：留着能看出这串曾经存在过）。
+     *
+     * `revoked` 表示这次调用是否真的改动了库：对一串已经吊销过的凭证再吊销一次，返回 false
+     * 而不是报错（端状态一样是「已吊销」）。
+     */
+    async revoke(params) {
+        const id = typeof params.credentialId === "string" ? params.credentialId.trim() : "";
+        const row = id.length === 0 ? undefined : await this.credentials.get(id);
+        if (!row) {
+            throw new HostError("not_found", {
+                params: { entity: "credential" },
+                detail: { credentialId: params.credentialId },
+            });
+        }
+        if (row.revokedAt !== null)
+            return { revoked: false };
+        const changes = await this.credentials.revoke(row.id, this.now());
+        return { revoked: changes > 0 };
+    }
+}

package/dist/services/DiscoveryService.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 能力发现服务：把「这个项目现在能用哪些 MCP / Skill / 工具 / 子 Agent」摊成分层清单。
+ *
+ * 对应能力编号：F-G1（MCP 5 层链，可编辑的只有 2 个作用域）、F-G2（Skill 4 层、工具与子 Agent
+ * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件要能看见、能修）、
+ * L9（MCP 的 5 层链）、R54（5 层链与各能力目录由本服务算好交给 ScopeRegistry）。
+ *
+ * 三件事分开：
+ *
+ *   1. **路径**（{@link DiscoveryService.scopeAbilityPaths} 等）：只有「按 cwd 推出各能力应该去
+ *      哪些目录 / 文件找」这一件事，与有没有东西在里面无关。组装层（ScopeRegistry 的
+ *      `createWorkspaceScopeFactory`）拿的就是这些路径。
+ *   2. **读**（{@link DiscoveryService.discover}）：把每一层的 `missing | ok | broken` 与条目
+ *      报出来。`missing` 与 `broken` 必须分开（F-F6）：以前两者都当空配置，一保存就把用户的
+ *      文件覆盖掉了。
+ *   3. **写**（{@link DiscoveryService.writeMcpEntry} / {@link DiscoveryService.deleteMcpEntry}）：
+ *      只写 MCP 的两个可编辑作用域，一次只动一条；写回时保留这一版不认识的字段与 `oauth`
+ *      （F-F6），其中 `oauth.clientSecret` 省略就按磁盘原文保留（F-F2：读出去的是掩码，
+ *      回写掩码就是把掩码当密钥存下来）。
+ *
+ * 判断「近的优先」用的是层序 `depth`（0 最靠近项目）：合并时同 id 取 depth 小的那一层，
+ * 被盖住的条目仍然出现在它自己那一层里，只是带上一条「被谁覆盖」的问题说明。
+ */
+import type { ConfigManager, McpServerConfig } from "@ai-zen/agents-sdk";
+import type { ConfigGetDiscoveryParams, ConfigGetDiscoveryResult, DiscoveryLayerView, McpEditableScope, McpServerEntryInput } from "../wire/index.js";
+/** 一层发现来源：层序、绝对路径、能不能写、属于谁 */
+export interface DiscoveryLayerPath {
+    /** 层序：0 最靠近项目，数字越大越远（合并时近的优先） */
+    depth: number;
+    /** 这一层对应的文件或目录的绝对路径 */
+    path: string;
+    /** 本契约的写方法能不能改这一层（F-G1：MCP 只有 2 层可以） */
+    editable: boolean;
+    /** 写入时用哪个作用域；不能写时为 `null` */
+    scope: McpEditableScope | null;
+    /** 这一层归谁：项目、用户数据根、还是别的工具约定的目录 */
+    owner: "workspace" | "user" | "other";
+}
+/**
+ * 组装一个 Scope 需要的全部能力路径（R54）。
+ *
+ * `ScopeRegistry` 的 `createWorkspaceScopeFactory` 就是按这份形状装配
+ * `new Scope({ agentsDir, ... })` 与 `allInOne({ skillsPaths, toolsPaths, subAgentsPaths, mcpPaths })`。
+ */
+export interface ScopeAbilityPaths {
+    /** 助手定义目录（SDK 的 `createAgent` 从这里读 `<id>.json`） */
+    agentsDir: string;
+    /** Skill 目录，近的在前 */
+    skillsPaths: string[];
+    /** 用户工具目录，近的在前 */
+    toolsPaths: string[];
+    /** 子 Agent 目录，近的在前 */
+    subAgentsPaths: string[];
+    /** MCP 配置文件的 5 层链，近的在前（SDK 的 `discoverMcpServers` 按这个顺序先到先得） */
+    mcpPaths: string[];
+}
+/** 按 workspaceId 取工作目录；项目不存在时回 `undefined` */
+export type WorkspaceCwdLookup = (workspaceId: string) => Promise<{
+    cwd: string;
+} | undefined> | {
+    cwd: string;
+} | undefined;
+/** 发现服务的依赖；由单根组装后注入 */
+export interface DiscoveryServiceOptions {
+    /** 配置唯一入口（SDK）：数据根、`agents/`、`mcp.json` 都从它的 `basePath` 推出 */
+    configManager: ConfigManager;
+    /** 按 workspaceId 取 cwd；不给时带 `workspaceId` 的调用按「项目不存在」处理 */
+    findWorkspace?: WorkspaceCwdLookup;
+    /** 用户主目录（`~/.agents/` 那一层），缺省 `os.homedir()`；测试注入临时目录 */
+    homeDir?: string;
+}
+export declare class DiscoveryService {
+    private readonly configManager;
+    private readonly findWorkspace?;
+    private readonly homeDir;
+    constructor(options: DiscoveryServiceOptions);
+    /** 数据根（SDK 的 `basePath`：`config.json` 所在目录） */
+    get basePath(): string;
+    /** 助手定义目录（`<basePath>/agents/`，一实体一文件，F-G3） */
+    get agentsDir(): string;
+    /**
+     * MCP 的 5 层链（L9）：`<ws>/.mcp.json` → `<ws>/.ai-zen/mcp.json` → `<ws>/.agents/mcp.json`
+     * → `<aiZenDir>/mcp.json` → `~/.agents/mcp.json`。
+     *
+     * `cwd` 为 `null`（还没打开项目）时只给后两层：项目侧那三层的路径得先有项目才算得出来。
+     */
+    mcpLayers(cwd: string | null): DiscoveryLayerPath[];
+    /** Skill 的 4 层目录：`<ws>/.ai-zen/skills` → `<ws>/.agents/skills` → `<aiZenDir>/skills` → `~/.agents/skills` */
+    skillLayers(cwd: string | null): DiscoveryLayerPath[];
+    /** 用户工具的 2 层目录：`<ws>/.agents/tools` → `<aiZenDir>/tools` */
+    toolLayers(cwd: string | null): DiscoveryLayerPath[];
+    /** 子 Agent 的 2 层目录：`<ws>/.agents/sub-agents` → `<aiZenDir>/sub-agents` */
+    subAgentLayers(cwd: string | null): DiscoveryLayerPath[];
+    /**
+     * 组装一个 Scope 要的全部路径（R54）。
+     *
+     * `agentsDir` 只有一处（数据根下的 `agents/`）：助手定义是全局配置，与项目无关。
+     * 其余四个按「近的在前」排好，直接喂给 SDK 的 `allInOne`。
+     */
+    scopeAbilityPaths(cwd: string): ScopeAbilityPaths;
+    /** 只取 MCP 的 5 层路径（喂给 SDK 的 `discoverMcpServers` / `McpScopePlugin`） */
+    mcpPaths(cwd: string): string[];
+    /** 按作用域找那一层的路径（写入时用） */
+    mcpLayer(scope: McpEditableScope, cwd: string | null): DiscoveryLayerPath;
+    /**
+     * `config.getDiscovery`（F-G1 / F-G2 / F-F6）。
+     *
+     * 给了 `workspaceId` 就带上项目侧的三层（与项目无关的两层也照常给）；没给就只报「用户级」
+     * 与「别的工具约定的」那几层 —— 客户端在没打开项目时也能看 MCP 屏。
+     */
+    discover(params?: ConfigGetDiscoveryParams): Promise<ConfigGetDiscoveryResult>;
+    /** 只读一层（`config.saveMcp` / `config.deleteMcp` 写回之后回报那一层时也用它） */
+    readMcpLayerView(layer: DiscoveryLayerPath): Promise<DiscoveryLayerView>;
+    /**
+     * 5 层 MCP 链的合并结果（SDK 的 `discoverMcpServers`，先到先得）。
+     *
+     * 这个方法是「client 侧看到的分层清单」与「Scope 实际连的那些 server」之间的对照点：
+     * 两者应当一致，不一致就说明某一层的文件坏了或者被近的层盖住了。
+     */
+    effectiveMcpServers(cwd: string): Promise<McpServerConfig[]>;
+    /**
+     * 存一条 MCP 条目（F-G1 / F-F6）：`entry.id` 在这一层里就改那一条，没有就建。
+     *
+     * 写回的口径（与 `deleteMcpEntry` 共用同一份合并规则）：
+     *   - 这个 id 的磁盘原文是底，覆盖入参里明确给了的字段，`extra` 最后叠上去 ——
+     *     于是这一版不认识的键与没被提到的 `oauth` 都原样留着（F-F6）；
+     *   - `oauth.clientSecret` 跟端点密钥同一套：省略 / 等于当前掩码 → 保留原文，空串才清掉
+     *     （见 `mergeOauth`）；
+     *   - 层里别的条目一个字节都不动：改一条不会把另一条读不全的字段覆盖掉；
+     *   - 文件里 `mcpServers` 之外的顶层键也原样带上。
+     */
+    writeMcpEntry(scope: McpEditableScope, entry: McpServerEntryInput, cwd: string | null): Promise<DiscoveryLayerView>;
+    /**
+     * 删一条 MCP 条目（F-F6）。
+     *
+     * 这个 id 本来就不在这一层里时落盘内容不变，回报 `removed: false`（不是失败）。
+     * 文件坏了但用户要清掉一个条目时，`readRawMcpFile` 把读不出来的那份当空 —— 于是这次写入
+     * 会用一份合法 JSON 覆盖它，这与「坏文件要能修」（F-F6）是同一个动作。
+     */
+    deleteMcpEntry(scope: McpEditableScope, id: string, cwd: string | null): Promise<{
+        layer: DiscoveryLayerView;
+        removed: boolean;
+    }>;
+    /** 可写作用域 → 那一层；`workspace` 作用域必须能落到某个项目里 */
+    private writableMcpLayer;
+    private readMcpLayers;
+    /** 读一个 mcp.json：不存在 / 坏了 / 能读 三种结论分开（F-F6） */
+    private readMcpFile;
+    /**
+     * 读 mcp.json 的原文。
+     *
+     * `broken` 与 `missing` 必须分开：`missing` 是「这里没有这一层」（正常），`broken` 是
+     * 「文件在，但读不成配置」（用户改了、改坏了，界面要能看见并修）。
+     */
+    private readRawMcpFile;
+    private readDirectoryLayers;
+    /** 按种类读一个目录；目录不存在就是 `missing`，不是目录或读不了就是 `broken` */
+    private readDirectory;
+    /**
+     * 一层的 Skill。
+     *
+     * 有效条目交给 SDK 的 `discoverSkills`（frontmatter 的解析口径只该有一份）；
+     * 另外再读一次目录，把「有 SKILL.md 却没被认成 Skill」的那些也报出来 —— 用户手改坏了要看得见。
+     */
+    private readSkillLayer;
+    /**
+     * 一层的用户工具。
+     *
+     * 以 SDK 的 `discoverUserToolFiles` 为「能不能真的变成一个工具」的判据（它自带 import 护栏与
+     * 超时）；没能加载上的 `.js` / `.mjs` 也列出来并说明原因。
+     */
+    private readToolLayer;
+    /**
+     * 一层的子 Agent。
+     *
+     * 「什么算子 Agent」由 SDK 的 `discoverSubAgents` 说了算（有 `function` 定义的那些）；
+     * 这里自己再读一遍文件，是为了拿到每个定义来自哪个文件（`source`）以及读不出来的那几个。
+     */
+    private readSubAgentLayer;
+    /** 入参的 workspaceId → cwd；没给就是 `null`（只报与项目无关的那几层） */
+    private resolveCwd;
+}