@ai-zen/agents-sdk 0.2.0-alpha.2

package/dist/runtime/McpConnectionManager.js

@@ -0,0 +1,238 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+const DEFAULT_IDLE_TIMEOUT = {
+    stdio: 30 * 60 * 1000,
+    http: 5 * 60 * 1000,
+};
+/** 指数退避: 1s → 2s → 4s → 8s → 16s → 30s（封顶） */
+function backoff(attempt) {
+    const ms = Math.min(1000 * Math.pow(2, attempt), 30_000);
+    return ms;
+}
+export class McpConnectionManager {
+    servers = new Map();
+    /** 可替换的 transport 工厂，用于测试注入 */
+    _transportFactory;
+    /** 可替换的 Client 工厂，用于测试注入 */
+    _clientFactory;
+    /**
+     * @param transportFactory 可选的自定义 transport 工厂（用于测试注入）
+     * @param clientFactory 可选的自定义 Client 工厂（用于测试注入）
+     */
+    constructor(transportFactory, clientFactory) {
+        this._transportFactory = transportFactory;
+        this._clientFactory = clientFactory;
+    }
+    // ---- 对外查询 ----
+    getState(name) {
+        return this.servers.get(name)?.state ?? "disconnected";
+    }
+    getManifest(name) {
+        return this.servers.get(name)?.manifest;
+    }
+    getClient(name) {
+        return this.servers.get(name)?.client;
+    }
+    // ---- 连接 ----
+    async connect(name, config, options = {}) {
+        const existing = this.servers.get(name);
+        if (existing?.state === "connected" && existing.manifest) {
+            this.touch(name);
+            return existing.manifest;
+        }
+        if (existing?.state === "connecting" && existing.pendingPromise) {
+            await existing.pendingPromise;
+            return this.servers.get(name)?.manifest ?? this.throwNotConnected(name);
+        }
+        const timeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT[config.transport] ?? 5 * 60 * 1000;
+        const pendingPromise = this.connectWithRetry(name, config, options, 0);
+        this.servers.set(name, {
+            state: "connecting",
+            pendingPromise,
+            timeoutMs,
+            cancelled: false,
+        });
+        try {
+            await pendingPromise;
+            const entry = this.servers.get(name);
+            this.servers.set(name, {
+                ...entry,
+                state: "connected",
+                timeoutTimer: this.scheduleTimeout(name, timeoutMs),
+            });
+            return entry.manifest;
+        }
+        catch (err) {
+            const entry = this.servers.get(name);
+            if (entry?.cancelled || entry?.state === "disconnected") {
+                this.servers.set(name, { state: "disconnected" });
+            }
+            else {
+                this.servers.set(name, { state: "error" });
+            }
+            throw err;
+        }
+    }
+    async connectWithRetry(name, config, options, attempt) {
+        try {
+            await this.doConnect(name, config);
+        }
+        catch (err) {
+            const entry = this.servers.get(name);
+            if (entry?.cancelled)
+                throw err;
+            if (options.isConfigError?.(err))
+                throw err;
+            if (!options.autoReconnect)
+                throw err;
+            const maxRetries = options.maxRetries ?? 3;
+            if (attempt >= maxRetries)
+                throw err;
+            const delay = backoff(attempt);
+            await new Promise((resolve, reject) => {
+                const current = this.servers.get(name);
+                if (current)
+                    current.cancelRetryWait = reject;
+                const timer = setTimeout(() => {
+                    const current2 = this.servers.get(name);
+                    if (current2)
+                        current2.cancelRetryWait = undefined;
+                    if (current2?.cancelled) {
+                        reject(new Error(`Connection to "${name}" was cancelled`));
+                    }
+                    else {
+                        resolve();
+                    }
+                }, delay);
+                const current3 = this.servers.get(name);
+                if (current3)
+                    current3.retryTimer = timer;
+            });
+            const recheck = this.servers.get(name);
+            if (recheck?.cancelled)
+                throw new Error(`Connection to "${name}" was cancelled`);
+            return this.connectWithRetry(name, config, options, attempt + 1);
+        }
+    }
+    async doConnect(name, config) {
+        const transport = this.createTransport(config);
+        const client = this._clientFactory
+            ? this._clientFactory()
+            : new Client({ name: "ai-zen-agents", version: "0.1.0" }, { capabilities: {} });
+        await client.connect(transport);
+        const toolsResult = await client.listTools();
+        const resourcesResult = await client.listResources();
+        const promptsResult = await client.listPrompts();
+        const manifest = {
+            tools: (toolsResult.tools ?? []).map((t) => ({
+                name: t.name,
+                description: t.description ?? "",
+                inputSchema: t.inputSchema,
+            })),
+            resources: (resourcesResult.resources ?? []).map((r) => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+            prompts: (promptsResult.prompts ?? []).map((p) => ({
+                name: p.name,
+                description: p.description,
+            })),
+        };
+        const entry = this.servers.get(name) ?? { state: "connecting" };
+        this.servers.set(name, {
+            ...entry,
+            state: "connected",
+            client,
+            transport,
+            manifest,
+            cancelled: false,
+        });
+    }
+    /**
+     * 根据配置创建对应的 Transport 实例。
+     * 如果设置了自定义工厂（测试用），则使用自定义工厂。
+     */
+    createTransport(config) {
+        if (this._transportFactory) {
+            return this._transportFactory(config);
+        }
+        if (config.transport === "stdio") {
+            if (!config.command) {
+                throw new Error(`MCP stdio server 缺少 command`);
+            }
+            return new StdioClientTransport({
+                command: config.command,
+                args: config.args,
+                env: config.env,
+            });
+        }
+        if (config.transport === "http") {
+            if (!config.url) {
+                throw new Error(`MCP HTTP server 缺少 url`);
+            }
+            return new StreamableHTTPClientTransport(new URL(config.url), {
+                requestInit: config.headers ? { headers: config.headers } : undefined,
+            });
+        }
+        throw new Error(`不支持的 MCP transport 类型: ${config.transport}`);
+    }
+    // ---- 断开 ----
+    async disconnect(name) {
+        const entry = this.servers.get(name);
+        if (!entry || entry.state === "disconnected")
+            return;
+        entry.cancelled = true;
+        if (entry.cancelRetryWait) {
+            entry.cancelRetryWait(new Error(`Connection to "${name}" was cancelled`));
+            entry.cancelRetryWait = undefined;
+        }
+        if (entry.retryTimer) {
+            clearTimeout(entry.retryTimer);
+            entry.retryTimer = undefined;
+        }
+        this.clearTimeout(name);
+        try {
+            await entry.client?.close();
+            await entry.transport?.close();
+        }
+        catch {
+            // 断开失败也清理状态
+        }
+        this.servers.set(name, { state: "disconnected" });
+    }
+    async disconnectAll() {
+        const names = Array.from(this.servers.keys());
+        await Promise.all(names.map((n) => this.disconnect(n)));
+    }
+    // ---- 活跃心跳 ----
+    touch(name) {
+        const entry = this.servers.get(name);
+        if (!entry || entry.state !== "connected" || !entry.timeoutMs)
+            return;
+        this.clearTimeout(name);
+        entry.timeoutTimer = this.scheduleTimeout(name, entry.timeoutMs);
+    }
+    // ---- 内部 ----
+    scheduleTimeout(name, timeoutMs) {
+        if (timeoutMs <= 0)
+            return undefined;
+        const timer = setTimeout(() => {
+            this.disconnect(name);
+        }, timeoutMs);
+        timer.unref();
+        return timer;
+    }
+    clearTimeout(name) {
+        const entry = this.servers.get(name);
+        if (entry?.timeoutTimer) {
+            clearTimeout(entry.timeoutTimer);
+            entry.timeoutTimer = undefined;
+        }
+    }
+    throwNotConnected(name) {
+        throw new Error(`MCP server "${name}" is not connected`);
+    }
+}

package/dist/runtime/Provider.d.ts

@@ -0,0 +1,44 @@
+import type { AppConfig, McpServerConfig } from "../types/index.js";
+import type { McpConnectionManager } from "./McpConnectionManager.js";
+/**
+ * Provider — 全局上下文实例。
+ *
+ * SDK 不是一个模块工具箱（到处 import 散装函数），而是一个实例，
+ * 持有所有全局状态（配置、路径、MCP 管理器等），各层通过它获取所需。
+ *
+ * 设计原则：
+ *   - Provider 实例一旦创建不可变（路径、配置等不变），refresh 时创建新实例
+ *   - 各层不直接 import 散装函数，而是通过 Provider 实例获取
+ *   - Provider 不关心能力的发现/过滤/实例化，那是 Capabilities 的事
+ */
+export declare class Provider {
+    /** 应用配置（端点、模型等） */
+    readonly config: AppConfig;
+    readonly agentsDir: string;
+    readonly subAgentsPaths: string[];
+    readonly skillsPaths: string[];
+    readonly toolsPaths: string[];
+    readonly mcpPaths: string[];
+    readonly conversationsDir: string;
+    readonly draftsDir: string;
+    readonly mcpManager?: McpConnectionManager;
+    readonly mcpConfigs?: Map<string, {
+        name: string;
+        config: McpServerConfig;
+    }>;
+    constructor(options: {
+        config: AppConfig;
+        agentsDir: string;
+        subAgentsPaths?: string[];
+        skillsPaths?: string[];
+        toolsPaths?: string[];
+        mcpPaths?: string[];
+        conversationsDir: string;
+        draftsDir: string;
+        mcpManager?: McpConnectionManager;
+        mcpConfigs?: Map<string, {
+            name: string;
+            config: McpServerConfig;
+        }>;
+    });
+}

package/dist/runtime/Provider.js

@@ -0,0 +1,38 @@
+/**
+ * Provider — 全局上下文实例。
+ *
+ * SDK 不是一个模块工具箱（到处 import 散装函数），而是一个实例，
+ * 持有所有全局状态（配置、路径、MCP 管理器等），各层通过它获取所需。
+ *
+ * 设计原则：
+ *   - Provider 实例一旦创建不可变（路径、配置等不变），refresh 时创建新实例
+ *   - 各层不直接 import 散装函数，而是通过 Provider 实例获取
+ *   - Provider 不关心能力的发现/过滤/实例化，那是 Capabilities 的事
+ */
+export class Provider {
+    /** 应用配置（端点、模型等） */
+    config;
+    // ---- 路径 ----
+    agentsDir;
+    subAgentsPaths;
+    skillsPaths;
+    toolsPaths;
+    mcpPaths;
+    conversationsDir;
+    draftsDir;
+    // ---- MCP ----
+    mcpManager;
+    mcpConfigs;
+    constructor(options) {
+        this.config = options.config;
+        this.agentsDir = options.agentsDir;
+        this.subAgentsPaths = options.subAgentsPaths ?? [];
+        this.skillsPaths = options.skillsPaths ?? [];
+        this.toolsPaths = options.toolsPaths ?? [];
+        this.mcpPaths = options.mcpPaths ?? [];
+        this.conversationsDir = options.conversationsDir;
+        this.draftsDir = options.draftsDir;
+        this.mcpManager = options.mcpManager;
+        this.mcpConfigs = options.mcpConfigs;
+    }
+}

package/dist/runtime/SdkAgent.d.ts

@@ -0,0 +1,100 @@
+import { Agent, type ChatCompletionModel } from "@ai-zen/agents-core";
+import type { AgentNS, Tool } from "@ai-zen/agents-core";
+import type { AgentDefinition, AgentPermissions } from "../types/index.js";
+import type { Capabilities } from "../capabilities/Capabilities.js";
+import type { Provider } from "./Provider.js";
+/**
+ * Agent 插件上下文：当前 SdkAgent + 发送内容 + 消息列表。
+ */
+export interface SendContext {
+    agent: SdkAgent;
+    content: string;
+    messages: AgentNS.Message[];
+}
+/**
+ * Agent 插件接口。
+ * 每个插件单一职责，通过钩子介入 Agent 生命周期。
+ *
+ * onInit:            Agent.init() 时调用，用于异步初始化
+ * onBeforeSend:      Agent.send() 调用前触发。可用于刷新工具列表等。
+ * onAfterSend:       Agent.send() 返回后调用。可通过 ctx.agent 替换当前 Agent。
+ * onInnerLoopStart:  Agent 内循环开始前触发。由 Core Agent 在内循环中调用。
+ * onInnerLoopEnd:    Agent 内循环结束后触发。由 Core Agent 在内循环中调用。
+ */
+export interface AgentPlugin {
+    /** Agent.init() 时调用，用于异步初始化 */
+    onInit?(): Promise<void>;
+    /** Agent.send() 调用前触发 */
+    onBeforeSend?(ctx: SendContext): Promise<void>;
+    /** Agent.send() 返回后调用，可通过 ctx.agent 替换当前 Agent */
+    onAfterSend?(ctx: SendContext): Promise<void>;
+    /** Agent 内循环开始前触发 */
+    onInnerLoopStart?(ctx: SendContext): Promise<void>;
+    /** Agent 内循环结束后触发 */
+    onInnerLoopEnd?(ctx: SendContext): Promise<void>;
+}
+/**
+ * SDK Agent — 继承 Core Agent，携带 SDK 层额外信息。
+ *
+ * Core Agent 不做复杂逻辑（不感知权限、不感知文件系统），
+ * SdkAgent 在 Core Agent 基础上增加了 SDK 层需要的元数据，
+ * 并通过 provider 字段访问全局上下文。
+ *
+ * 携带：
+ *   - provider：全局 Provider 实例
+ *   - definition：Agent 原始定义
+ *   - permissions：Agent 权限，供 call_skill_sub_agent 等回调读取
+ *   - caps：Capabilities 全局注册表，供 refreshTools 刷新工具列表
+ *
+ * 插件能力：
+ *   - use(plugin)：注册插件
+ *   - init()：初始化所有已注册插件
+ *   - send()：重写，在前后执行插件钩子
+ */
+export declare class SdkAgent extends Agent {
+    /** 全局 Provider 实例 */
+    readonly provider: Provider;
+    /** Agent 原始定义 */
+    readonly definition: AgentDefinition;
+    /** Agent 权限 */
+    readonly permissions?: AgentPermissions;
+    /** Capabilities 全局注册表，用于运行时刷新工具列表 */
+    readonly caps?: Capabilities;
+    /** 已注册的插件列表 */
+    private _plugins;
+    constructor(params: {
+        provider: Provider;
+        definition: AgentDefinition;
+        model: ChatCompletionModel;
+        model_config?: Record<string, unknown>;
+        messages?: AgentNS.Message[];
+        tools?: Tool[];
+        permissions?: AgentPermissions;
+        caps?: Capabilities;
+        rag?: any;
+        allowJsonParseError?: boolean;
+    });
+    /**
+     * 注册一个插件。
+     * 可以在 init() 之前或之后调用，但 beforeSend/afterSend 钩子仅在
+     * init() 之后发送消息时生效。
+     */
+    use(plugin: AgentPlugin): void;
+    /**
+     * 初始化所有已注册插件。
+     * SdkAgent 本身没有异步初始化需求——模型、工具、消息在构造时已就绪。
+     * init() 的存在完全是为了给插件一个执行异步初始化的机会。
+     *
+     * 如果不使用任何插件，可以不调 init()。
+     */
+    init(): Promise<void>;
+    /**
+     * 发送消息，在前后执行插件钩子。
+     *
+     * 流程：
+     *   1. onBeforeSend — send 外部准备（刷新工具等）
+     *   2. super.send()  — 委托 Core Agent，内含内循环及其钩子
+     *   3. onAfterSend  — send 外部后处理（保存草稿、迁移等）
+     */
+    send(content: string): Promise<AgentNS.Message[]>;
+}

package/dist/runtime/SdkAgent.js

@@ -0,0 +1,103 @@
+import { Agent } from "@ai-zen/agents-core";
+// ---------------------------------------------------------------------------
+// SdkAgent
+// ---------------------------------------------------------------------------
+/**
+ * SDK Agent — 继承 Core Agent，携带 SDK 层额外信息。
+ *
+ * Core Agent 不做复杂逻辑（不感知权限、不感知文件系统），
+ * SdkAgent 在 Core Agent 基础上增加了 SDK 层需要的元数据，
+ * 并通过 provider 字段访问全局上下文。
+ *
+ * 携带：
+ *   - provider：全局 Provider 实例
+ *   - definition：Agent 原始定义
+ *   - permissions：Agent 权限，供 call_skill_sub_agent 等回调读取
+ *   - caps：Capabilities 全局注册表，供 refreshTools 刷新工具列表
+ *
+ * 插件能力：
+ *   - use(plugin)：注册插件
+ *   - init()：初始化所有已注册插件
+ *   - send()：重写，在前后执行插件钩子
+ */
+export class SdkAgent extends Agent {
+    /** 全局 Provider 实例 */
+    provider;
+    /** Agent 原始定义 */
+    definition;
+    /** Agent 权限 */
+    permissions;
+    /** Capabilities 全局注册表，用于运行时刷新工具列表 */
+    caps;
+    /** 已注册的插件列表 */
+    _plugins = [];
+    constructor(params) {
+        super({
+            model: params.model,
+            model_config: params.model_config,
+            messages: params.messages,
+            tools: params.tools,
+            rag: params.rag,
+            allowJsonParseError: params.allowJsonParseError,
+        });
+        this.provider = params.provider;
+        this.definition = params.definition;
+        this.permissions = params.permissions;
+        this.caps = params.caps;
+    }
+    /**
+     * 注册一个插件。
+     * 可以在 init() 之前或之后调用，但 beforeSend/afterSend 钩子仅在
+     * init() 之后发送消息时生效。
+     */
+    use(plugin) {
+        this._plugins.push(plugin);
+    }
+    /**
+     * 初始化所有已注册插件。
+     * SdkAgent 本身没有异步初始化需求——模型、工具、消息在构造时已就绪。
+     * init() 的存在完全是为了给插件一个执行异步初始化的机会。
+     *
+     * 如果不使用任何插件，可以不调 init()。
+     */
+    async init() {
+        for (const plugin of this._plugins) {
+            await plugin.onInit?.();
+        }
+    }
+    /**
+     * 发送消息，在前后执行插件钩子。
+     *
+     * 流程：
+     *   1. onBeforeSend — send 外部准备（刷新工具等）
+     *   2. super.send()  — 委托 Core Agent，内含内循环及其钩子
+     *   3. onAfterSend  — send 外部后处理（保存草稿、迁移等）
+     */
+    async send(content) {
+        const ctx = {
+            agent: this,
+            content,
+            messages: this.messages,
+        };
+        for (const plugin of this._plugins) {
+            await plugin.onBeforeSend?.(ctx);
+        }
+        this.onInnerLoopStart = async () => {
+            for (const plugin of this._plugins) {
+                await plugin.onInnerLoopStart?.(ctx);
+            }
+        };
+        this.onInnerLoopEnd = async () => {
+            for (const plugin of this._plugins) {
+                await plugin.onInnerLoopEnd?.(ctx);
+            }
+        };
+        const messages = await super.send(content);
+        this.onInnerLoopStart = undefined;
+        this.onInnerLoopEnd = undefined;
+        for (const plugin of this._plugins) {
+            await plugin.onAfterSend?.(ctx);
+        }
+        return messages;
+    }
+}

package/dist/runtime/TaskMigrationService.d.ts

@@ -0,0 +1,24 @@
+import { AgentNS } from "@ai-zen/agents-core";
+import type { AgentDefinition } from "../types/index.js";
+/**
+ * 任务迁移服务。
+ */
+export declare class TaskMigrationService {
+    static readonly HANDOFF_SECTIONS: {
+        readonly breakpoint: "## 💬 对话断点";
+        readonly completed: "## ✅ 已完成的任务";
+        readonly pending: "## 📋 未完成的任务";
+        readonly memory: "## 🧠 重要记忆";
+        readonly files: "## 📁 文件索引";
+        readonly instructions: "## 🔔 接手指令";
+    };
+    static shouldMigrate(promptTokens: number, maxTokens: number): boolean;
+    static createPrompt(): string;
+    static createAgentDefinition(options?: {
+        modelId?: string;
+    }): AgentDefinition;
+    static createPostMessages(handoffDoc: string): AgentNS.Message[];
+}
+export interface BuildMigrationAgentOptions {
+    modelId?: string;
+}

package/dist/runtime/TaskMigrationService.js

@@ -0,0 +1,71 @@
+import { AgentNS } from "@ai-zen/agents-core";
+/**
+ * 任务迁移服务。
+ */
+export class TaskMigrationService {
+    static HANDOFF_SECTIONS = {
+        breakpoint: "## 💬 对话断点",
+        completed: "## ✅ 已完成的任务",
+        pending: "## 📋 未完成的任务",
+        memory: "## 🧠 重要记忆",
+        files: "## 📁 文件索引",
+        instructions: "## 🔔 接手指令",
+    };
+    static shouldMigrate(promptTokens, maxTokens) {
+        return promptTokens > maxTokens;
+    }
+    static createPrompt() {
+        return [
+            "你是一个任务交接助手。请根据以下对话历史，生成一份结构化交接文档。",
+            "",
+            `文档必须包含以下章节：`,
+            `${TaskMigrationService.HANDOFF_SECTIONS.breakpoint}`,
+            `- 用户最后说了什么，AI 最后回复了什么`,
+            "",
+            `${TaskMigrationService.HANDOFF_SECTIONS.completed}`,
+            `- 列出已完成的每项任务及其关键产出`,
+            "",
+            `${TaskMigrationService.HANDOFF_SECTIONS.pending}`,
+            `- 按优先级列出未完成的任务、当前进度、下一步`,
+            "",
+            `${TaskMigrationService.HANDOFF_SECTIONS.memory}`,
+            `- 需要新 Agent 记住的关键信息（设计决策、偏好、约定等）`,
+            "",
+            `${TaskMigrationService.HANDOFF_SECTIONS.files}`,
+            `- 涉及的文件及其用途`,
+            "",
+            `${TaskMigrationService.HANDOFF_SECTIONS.instructions}`,
+            `- 接手后建议的操作步骤`,
+            "",
+            "只输出交接文档本身，不要加额外说明。",
+        ].join("\n");
+    }
+    static createAgentDefinition(options = {}) {
+        const now = new Date().toISOString();
+        return {
+            id: "task-migration",
+            name: "任务交接助手",
+            description: "专用迁移 Agent：分析对话历史并生成结构化交接文档",
+            messages: [
+                { role: AgentNS.Role.System, content: TaskMigrationService.createPrompt() },
+            ],
+            modelId: options.modelId,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    static createPostMessages(handoffDoc) {
+        const content = [
+            "这是上一轮对话的任务交接文档。请先阅读交接文档，理解上下文后再继续协助用户完成任务。",
+            "",
+            "---",
+            "",
+            handoffDoc,
+            "",
+            "---",
+            "",
+            "请确认你已理解以上内容，然后询问用户接下来需要什么帮助。",
+        ].join("\n");
+        return [{ role: AgentNS.Role.User, content }];
+    }
+}

package/dist/runtime/createAgent.d.ts

@@ -0,0 +1,14 @@
+import { SdkAgent } from "./SdkAgent.js";
+import type { Provider } from "./Provider.js";
+/**
+ * 从磁盘创建 Agent（同步）。
+ *
+ * 内部创建 Capabilities 实例执行全局发现，读取 Agent 定义，
+ * 过滤并实例化工具，产出 SdkAgent。
+ *
+ * ```ts
+ * const agent = createAgent(runtime, "my-agent");
+ * // agent 是 SdkAgent，可直接注册插件、发送消息
+ * ```
+ */
+export declare function createAgent(provider: Provider, agentId: string): SdkAgent;

package/dist/runtime/createAgent.js

@@ -0,0 +1,41 @@
+import { AgentRepository } from "../crud/AgentRepository.js";
+import { Capabilities } from "../capabilities/Capabilities.js";
+import { SdkAgent } from "./SdkAgent.js";
+import { createModel } from "./createModel.js";
+/**
+ * 从磁盘创建 Agent（同步）。
+ *
+ * 内部创建 Capabilities 实例执行全局发现，读取 Agent 定义，
+ * 过滤并实例化工具，产出 SdkAgent。
+ *
+ * ```ts
+ * const agent = createAgent(runtime, "my-agent");
+ * // agent 是 SdkAgent，可直接注册插件、发送消息
+ * ```
+ */
+export function createAgent(provider, agentId) {
+    const caps = new Capabilities(provider);
+    const definition = new AgentRepository(provider.agentsDir).read(agentId);
+    if (!definition)
+        throw new Error(`Agent "${agentId}" 不存在`);
+    const modelId = definition.modelId ?? provider.config.defaultModel;
+    if (!modelId)
+        throw new Error("未指定模型且无默认模型");
+    const model = createModel(provider.config, modelId);
+    const tools = caps.buildTools(definition.permissions ?? {}, {
+        exclude: {
+            subagents: definition.function?.name
+                ? [definition.function.name]
+                : undefined,
+        },
+    });
+    return new SdkAgent({
+        provider,
+        definition,
+        model,
+        messages: definition.messages,
+        tools,
+        permissions: definition.permissions,
+        caps,
+    });
+}

package/dist/runtime/createModel.d.ts

@@ -0,0 +1,11 @@
+import type { ChatCompletionModel } from "@ai-zen/agents-core";
+import type { AppConfig } from "../types/index.js";
+/**
+ * 模型工厂 — 根据 modelId 和 config 构建 Core ChatCompletionModel。
+ *
+ * 属于独立的 runtime 子层，不依赖 capabilities/ 或其他模块。
+ * 通过 Provider 实例获取 AppConfig 后调用。
+ *
+ * 改为同步版本，使用 endp​oint.chatCompletionSync() 避免不必要的 async。
+ */
+export declare function createModel(config: AppConfig, modelId: string): ChatCompletionModel;