@h-ai/ai 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/{ai-audio-ws-protocol-nfhO0tOo.d.ts → ai-acp-types-DQ8jO9Ie.d.ts}

@@ -3,13 +3,245 @@ import { HaiResult, HaiError } from '@h-ai/core';
 import { AgentCard } from '@a2a-js/sdk';
 import { AgentExecutor } from '@a2a-js/sdk/server';
 import * as zod from 'zod';
-import { ZodType, z } from 'zod';
-import { e as AudioOperations, a as AudioContent, P as PlayableAudio, b as AudioFormat } from './ai-audio-types-4R5yUAVl.js';
-import OpenAI from 'openai';
+import { z, ZodType } from 'zod';
 import { Buffer } from 'node:buffer';
 import { CleanOptionsInput, ChunkOptionsInput } from '@h-ai/datapipe';
-import { PromptMessage } from '@modelcontextprotocol/sdk/types.js';
+import { e as AudioOperations, a as AudioContent, P as PlayableAudio, b as AudioFormat } from './ai-audio-types-4R5yUAVl.js';
 import * as zod_v4_core from 'zod/v4/core';
+import * as _agentclientprotocol_sdk from '@agentclientprotocol/sdk';
+import { McpServer, ContentBlock, SessionNotification, ClientRequestHandlersByMethod, ClientCapabilities } from '@agentclientprotocol/sdk';
+import OpenAI from 'openai';
+import { PromptMessage } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * 工程主分支必须显式填写。
+ * @example
+ * ```ts
+ * import { ACPRepositorySchema } from '@h-ai/ai'
+ * const repository = ACPRepositorySchema.parse({ id: 'api', url: 'https://example.com/api.git', mainBranch: 'trunk' })
+ * ```
+ */
+declare const ACPRepositorySchema: z.ZodObject<{
+    id: z.ZodString;
+    url: z.ZodString;
+    mainBranch: z.ZodString;
+    remote: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 工作区持久目录或容器卷。
+ * @example
+ * ```ts
+ * import { ACPWorkspaceSchema } from '@h-ai/ai'
+ * const workspace = ACPWorkspaceSchema.parse({ id: 'project', storage: { type: 'directory', path: '/srv/project' }, repositories: [] })
+ * ```
+ */
+declare const ACPWorkspaceSchema: z.ZodObject<{
+    id: z.ZodString;
+    storage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"directory">;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"volume">;
+        name: z.ZodString;
+        engine: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            podman: "podman";
+            docker: "docker";
+        }>>;
+        image: z.ZodString;
+    }, z.core.$strict>], "type">;
+    repositories: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        url: z.ZodString;
+        mainBranch: z.ZodString;
+        remote: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>>;
+    environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * Agent 定义，仅保存凭据引用。
+ * @example
+ * ```ts
+ * import { ACPAgentSchema } from '@h-ai/ai'
+ * const agent = ACPAgentSchema.parse({ id: 'coder', name: 'Coder', mode: 'embedded', adapter: 'codex', modelIds: ['coding'], defaultModelId: 'coding' })
+ * ```
+ */
+declare const ACPAgentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"custom-service">;
+    transport: z.ZodEnum<{
+        http: "http";
+        ws: "ws";
+    }>;
+    url: z.ZodURL;
+    headerEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    supportedTransports: z.ZodArray<z.ZodEnum<{
+        http: "http";
+        ws: "ws";
+    }>>;
+    id: z.ZodString;
+    name: z.ZodString;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    adapter: z.ZodDefault<z.ZodString>;
+    modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    defaultModelId: z.ZodOptional<z.ZodString>;
+    environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"embedded">;
+    transport: z.ZodDefault<z.ZodLiteral<"stdio">>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    id: z.ZodString;
+    name: z.ZodString;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    adapter: z.ZodDefault<z.ZodString>;
+    modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    defaultModelId: z.ZodOptional<z.ZodString>;
+    environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"builtin-service">;
+    transport: z.ZodDefault<z.ZodLiteral<"stdio">>;
+    image: z.ZodString;
+    engine: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        podman: "podman";
+        docker: "docker";
+    }>>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    id: z.ZodString;
+    name: z.ZodString;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    adapter: z.ZodDefault<z.ZodString>;
+    modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    defaultModelId: z.ZodOptional<z.ZodString>;
+    environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>], "mode">;
+/**
+ * 会话 Git 发布请求。
+ * @example
+ * ```ts
+ * import { ACPPublishSchema } from '@h-ai/ai'
+ * const request = ACPPublishSchema.parse({ mode: 'push-branch', message: 'Implement task', author: { name: 'Developer', email: 'developer@example.com' } })
+ * ```
+ */
+declare const ACPPublishSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        "merge-main": "merge-main";
+        "push-branch": "push-branch";
+    }>;
+    message: z.ZodString;
+    author: z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodEmail;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * ACP 执行限制。
+ * @example
+ * ```ts
+ * import { ACPConfigSchema } from '@h-ai/ai'
+ * const config = ACPConfigSchema.parse({ promptTimeout: 300000 })
+ * ```
+ */
+declare const ACPConfigSchema: z.ZodObject<{
+    agents: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"custom-service">;
+        transport: z.ZodEnum<{
+            http: "http";
+            ws: "ws";
+        }>;
+        url: z.ZodURL;
+        headerEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        supportedTransports: z.ZodArray<z.ZodEnum<{
+            http: "http";
+            ws: "ws";
+        }>>;
+        id: z.ZodString;
+        name: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        adapter: z.ZodDefault<z.ZodString>;
+        modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        defaultModelId: z.ZodOptional<z.ZodString>;
+        environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"embedded">;
+        transport: z.ZodDefault<z.ZodLiteral<"stdio">>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        id: z.ZodString;
+        name: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        adapter: z.ZodDefault<z.ZodString>;
+        modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        defaultModelId: z.ZodOptional<z.ZodString>;
+        environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"builtin-service">;
+        transport: z.ZodDefault<z.ZodLiteral<"stdio">>;
+        image: z.ZodString;
+        engine: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            podman: "podman";
+            docker: "docker";
+        }>>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        id: z.ZodString;
+        name: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        adapter: z.ZodDefault<z.ZodString>;
+        modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        defaultModelId: z.ZodOptional<z.ZodString>;
+        environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>], "mode">>>;
+    workspaces: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        storage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"directory">;
+            path: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"volume">;
+            name: z.ZodString;
+            engine: z.ZodDefault<z.ZodEnum<{
+                auto: "auto";
+                podman: "podman";
+                docker: "docker";
+            }>>;
+            image: z.ZodString;
+        }, z.core.$strict>], "type">;
+        repositories: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            url: z.ZodString;
+            mainBranch: z.ZodString;
+            remote: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>>;
+        environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>>;
+    requestTimeout: z.ZodDefault<z.ZodNumber>;
+    promptTimeout: z.ZodDefault<z.ZodNumber>;
+    cancelTimeout: z.ZodDefault<z.ZodNumber>;
+    maxContentBytes: z.ZodDefault<z.ZodNumber>;
+    maxPendingEvents: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * ACP 初始化配置，已填充超时和只读清单默认值。
+ * @example
+ * ```ts
+ * import { ACPConfigSchema } from '@h-ai/ai'
+ * import type { ACPConfig } from '@h-ai/ai'
+ * const config: ACPConfig = ACPConfigSchema.parse({ promptTimeout: 300000 })
+ * ```
+ */
+type ACPConfig = z.output<typeof ACPConfigSchema>;
+/**
+ * ACP 初始化输入，省略字段采用 Schema 默认值。
+ * @example
+ * ```ts
+ * import type { ACPConfigInput } from '@h-ai/ai'
+ * const config: ACPConfigInput = { promptTimeout: 300000 }
+ * ```
+ */
+type ACPConfigInput = z.input<typeof ACPConfigSchema>;
 
 /**
  * @h-ai/ai — Store 存储抽象类型
@@ -837,14 +1069,14 @@ type ToolDefinition = OpenAI.Chat.Completions.ChatCompletionTool;
  * ```ts
  * import type { TempModelConfig } from '@h-ai/ai'
  *
- * const value: TempModelConfig = { model: 'gpt-4o-mini', api: 'chat', timeout: 15_000 }
+ * const value: TempModelConfig = { model: 'gpt-4o-mini', protocol: 'chat', timeout: 15_000 }
  * ```
  */
 interface TempModelConfig {
     /** 模型名称（传给 API 的实际模型名） */
     model: string;
-    /** API 协议（未指定时回退全局 `api`，再回退 `chat`；决定走 Chat Completions / Responses / Anthropic） */
-    api?: ApiType;
+    /** API 协议（未指定时回退全局 `protocol`，再回退 `chat`；决定走 Chat Completions / Responses / Anthropic） */
+    protocol?: ApiType;
     /** API Key（未指定时回退全局配置 / 环境变量） */
     apiKey?: string;
     /** API 基础 URL（未指定时回退全局配置 / 环境变量 / 默认 OpenAI） */
@@ -3081,13 +3313,6 @@ interface MemoryOperations extends MemoryCoreOperations {
     admin: MemoryAdminOperations;
 }
 
-/**
- * @h-ai/ai — 错误码 + 配置 Schema
- *
- * 定义 AI 模块的错误码常量、Zod Schema 和配置类型。
- * @module ai-config
- */
-
 /**
  * 可选密钥 Schema。
  *
@@ -3139,12 +3364,12 @@ declare const OptionalSecretSchema: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodS
  * ```
  */
 declare const ModelScenarioSchema: z.ZodEnum<{
+    default: "default";
     chat: "chat";
     summary: "summary";
     plan: "plan";
     reasoning: "reasoning";
     ocr: "ocr";
-    default: "default";
     execute: "execute";
     extraction: "extraction";
     embedding: "embedding";
@@ -3202,6 +3427,35 @@ declare const ApiTypeSchema: z.ZodEnum<{
  * ```
  */
 type ApiType = z.infer<typeof ApiTypeSchema>;
+/**
+ * 模型能力元数据；缺省字段表示未知，不从调用预算推断容量。
+ * @example
+ * ```ts
+ * import { ModelCapabilitiesSchema } from '@h-ai/ai'
+ * const capabilities = ModelCapabilitiesSchema.parse({ contextWindow: 128000, toolCalling: true })
+ * ```
+ */
+declare const ModelCapabilitiesSchema: z.ZodObject<{
+    contextWindow: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    inputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        image: "image";
+        audio: "audio";
+        text: "text";
+        video: "video";
+    }>>>;
+    outputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        image: "image";
+        audio: "audio";
+        text: "text";
+        video: "video";
+    }>>>;
+    toolCalling: z.ZodOptional<z.ZodBoolean>;
+    reasoning: z.ZodOptional<z.ZodObject<{
+        supported: z.ZodBoolean;
+        efforts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /**
  * 模型条目 Schema
  *
@@ -3222,8 +3476,29 @@ type ApiType = z.infer<typeof ApiTypeSchema>;
  */
 declare const ModelEntrySchema: z.ZodObject<{
     id: z.ZodString;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        inputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            image: "image";
+            audio: "audio";
+            text: "text";
+            video: "video";
+        }>>>;
+        outputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            image: "image";
+            audio: "audio";
+            text: "text";
+            video: "video";
+        }>>>;
+        toolCalling: z.ZodOptional<z.ZodBoolean>;
+        reasoning: z.ZodOptional<z.ZodObject<{
+            supported: z.ZodBoolean;
+            efforts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     model: z.ZodString;
-    api: z.ZodOptional<z.ZodEnum<{
+    protocol: z.ZodOptional<z.ZodEnum<{
         chat: "chat";
         responses: "responses";
         anthropic: "anthropic";
@@ -3233,7 +3508,7 @@ declare const ModelEntrySchema: z.ZodObject<{
     maxTokens: z.ZodOptional<z.ZodNumber>;
     temperature: z.ZodOptional<z.ZodNumber>;
     timeout: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 /**
  * 模型条目类型
  *
@@ -3273,7 +3548,7 @@ declare const LLMConfigSchema: z.ZodObject<{
     apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
     baseUrl: z.ZodOptional<z.ZodURL>;
     model: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    api: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+    protocol: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         chat: "chat";
         responses: "responses";
         anthropic: "anthropic";
@@ -3284,8 +3559,29 @@ declare const LLMConfigSchema: z.ZodObject<{
     tempModelCacheTtl: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     models: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            contextWindow: z.ZodOptional<z.ZodNumber>;
+            maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+            inputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                image: "image";
+                audio: "audio";
+                text: "text";
+                video: "video";
+            }>>>;
+            outputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                image: "image";
+                audio: "audio";
+                text: "text";
+                video: "video";
+            }>>>;
+            toolCalling: z.ZodOptional<z.ZodBoolean>;
+            reasoning: z.ZodOptional<z.ZodObject<{
+                supported: z.ZodBoolean;
+                efforts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
         model: z.ZodString;
-        api: z.ZodOptional<z.ZodEnum<{
+        protocol: z.ZodOptional<z.ZodEnum<{
             chat: "chat";
             responses: "responses";
             anthropic: "anthropic";
@@ -3295,21 +3591,21 @@ declare const LLMConfigSchema: z.ZodObject<{
         maxTokens: z.ZodOptional<z.ZodNumber>;
         temperature: z.ZodOptional<z.ZodNumber>;
         timeout: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>>;
+    }, z.core.$strict>>>;
     scenarios: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodString>;
         chat: z.ZodOptional<z.ZodString>;
         summary: z.ZodOptional<z.ZodString>;
         plan: z.ZodOptional<z.ZodString>;
         reasoning: z.ZodOptional<z.ZodString>;
         ocr: z.ZodOptional<z.ZodString>;
-        default: z.ZodOptional<z.ZodString>;
         execute: z.ZodOptional<z.ZodString>;
         extraction: z.ZodOptional<z.ZodString>;
         embedding: z.ZodOptional<z.ZodString>;
         rerank: z.ZodOptional<z.ZodString>;
         fast: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 /**
  * LLM 配置类型
  *
@@ -3333,15 +3629,17 @@ type LLMConfig = z.infer<typeof LLMConfigSchema>;
  *
  * // 展示模型选择，不输出配置中的 apiKey。
  * function label(config: ResolvedModelConfig): string {
- *   return `${config.api}/${config.model}, timeout=${config.timeout}ms`
+ *   return `${config.protocol}/${config.model}, timeout=${config.timeout}ms`
  * }
  * ```
  */
 interface ResolvedModelConfig {
+    /** 已确认的模型能力 */
+    capabilities?: z.infer<typeof ModelCapabilitiesSchema>;
     /** 模型名称（传给 API 的实际模型名） */
     model: string;
     /** API 协议（模型条目 > 全局配置 > `chat`） */
-    api: ApiType;
+    protocol: ApiType;
     /** API Key（模型条目 > 全局配置 > 环境变量） */
     apiKey: string | undefined;
     /** API 基础 URL（模型条目 > 全局配置 > 环境变量 > 默认 OpenAI） */
@@ -3394,8 +3692,8 @@ declare function resolveModelEntry(llmConfig: LLMConfig, scenario: ModelScenario
 /**
  * 解析某次 chat 请求应使用的 API 协议（不校验 API Key）
  *
- * 供 LLM Provider 路由层选择底层实现使用：优先取显式模型条目的 `api`，
- * 其次全局 `api`，最后回退 `chat`。临时模型的 `api` 由调用方单独传入优先。
+ * 供 LLM Provider 路由层选择底层实现使用：优先取显式模型条目的 `protocol`，
+ * 其次全局 `protocol`，最后回退 `chat`。临时模型的 `protocol` 由调用方单独传入优先。
  *
  * @param llmConfig - LLM 配置
  * @param explicitModel - 显式指定的模型名/ID（可选）
@@ -3406,7 +3704,7 @@ declare function resolveModelEntry(llmConfig: LLMConfig, scenario: ModelScenario
  * ```ts
  * import { LLMConfigSchema, resolveModelApi } from '@h-ai/ai'
  *
- * const config = LLMConfigSchema.parse({ models: [{ id: 'claude', model: 'claude-sonnet-4', api: 'anthropic' }] })
+ * const config = LLMConfigSchema.parse({ models: [{ id: 'claude', model: 'claude-sonnet-4', protocol: 'anthropic' }] })
  * const protocol = resolveModelApi(config, 'claude')
  * ```
  */
@@ -3481,6 +3779,37 @@ declare const MCPServerConfigSchema: z.ZodObject<{
  * ```
  */
 type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
+/**
+ * 外部 MCP 服务清单项；凭据仅保存环境变量引用，可供 ACP 会话选择。
+ * @example
+ * ```ts
+ * import { MCPExternalServerSchema } from '@h-ai/ai'
+ * const server = MCPExternalServerSchema.parse({ id: 'docs', name: 'Docs', transport: 'http', url: 'https://mcp.example.com' })
+ * ```
+ */
+declare const MCPExternalServerSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    transport: z.ZodEnum<{
+        http: "http";
+        stdio: "stdio";
+        sse: "sse";
+    }>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    url: z.ZodOptional<z.ZodURL>;
+    environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    headerEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * 外部 MCP 服务配置。
+ * @example
+ * ```ts
+ * import type { MCPExternalServer } from '@h-ai/ai'
+ * function serverId(server: MCPExternalServer) { return server.id }
+ * ```
+ */
+type MCPExternalServer = z.infer<typeof MCPExternalServerSchema>;
 /**
  * MCP 配置 Schema
  *
@@ -3500,6 +3829,20 @@ type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
  * ```
  */
 declare const MCPConfigSchema: z.ZodObject<{
+    servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        transport: z.ZodEnum<{
+            http: "http";
+            stdio: "stdio";
+            sse: "sse";
+        }>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        url: z.ZodOptional<z.ZodURL>;
+        environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        headerEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>>;
     server: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -4468,11 +4811,91 @@ declare function resolveImageModel(imageConfig: ImageConfig, explicit?: string):
  * ```
  */
 declare const AIConfigSchema: z.ZodObject<{
+    acp: z.ZodOptional<z.ZodObject<{
+        agents: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            mode: z.ZodLiteral<"custom-service">;
+            transport: z.ZodEnum<{
+                http: "http";
+                ws: "ws";
+            }>;
+            url: z.ZodURL;
+            headerEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            supportedTransports: z.ZodArray<z.ZodEnum<{
+                http: "http";
+                ws: "ws";
+            }>>;
+            id: z.ZodString;
+            name: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            adapter: z.ZodDefault<z.ZodString>;
+            modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            defaultModelId: z.ZodOptional<z.ZodString>;
+            environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>, z.ZodObject<{
+            mode: z.ZodLiteral<"embedded">;
+            transport: z.ZodDefault<z.ZodLiteral<"stdio">>;
+            command: z.ZodOptional<z.ZodString>;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            id: z.ZodString;
+            name: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            adapter: z.ZodDefault<z.ZodString>;
+            modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            defaultModelId: z.ZodOptional<z.ZodString>;
+            environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>, z.ZodObject<{
+            mode: z.ZodLiteral<"builtin-service">;
+            transport: z.ZodDefault<z.ZodLiteral<"stdio">>;
+            image: z.ZodString;
+            engine: z.ZodDefault<z.ZodEnum<{
+                auto: "auto";
+                podman: "podman";
+                docker: "docker";
+            }>>;
+            command: z.ZodOptional<z.ZodString>;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            id: z.ZodString;
+            name: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            adapter: z.ZodDefault<z.ZodString>;
+            modelIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            defaultModelId: z.ZodOptional<z.ZodString>;
+            environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>], "mode">>>;
+        workspaces: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            storage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"directory">;
+                path: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"volume">;
+                name: z.ZodString;
+                engine: z.ZodDefault<z.ZodEnum<{
+                    auto: "auto";
+                    podman: "podman";
+                    docker: "docker";
+                }>>;
+                image: z.ZodString;
+            }, z.core.$strict>], "type">;
+            repositories: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                url: z.ZodString;
+                mainBranch: z.ZodString;
+                remote: z.ZodDefault<z.ZodString>;
+            }, z.core.$strict>>>;
+            environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>>;
+        requestTimeout: z.ZodDefault<z.ZodNumber>;
+        promptTimeout: z.ZodDefault<z.ZodNumber>;
+        cancelTimeout: z.ZodDefault<z.ZodNumber>;
+        maxContentBytes: z.ZodDefault<z.ZodNumber>;
+        maxPendingEvents: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
     llm: z.ZodDefault<z.ZodObject<{
         apiKey: z.ZodOptional<z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>>;
         baseUrl: z.ZodOptional<z.ZodURL>;
         model: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        api: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        protocol: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
             chat: "chat";
             responses: "responses";
             anthropic: "anthropic";
@@ -4483,8 +4906,29 @@ declare const AIConfigSchema: z.ZodObject<{
         tempModelCacheTtl: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         models: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
+            capabilities: z.ZodOptional<z.ZodObject<{
+                contextWindow: z.ZodOptional<z.ZodNumber>;
+                maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+                inputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                    image: "image";
+                    audio: "audio";
+                    text: "text";
+                    video: "video";
+                }>>>;
+                outputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                    image: "image";
+                    audio: "audio";
+                    text: "text";
+                    video: "video";
+                }>>>;
+                toolCalling: z.ZodOptional<z.ZodBoolean>;
+                reasoning: z.ZodOptional<z.ZodObject<{
+                    supported: z.ZodBoolean;
+                    efforts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
             model: z.ZodString;
-            api: z.ZodOptional<z.ZodEnum<{
+            protocol: z.ZodOptional<z.ZodEnum<{
                 chat: "chat";
                 responses: "responses";
                 anthropic: "anthropic";
@@ -4494,22 +4938,36 @@ declare const AIConfigSchema: z.ZodObject<{
             maxTokens: z.ZodOptional<z.ZodNumber>;
             temperature: z.ZodOptional<z.ZodNumber>;
             timeout: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strip>>>;
+        }, z.core.$strict>>>;
         scenarios: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodString>;
             chat: z.ZodOptional<z.ZodString>;
             summary: z.ZodOptional<z.ZodString>;
             plan: z.ZodOptional<z.ZodString>;
             reasoning: z.ZodOptional<z.ZodString>;
             ocr: z.ZodOptional<z.ZodString>;
-            default: z.ZodOptional<z.ZodString>;
             execute: z.ZodOptional<z.ZodString>;
             extraction: z.ZodOptional<z.ZodString>;
             embedding: z.ZodOptional<z.ZodString>;
             rerank: z.ZodOptional<z.ZodString>;
             fast: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     mcp: z.ZodOptional<z.ZodObject<{
+        servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            transport: z.ZodEnum<{
+                http: "http";
+                stdio: "stdio";
+                sse: "sse";
+            }>;
+            command: z.ZodOptional<z.ZodString>;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            url: z.ZodOptional<z.ZodURL>;
+            environmentRefs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            headerEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>>;
         server: z.ZodOptional<z.ZodObject<{
             name: z.ZodString;
             version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -6359,90 +6817,267 @@ interface FileOperations {
 }
 
 /**
- * @h-ai/ai — 文生图公共类型
+ * @h-ai/ai — Persona 子功能类型
  *
- * 公共契约只暴露业务需要的提示词、尺寸和标准化图片字节。
- * 厂商请求字段、临时 URL 与响应中间态由 Provider 内部处理。
- * @module image/ai-image-types
+ * 定义「AI 角色人格」的持久化与组合接口。Persona 解决的是「AI 是谁」的问题：
+ * 多智能体场景（如多位专家同台访谈）中，每个 AI 有稳定的系统提示词、性格特征与
+ * 长期人格。它与 Memory 正交——Memory 用 `objectId` / `scope` 回答「谁的记忆」，
+ * Persona 回答「这个 AI 的身份与人设」，二者通过 `scope: { personaId }` 关联。
+ * @module ai-persona-types
  */
 
 /**
- * 图片像素尺寸
+ * Persona 档案输入（创建 / 覆盖保存时使用）
  *
  * @example
  * ```ts
- * import type { ImageSize } from '@h-ai/ai'
+ * import type { PersonaProfileInput } from '@h-ai/ai'
  *
- * const value: ImageSize = { width: 1024, height: 1024 }
+ * const value: PersonaProfileInput = { id: 'support', objectId: 'tenant-1', name: '客服助手', systemPrompt: '根据已验证的订单信息回答。', traits: ['简洁', '先核对证据'] }
  * ```
  */
-interface ImageSize {
-    /** 宽度（像素） */
-    width: number;
-    /** 高度（像素） */
-    height: number;
+interface PersonaProfileInput {
+    /** 角色唯一标识（业务侧稳定 ID，如 `xiaop`） */
+    id: string;
+    /**
+     * 所属主体 ID（多租户隔离）
+     *
+     * 不同主体可创建同名角色而互不覆盖；不传时归为平台内置角色 `system`。
+     */
+    objectId?: string;
+    /** 角色显示名（如「小P」） */
+    name?: string;
+    /** 角色系统提示词（定义身份、职责、语气） */
+    systemPrompt: string;
+    /** 性格 / 风格特征（组合进系统提示词，如「谨慎」「喜欢引用案例」） */
+    traits?: string[];
+    /** 附加元数据 */
+    metadata?: Record<string, unknown>;
 }
 /**
- * 可选参考图；Provider 会转换为对应厂商的传输格式
+ * 完整的 Persona 档案
  *
  * @example
  * ```ts
- * import type { ReferenceImage } from '@h-ai/ai'
- * import { readFile } from 'node:fs/promises'
+ * import type { PersonaProfile } from '@h-ai/ai'
  *
- * const reference: ReferenceImage = { data: await readFile('reference.png'), mimeType: 'image/png' }
+ * function label(profile: PersonaProfile): string {
+ *   return `${profile.objectId}/${profile.id}: ${profile.name ?? profile.id}`
+ * }
  * ```
  */
-interface ReferenceImage {
-    /** 图片二进制内容 */
-    data: Uint8Array;
-    /** 图片 MIME 类型，例如 `image/png`、`image/jpeg` */
-    mimeType: string;
+interface PersonaProfile {
+    /** 角色唯一标识 */
+    id: string;
+    /** 所属主体 ID（多租户隔离；平台内置角色为 `system`） */
+    objectId: string;
+    /** 角色显示名 */
+    name?: string;
+    /** 角色系统提示词 */
+    systemPrompt: string;
+    /** 性格 / 风格特征 */
+    traits: string[];
+    /** 附加元数据 */
+    metadata?: Record<string, unknown>;
+    /** 创建时间（Unix 毫秒） */
+    createdAt: number;
+    /** 更新时间（Unix 毫秒） */
+    updatedAt: number;
 }
 /**
- * 文生图请求
+ * Persona 档案更新输入
+ *
+ * 所有字段可选，仅更新传入的字段。
  *
  * @example
  * ```ts
- * import type { GenerateImageRequest } from '@h-ai/ai'
+ * import type { PersonaProfileUpdate } from '@h-ai/ai'
  *
- * const value: GenerateImageRequest = { prompt: '水墨山水，留白构图', size: { width: 1024, height: 1024 }, signal: new AbortController().signal }
+ * const value: PersonaProfileUpdate = { traits: ['简洁', '引用来源'] }
  * ```
  */
-interface GenerateImageRequest {
-    /** 图片内容与风格提示词 */
-    prompt: string;
-    /** 模型 ID；不传时使用配置中的默认文生图模型 */
-    model?: string;
-    /** 输出像素尺寸；不传时由模型决定 */
-    size?: ImageSize;
-    /** 用于图生图、编辑或风格参考的一张或多张图片 */
-    referenceImages?: ReferenceImage[];
-    /** 取消整个厂商请求和图片下载；模型 timeout 同时限制总耗时。 */
-    signal?: AbortSignal;
+interface PersonaProfileUpdate {
+    /** 更新显示名 */
+    name?: string;
+    /** 更新系统提示词 */
+    systemPrompt?: string;
+    /** 更新特征列表（整体替换） */
+    traits?: string[];
+    /** 更新元数据 */
+    metadata?: Record<string, unknown>;
 }
 /**
- * 标准化后的单张图片
+ * Persona 操作接口（通过 `ai.persona` 访问）
+ *
+ * 管理 AI 角色人格的持久化与系统提示词组合。需要先调用 `ai.init()` 初始化后使用。
  *
  * @example
  * ```ts
- * import type { GeneratedImage } from '@h-ai/ai'
+ * import { ai } from '@h-ai/ai'
  *
- * function imageBlob(image: GeneratedImage): Blob {
- *   return new Blob([Uint8Array.from(image.data)], { type: image.mimeType })
+ * // 应用启动已成功初始化 ai；这里是业务服务函数。
+ * async function run() {
+ *   const result = await ai.persona.save({ id: 'support', objectId: 'tenant-1', systemPrompt: '先核对订单状态再回答。' })
+ *   if (!result.success)
+ *     return result
+ *   const composed = await ai.persona.compose(result.data.id, { objectId: result.data.objectId })
+ *   if (!composed.success)
+ *     return composed
+ *   return composed.data
  * }
  * ```
  */
-interface GeneratedImage {
-    /** 图片二进制内容 */
-    data: Uint8Array;
-    /** 经魔数核验的栅格图片 MIME：PNG、JPEG、GIF、WebP。 */
-    mimeType: string;
-    /** 宽度提示，来自请求或厂商；未通过完整图片解码核验。 */
-    width?: number;
-    /** 高度提示，来自请求或厂商；未通过完整图片解码核验。 */
-    height?: number;
-}
+interface PersonaOperations {
+    /**
+     * 创建或覆盖保存一个角色档案（upsert 语义）
+     *
+     * @param profile - 角色档案输入
+     * @returns 保存后的完整档案
+     */
+    save: (profile: PersonaProfileInput) => Promise<HaiResult<PersonaProfile>>;
+    /**
+     * 按 ID 获取角色档案
+     *
+     * @param id - 角色 ID
+     * @returns 角色档案，不存在时返回 PERSONA_NOT_FOUND
+     */
+    get: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile>>;
+    /**
+     * 更新角色档案（仅更新传入字段）
+     *
+     * @param id - 角色 ID
+     * @param updates - 需要更新的字段
+     * @param options - 主体作用域（默认 `system`）
+     * @returns 更新后的完整档案
+     */
+    update: (id: string, updates: PersonaProfileUpdate, options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile>>;
+    /**
+     * 删除角色档案
+     *
+     * @param id - 角色 ID
+     * @param options - 主体作用域（默认 `system`）
+     * @returns 成功返回 ok(undefined)
+     */
+    remove: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<void>>;
+    /**
+     * 列出指定主体的角色档案
+     *
+     * @param options - 主体作用域（默认 `system`）
+     * @returns 角色档案列表
+     */
+    list: (options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile[]>>;
+    /**
+     * 组合角色的完整系统提示词
+     *
+     * 将 `systemPrompt` 与 `traits` 拼装为一段可直接作为 system 消息的文本，
+     * 供 `ai.context.createManager({ scope, systemPrompt })` 使用。
+     *
+     * @param id - 角色 ID
+     * @param options - 主体作用域（默认 `system`）
+     * @returns 组合后的系统提示词，角色不存在时返回 PERSONA_NOT_FOUND
+     */
+    compose: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<string>>;
+}
+/**
+ * Persona 操作的主体作用域选项
+ *
+ * @example
+ * ```ts
+ * import type { PersonaScopeOptions } from '@h-ai/ai'
+ *
+ * const value: PersonaScopeOptions = { objectId: 'tenant-1' }
+ * ```
+ */
+interface PersonaScopeOptions {
+    /** 所属主体 ID（不传时归为平台内置角色 `system`） */
+    objectId?: string;
+}
+
+/**
+ * @h-ai/ai — 文生图公共类型
+ *
+ * 公共契约只暴露业务需要的提示词、尺寸和标准化图片字节。
+ * 厂商请求字段、临时 URL 与响应中间态由 Provider 内部处理。
+ * @module image/ai-image-types
+ */
+
+/**
+ * 图片像素尺寸
+ *
+ * @example
+ * ```ts
+ * import type { ImageSize } from '@h-ai/ai'
+ *
+ * const value: ImageSize = { width: 1024, height: 1024 }
+ * ```
+ */
+interface ImageSize {
+    /** 宽度（像素） */
+    width: number;
+    /** 高度（像素） */
+    height: number;
+}
+/**
+ * 可选参考图；Provider 会转换为对应厂商的传输格式
+ *
+ * @example
+ * ```ts
+ * import type { ReferenceImage } from '@h-ai/ai'
+ * import { readFile } from 'node:fs/promises'
+ *
+ * const reference: ReferenceImage = { data: await readFile('reference.png'), mimeType: 'image/png' }
+ * ```
+ */
+interface ReferenceImage {
+    /** 图片二进制内容 */
+    data: Uint8Array;
+    /** 图片 MIME 类型，例如 `image/png`、`image/jpeg` */
+    mimeType: string;
+}
+/**
+ * 文生图请求
+ *
+ * @example
+ * ```ts
+ * import type { GenerateImageRequest } from '@h-ai/ai'
+ *
+ * const value: GenerateImageRequest = { prompt: '水墨山水，留白构图', size: { width: 1024, height: 1024 }, signal: new AbortController().signal }
+ * ```
+ */
+interface GenerateImageRequest {
+    /** 图片内容与风格提示词 */
+    prompt: string;
+    /** 模型 ID；不传时使用配置中的默认文生图模型 */
+    model?: string;
+    /** 输出像素尺寸；不传时由模型决定 */
+    size?: ImageSize;
+    /** 用于图生图、编辑或风格参考的一张或多张图片 */
+    referenceImages?: ReferenceImage[];
+    /** 取消整个厂商请求和图片下载；模型 timeout 同时限制总耗时。 */
+    signal?: AbortSignal;
+}
+/**
+ * 标准化后的单张图片
+ *
+ * @example
+ * ```ts
+ * import type { GeneratedImage } from '@h-ai/ai'
+ *
+ * function imageBlob(image: GeneratedImage): Blob {
+ *   return new Blob([Uint8Array.from(image.data)], { type: image.mimeType })
+ * }
+ * ```
+ */
+interface GeneratedImage {
+    /** 图片二进制内容 */
+    data: Uint8Array;
+    /** 经魔数核验的栅格图片 MIME：PNG、JPEG、GIF、WebP。 */
+    mimeType: string;
+    /** 宽度提示，来自请求或厂商；未通过完整图片解码核验。 */
+    width?: number;
+    /** 高度提示，来自请求或厂商；未通过完整图片解码核验。 */
+    height?: number;
+}
 /**
  * 文生图结果
  *
@@ -6690,180 +7325,159 @@ interface MCPOperations {
 }
 
 /**
- * @h-ai/ai — Persona 子功能类型
- *
- * 定义「AI 角色人格」的持久化与组合接口。Persona 解决的是「AI 是谁」的问题：
- * 多智能体场景（如多位专家同台访谈）中，每个 AI 有稳定的系统提示词、性格特征与
- * 长期人格。它与 Memory 正交——Memory 用 `objectId` / `scope` 回答「谁的记忆」，
- * Persona 回答「这个 AI 的身份与人设」，二者通过 `scope: { personaId }` 关联。
- * @module ai-persona-types
+ * 清单项与来源；配置来源不可修改，version 仅用于数据库乐观并发更新。
+ * @example
+ * ```ts
+ * import type { AIResourceEntry, ModelEntry } from '@h-ai/ai'
+ * function editable(entry: AIResourceEntry<ModelEntry>) { return entry.source === 'database' }
+ * ```
  */
-
+interface AIResourceEntry<T> {
+    /** 原始配置；返回独立副本，修改副本不会修改清单。 */
+    value: T;
+    /** config 来自初始化配置，database 来自 AIStoreProvider。 */
+    source: 'config' | 'database';
+    /** get 返回的数据库版本；更新/删除时可传回以拒绝过期写入。 */
+    version?: string;
+}
 /**
- * Persona 档案输入（创建 / 覆盖保存时使用）
- *
+ * 配置与数据库合并的资源清单。相同 ID 配置优先，配置记录永不写回数据库。
  * @example
  * ```ts
- * import type { PersonaProfileInput } from '@h-ai/ai'
- *
- * const value: PersonaProfileInput = { id: 'support', objectId: 'tenant-1', name: '客服助手', systemPrompt: '根据已验证的订单信息回答。', traits: ['简洁', '先核对证据'] }
+ * import { ai } from '@h-ai/ai'
+ * async function listModels() { const result = await ai.llm.models.list(); if (!result.success) return result; return result.data.map(item => ({ id: item.value.id, source: item.source })) }
  * ```
  */
-interface PersonaProfileInput {
-    /** 角色唯一标识（业务侧稳定 ID，如 `xiaop`） */
-    id: string;
+interface AIResourceRegistry<T, Input = T> {
     /**
-     * 所属主体 ID（多租户隔离）
-     *
-     * 不同主体可创建同名角色而互不覆盖；不传时归为平台内置角色 `system`。
+     * 读取合并清单；保留配置顺序，追加未被遮蔽的数据库项。
+     * @returns 包含 value/source 的去重列表；列表项无数据库版本。
+     * @example
+     * ```ts
+     * import { ai } from '@h-ai/ai'
+     * const result = await ai.llm.models.list()
+     * if (result.success) { const entries = result.data }
+     * ```
      */
-    objectId?: string;
-    /** 角色显示名（如「小P」） */
-    name?: string;
-    /** 角色系统提示词（定义身份、职责、语气） */
-    systemPrompt: string;
-    /** 性格 / 风格特征（组合进系统提示词，如「谨慎」「喜欢引用案例」） */
-    traits?: string[];
-    /** 附加元数据 */
-    metadata?: Record<string, unknown>;
+    list: () => Promise<HaiResult<AIResourceEntry<T>[]>>;
+    /**
+     * 按 ID 读取来源、配置和数据库版本。
+     * @param id - 资源 ID。
+     * @returns 包含 value/source/version 的资源条目，未找到时返回失败。
+     * @example
+     * ```ts
+     * import { ai } from '@h-ai/ai'
+     * const result = await ai.llm.models.get('coding')
+     * if (result.success) { const source = result.data.source }
+     * ```
+     */
+    get: (id: string) => Promise<HaiResult<AIResourceEntry<T>>>;
+    /**
+     * 新建数据库记录；ID 已存在或属于配置时拒绝。
+     * @param input - 完整资源配置。
+     * @returns 新建条目及版本的 HaiResult，配置同 ID 返回只读错误。
+     * @example
+     * ```ts
+     * import { ai } from '@h-ai/ai'
+     * const result = await ai.llm.models.register({ id: 'coding', model: 'example-model', protocol: 'responses' })
+     * if (!result.success) { const code = result.error.code }
+     * ```
+     */
+    register: (input: Input) => Promise<HaiResult<AIResourceEntry<T>>>;
+    /**
+     * 完整替换数据库记录；配置来源只读。版本不匹配时不写入。
+     * @param input - 同 ID 的完整新配置。
+     * @param expectedVersion - 可选的 get 版本。
+     * @returns 替换后的条目及版本；过期版本返回资源冲突。
+     * @example
+     * ```ts
+     * import { ai } from '@h-ai/ai'
+     * const current = await ai.llm.models.get('coding')
+     * if (current.success && current.data.source === 'database') {
+     *   const result = await ai.llm.models.update({ ...current.data.value, temperature: 0.2 }, current.data.version)
+     *   if (!result.success) { const code = result.error.code }
+     * }
+     * ```
+     */
+    update: (input: Input, expectedVersion?: string) => Promise<HaiResult<AIResourceEntry<T>>>;
+    /**
+     * 删除数据库记录，采用 CAS 墓碑避免与并发更新相互覆盖；不删除外部文件。
+     * @param id - 资源 ID。
+     * @param expectedVersion - 可选的 get 版本。
+     * @returns 删除完成的 HaiResult；配置只读、版本冲突或记录不存在时失败。
+     * @example
+     * ```ts
+     * import { ai } from '@h-ai/ai'
+     * const result = await ai.llm.models.remove('temporary')
+     * if (!result.success) { const code = result.error.code }
+     * ```
+     */
+    remove: (id: string, expectedVersion?: string) => Promise<HaiResult<void>>;
 }
 /**
- * 完整的 Persona 档案
- *
+ * 包含配置/数据库资源维护的 llm 操作接口。
  * @example
  * ```ts
- * import type { PersonaProfile } from '@h-ai/ai'
- *
- * function label(profile: PersonaProfile): string {
- *   return `${profile.objectId}/${profile.id}: ${profile.name ?? profile.id}`
- * }
+ * import { ai } from '@h-ai/ai'
+ * const result = await ai.llm.models.list()
+ * if (result.success) { const resources = result.data }
  * ```
  */
-interface PersonaProfile {
-    /** 角色唯一标识 */
-    id: string;
-    /** 所属主体 ID（多租户隔离；平台内置角色为 `system`） */
-    objectId: string;
-    /** 角色显示名 */
-    name?: string;
-    /** 角色系统提示词 */
-    systemPrompt: string;
-    /** 性格 / 风格特征 */
-    traits: string[];
-    /** 附加元数据 */
-    metadata?: Record<string, unknown>;
-    /** 创建时间（Unix 毫秒） */
-    createdAt: number;
-    /** 更新时间（Unix 毫秒） */
-    updatedAt: number;
+interface ManagedLLMOperations extends LLMOperations {
+    /** 配置只读、数据库可维护的合并清单。 */
+    models: AIResourceRegistry<z.output<typeof ModelEntrySchema>, z.input<typeof ModelEntrySchema>>;
 }
 /**
- * Persona 档案更新输入
- *
- * 所有字段可选，仅更新传入的字段。
- *
+ * 包含配置/数据库资源维护的 audio 操作接口。
  * @example
  * ```ts
- * import type { PersonaProfileUpdate } from '@h-ai/ai'
- *
- * const value: PersonaProfileUpdate = { traits: ['简洁', '引用来源'] }
+ * import { ai } from '@h-ai/ai'
+ * const result = await ai.audio.models.list()
+ * if (result.success) { const resources = result.data }
  * ```
  */
-interface PersonaProfileUpdate {
-    /** 更新显示名 */
-    name?: string;
-    /** 更新系统提示词 */
-    systemPrompt?: string;
-    /** 更新特征列表（整体替换） */
-    traits?: string[];
-    /** 更新元数据 */
-    metadata?: Record<string, unknown>;
+interface ManagedAudioOperations extends AudioOperations {
+    /** 配置只读、数据库可维护的合并清单。 */
+    models: AIResourceRegistry<z.output<typeof AudioModelEntrySchema>, z.input<typeof AudioModelEntrySchema>>;
 }
 /**
- * Persona 操作接口（通过 `ai.persona` 访问）
- *
- * 管理 AI 角色人格的持久化与系统提示词组合。需要先调用 `ai.init()` 初始化后使用。
- *
+ * 包含配置/数据库资源维护的 image 操作接口。
  * @example
  * ```ts
  * import { ai } from '@h-ai/ai'
- *
- * // 应用启动已成功初始化 ai；这里是业务服务函数。
- * async function run() {
- *   const result = await ai.persona.save({ id: 'support', objectId: 'tenant-1', systemPrompt: '先核对订单状态再回答。' })
- *   if (!result.success)
- *     return result
- *   const composed = await ai.persona.compose(result.data.id, { objectId: result.data.objectId })
- *   if (!composed.success)
- *     return composed
- *   return composed.data
- * }
+ * const result = await ai.image.models.list()
+ * if (result.success) { const resources = result.data }
  * ```
  */
-interface PersonaOperations {
-    /**
-     * 创建或覆盖保存一个角色档案（upsert 语义）
-     *
-     * @param profile - 角色档案输入
-     * @returns 保存后的完整档案
-     */
-    save: (profile: PersonaProfileInput) => Promise<HaiResult<PersonaProfile>>;
-    /**
-     * 按 ID 获取角色档案
-     *
-     * @param id - 角色 ID
-     * @returns 角色档案，不存在时返回 PERSONA_NOT_FOUND
-     */
-    get: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile>>;
-    /**
-     * 更新角色档案（仅更新传入字段）
-     *
-     * @param id - 角色 ID
-     * @param updates - 需要更新的字段
-     * @param options - 主体作用域（默认 `system`）
-     * @returns 更新后的完整档案
-     */
-    update: (id: string, updates: PersonaProfileUpdate, options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile>>;
-    /**
-     * 删除角色档案
-     *
-     * @param id - 角色 ID
-     * @param options - 主体作用域（默认 `system`）
-     * @returns 成功返回 ok(undefined)
-     */
-    remove: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<void>>;
-    /**
-     * 列出指定主体的角色档案
-     *
-     * @param options - 主体作用域（默认 `system`）
-     * @returns 角色档案列表
-     */
-    list: (options?: PersonaScopeOptions) => Promise<HaiResult<PersonaProfile[]>>;
-    /**
-     * 组合角色的完整系统提示词
-     *
-     * 将 `systemPrompt` 与 `traits` 拼装为一段可直接作为 system 消息的文本，
-     * 供 `ai.context.createManager({ scope, systemPrompt })` 使用。
-     *
-     * @param id - 角色 ID
-     * @param options - 主体作用域（默认 `system`）
-     * @returns 组合后的系统提示词，角色不存在时返回 PERSONA_NOT_FOUND
-     */
-    compose: (id: string, options?: PersonaScopeOptions) => Promise<HaiResult<string>>;
+interface ManagedImageOperations extends ImageOperations {
+    /** 配置只读、数据库可维护的合并清单。 */
+    models: AIResourceRegistry<z.output<typeof ImageModelEntrySchema>, z.input<typeof ImageModelEntrySchema>>;
 }
 /**
- * Persona 操作的主体作用域选项
- *
+ * 包含配置/数据库资源维护的 mcp 操作接口。
  * @example
  * ```ts
- * import type { PersonaScopeOptions } from '@h-ai/ai'
- *
- * const value: PersonaScopeOptions = { objectId: 'tenant-1' }
+ * import { ai } from '@h-ai/ai'
+ * const result = await ai.mcp.servers.list()
+ * if (result.success) { const resources = result.data }
  * ```
  */
-interface PersonaScopeOptions {
-    /** 所属主体 ID（不传时归为平台内置角色 `system`） */
-    objectId?: string;
+interface ManagedMCPOperations extends MCPOperations {
+    /** 配置只读、数据库可维护的合并清单。 */
+    servers: AIResourceRegistry<z.output<typeof MCPExternalServerSchema>, z.input<typeof MCPExternalServerSchema>>;
+}
+/**
+ * 包含配置/数据库资源维护的 retrieval 操作接口。
+ * @example
+ * ```ts
+ * import { ai } from '@h-ai/ai'
+ * const result = await ai.retrieval.sources.list()
+ * if (result.success) { const resources = result.data }
+ * ```
+ */
+interface ManagedRetrievalOperations extends RetrievalOperations {
+    /** 配置只读、数据库可维护的合并清单。 */
+    sources: AIResourceRegistry<z.output<typeof RetrievalSourceSchema>, z.input<typeof RetrievalSourceSchema>>;
 }
 
 /**
@@ -7046,6 +7660,21 @@ interface TokenOperations {
  */
 declare const HaiAIError: {
     readonly INTERNAL_ERROR: _h_ai_core.HaiErrorDef;
+    readonly ACP_GIT_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly ACP_OPERATION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly ACP_INVALID_REQUEST: _h_ai_core.HaiErrorDef;
+    readonly ACP_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly ACP_BUSY: _h_ai_core.HaiErrorDef;
+    readonly ACP_UNSUPPORTED: _h_ai_core.HaiErrorDef;
+    readonly ACP_CANCELLED: _h_ai_core.HaiErrorDef;
+    readonly ACP_TIMEOUT: _h_ai_core.HaiErrorDef;
+    readonly ACP_OUTPUT_INVALID: _h_ai_core.HaiErrorDef;
+    readonly ACP_CONFLICT: _h_ai_core.HaiErrorDef;
+    readonly ACP_PARTIAL_FAILURE: _h_ai_core.HaiErrorDef;
+    readonly ACP_CLOSED: _h_ai_core.HaiErrorDef;
+    readonly ACP_RUNTIME_UNAVAILABLE: _h_ai_core.HaiErrorDef;
+    readonly ACP_MODEL_INCOMPATIBLE: _h_ai_core.HaiErrorDef;
+    readonly ACP_CLEANUP_FAILED: _h_ai_core.HaiErrorDef;
     readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
     readonly CONFIGURATION_ERROR: _h_ai_core.HaiErrorDef;
     readonly INIT_IN_PROGRESS: _h_ai_core.HaiErrorDef;
@@ -7118,6 +7747,11 @@ declare const HaiAIError: {
     readonly IMAGE_DOWNLOAD_BLOCKED: _h_ai_core.HaiErrorDef;
     readonly IMAGE_TOO_LARGE: _h_ai_core.HaiErrorDef;
     readonly IMAGE_TIMEOUT: _h_ai_core.HaiErrorDef;
+    readonly RESOURCE_READ_ONLY: _h_ai_core.HaiErrorDef;
+    readonly RESOURCE_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly RESOURCE_CONFLICT: _h_ai_core.HaiErrorDef;
+    readonly RESOURCE_INVALID: _h_ai_core.HaiErrorDef;
+    readonly RESOURCE_OPERATION_FAILED: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_COMPRESS_FAILED: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_SUMMARIZE_FAILED: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_TOKEN_ESTIMATE_FAILED: _h_ai_core.HaiErrorDef;
@@ -7152,6 +7786,8 @@ declare const HaiAIError: {
  * ```
  */
 interface AIInitOptions {
+    /** 可信服务端扩展：为其他 ACP 智能体生成原生配置。 */
+    acpAdapters?: Record<string, ACPAgentAdapter>;
     /**
      * 自定义存储 Provider
      *
@@ -7208,9 +7844,11 @@ interface AIFunctions {
     /** 是否已初始化（`init()` 成功后为 `true`，`close()` 后为 `false`） */
     readonly isInitialized: boolean;
     /** LLM 操作（聊天、流式、模型列表），需要先调用 `init()` */
-    readonly llm: LLMOperations;
-    /** MCP 操作（工具/资源/提示词注册与调用），需要先调用 `init()` */
-    readonly mcp: MCPOperations;
+    readonly llm: ManagedLLMOperations;
+    /** ACP 智能体、工作区与原生会话，需要先调用 `init()`。 */
+    readonly acp: ACPOperations;
+    /** MCP 本地函数注册及配置/数据库外部服务清单，需要先调用 `init()`。 */
+    readonly mcp: ManagedMCPOperations;
     /** 工具操作（定义工具与注册表），纯函数，无需初始化 */
     readonly tools: ToolsOperations;
     /** 流处理操作（流处理器、SSE 编解码），纯函数，无需初始化 */
@@ -7220,7 +7858,7 @@ interface AIFunctions {
     /** 推理操作（ReAct / CoT / Plan-Execute），需要先调用 `init()` */
     readonly reasoning: ReasoningOperations;
     /** 检索操作（向量检索），需要先调用 `init()` */
-    readonly retrieval: RetrievalOperations;
+    readonly retrieval: ManagedRetrievalOperations;
     /** RAG 操作（检索增强生成），需要先调用 `init()` */
     readonly rag: RagOperations;
     /** Knowledge 操作（知识库管理与检索），需要先调用 `init()` 和 `knowledge.setup()` */
@@ -7244,9 +7882,9 @@ interface AIFunctions {
     /** A2A 操作（Agent-to-Agent 协议），需要先调用 `init()` 并配置 `a2a` */
     readonly a2a: A2AOperations;
     /** Audio 操作（语音识别 / 语音合成），需要先调用 `init()` 并配置 `audio` */
-    readonly audio: AudioOperations;
+    readonly audio: ManagedAudioOperations;
     /** Image 操作（文生图），需要先调用 `init()` 并配置 `image` */
-    readonly image: ImageOperations;
+    readonly image: ManagedImageOperations;
 }
 
 /** @h-ai/ai — 音频播放负载序列化 */
@@ -7602,4 +8240,1524 @@ interface AudioWsEndMessage {
  */
 type AudioWsServerMessage = AudioWsSpeechMessage | AudioWsTranscriptMessage | AudioWsSegmentStartedMessage | AudioWsSegmentDoneMessage | AudioWsErrorMessage | AudioWsEndMessage;
 
-export { AudioWsStartMessageSchema as $, type A2AAgentCardConfig as A, AUDIO_WS_PATH as B, type ApiType as C, ApiTypeSchema as D, type AskOptions as E, type AssistantMessage as F, type AudioConfig as G, AudioConfigSchema as H, AudioFormatSchema as I, type AudioModelEntry as J, AudioModelEntrySchema as K, type AudioOperation as L, AudioOperationSchema as M, AudioOperationsSchema as N, type AudioProviderName as O, AudioProviderSchema as P, type AudioWsClientMessage as Q, AudioWsClientMessageSchema as R, type AudioWsDoneMessage as S, AudioWsDoneMessageSchema as T, type AudioWsEndMessage as U, type AudioWsErrorMessage as V, type AudioWsSegmentDoneMessage as W, type AudioWsSegmentStartedMessage as X, type AudioWsServerMessage as Y, type AudioWsSpeechMessage as Z, type AudioWsStartMessage as _, type A2AApiKeySecurity as a, type ImageProviderName as a$, type AudioWsTextMessage as a0, AudioWsTextMessageSchema as a1, type AudioWsTranscriptMessage as a2, type ChatCompletionChoice as a3, type ChatCompletionChunk as a4, type ChatCompletionDelta as a5, type ChatCompletionRequest as a6, type ChatCompletionResponse as a7, type ChatHistoryOptions as a8, type ChatMessage as a9, type EmbeddingOperations as aA, type EmbeddingRequest as aB, type EmbeddingResponse as aC, type EntityDocumentRelation as aD, type EntityDocumentResult as aE, type EntityListOptions as aF, type EntityQueryOptions as aG, type EntityType as aH, EntityTypeSchema as aI, type FileConfig as aJ, FileConfigSchema as aK, type FileOperations as aL, type FileParseMethod as aM, type FileParseOptions as aN, type FileParseRequest as aO, type FileParseResult as aP, type GenerateImageRequest as aQ, type GenerateImageResult as aR, type GenerateObjectRequest as aS, type GeneratedImage as aT, HaiAIError as aU, type ImageConfig as aV, ImageConfigSchema as aW, type ImageContent as aX, type ImageModelEntry as aY, ImageModelEntrySchema as aZ, type ImageOperations as a_, type ChatRecord as aa, type Citation as ab, type CommitTurnInput as ac, type CompressConfig as ad, CompressConfigSchema as ae, type CompressOperations as af, type CompressOptions as ag, type CompressResult as ah, type CompressionStrategy as ai, CompressionStrategySchema as aj, type ConsolidateOptions as ak, type ConsolidateResult as al, type ContextChatOptions as am, type ContextChatResult as an, type ContextManager as ao, type ContextManagerOptions as ap, type ContextOperations as aq, type ContextResetOptions as ar, type ContextStreamEvent as as, type ConversationTurn as at, type ConversationTurnStatus as au, type DefineToolOptions as av, type DeveloperMessage as aw, type EmbeddingConfig as ax, EmbeddingConfigSchema as ay, type EmbeddingItem as az, type A2AAuthenticator as b, MemoryTypeSchema as b$, ImageProviderSchema as b0, type ImageSize as b1, type InteractionScope as b2, type KnowledgeAskOptions as b3, type KnowledgeAskResult as b4, type KnowledgeConfig as b5, KnowledgeConfigSchema as b6, type KnowledgeDocumentInfo as b7, type KnowledgeDocumentListOptions as b8, type KnowledgeDocumentMetadata as b9, type MCPPromptContent as bA, type MCPPromptMessage as bB, type MCPResource as bC, type MCPResourceContent as bD, type MCPServerCapabilities as bE, MCPServerCapabilitiesSchema as bF, type MCPServerConfig as bG, MCPServerConfigSchema as bH, type MCPToolDefinition as bI, type MCPToolHandler as bJ, type McpServerOptions as bK, type MemoryAccessScope as bL, type MemoryAdminOperations as bM, type MemoryClearAllOptions as bN, type MemoryClearOptions as bO, type MemoryConfig as bP, MemoryConfigSchema as bQ, type MemoryCoreOperations as bR, type MemoryEntry as bS, type MemoryEntryInput as bT, type MemoryExtractOptions as bU, type MemoryInjectionOptions as bV, type MemoryListOptions as bW, type MemoryListPageOptions as bX, type MemoryOperations as bY, type MemoryRecallOptions as bZ, type MemoryType as b_, type KnowledgeDocumentRemoveOptions as ba, type KnowledgeDocumentRevision as bb, type KnowledgeEntity as bc, type KnowledgeIngestBatchProgress as bd, type KnowledgeIngestBatchResult as be, type KnowledgeIngestFileInput as bf, type KnowledgeIngestInput as bg, type KnowledgeIngestResult as bh, type KnowledgeOperations as bi, type KnowledgeRepairOptions as bj, type KnowledgeRepairProgress as bk, type KnowledgeRepairResult as bl, type KnowledgeRetrieveItem as bm, type KnowledgeRetrieveOptions as bn, type KnowledgeRetrieveResult as bo, type KnowledgeSetupOptions as bp, type KnowledgeStore as bq, type LLMConfig as br, LLMConfigSchema as bs, type LLMOperations as bt, type MCPConfig as bu, MCPConfigSchema as bv, type MCPContext as bw, type MCPOperations as bx, type MCPPrompt as by, type MCPPromptArgument as bz, type A2ACallOptions as c, type TempModelConfig as c$, type MemoryUpdateInput as c0, type MessageContent as c1, type MessageRole as c2, type ModelEntry as c3, ModelEntrySchema as c4, type ModelScenario as c5, ModelScenarioSchema as c6, type ObjectRef as c7, OptionalSecretSchema as c8, type OutputFormat as c9, type ResolvedModelConfig as cA, type RetrievalConfig as cB, RetrievalConfigSchema as cC, type RetrievalOperations as cD, type RetrievalRequest as cE, type RetrievalResult as cF, type RetrievalResultItem as cG, type RetrievalSource as cH, type RetrievalSourceConfig as cI, RetrievalSourceSchema as cJ, type SSEDecoder as cK, type SSEEvent as cL, type ScopedMemoryBinding as cM, type ScopedMemoryOperations as cN, type SessionInfo as cO, type StoreFilter as cP, type StorePage as cQ, type StoreScope as cR, type StreamOperations as cS, type StreamProcessor as cT, type StreamResult as cU, type SummaryConfig as cV, SummaryConfigSchema as cW, type SummaryOperations as cX, type SummaryOptions as cY, type SummaryResult as cZ, type SystemMessage as c_, type PersonaOperations as ca, type PersonaProfile as cb, type PersonaProfileInput as cc, type PersonaProfileUpdate as cd, type PersonaScopeOptions as ce, type RagContextItem as cf, type RagOperations as cg, type RagOptions as ch, type RagResult as ci, type RagStreamEvent as cj, type ReasoningOperations as ck, type ReasoningOptions as cl, type ReasoningResult as cm, type ReasoningStep as cn, type ReasoningStepType as co, type ReasoningStrategy as cp, type ReasoningStreamEvent as cq, type ReferenceImage as cr, type RerankDocument as cs, type RerankItem as ct, type RerankOperations as cu, type RerankRequest as cv, type RerankResponse as cw, type ResolveRequiredModelEntryOptions as cx, type ResolvedAudioModel as cy, type ResolvedImageModel as cz, type A2ACallResult as d, type TextContent as d0, type TokenConfig as d1, TokenConfigSchema as d2, type TokenOperations as d3, type TokenUsage as d4, type Tool as d5, type ToolAuthorizationRequest as d6, type ToolAuthorizer as d7, type ToolCall as d8, type ToolDefinition as d9, type ToolErrorType as da, type ToolExecutionContext as db, type ToolExecutionOptions as dc, type ToolMessage as dd, type ToolRegistryOperations as de, type ToolRegistryOptions as df, type ToolsOperations as dg, type UserMessage as dh, type WhereClause as di, type WhereOperator as dj, type WhereValue as dk, ensureAudioCredential as dl, resolveAudioModel as dm, resolveImageModel as dn, resolveModelApi as dp, resolveModelEntry as dq, serializePlayableAudio as dr, type A2ACallerIdentity as e, type A2AConfig as f, A2AConfigSchema as g, type A2AContextInfo as h, type A2AHandleResult as i, type A2AMessageRecord as j, type A2AOperations as k, type A2ASecurityConfig as l, A2ASkillConfigSchema as m, type A2ATaskFilter as n, type AIConfig as o, type AIConfigInput as p, AIConfigSchema as q, type AIFunctions as r, type AIInitOptions as s, type AIRelStore as t, type AIRelStoreCompareAndSwap as u, type AIRelStoreOptions as v, type AIStoreProvider as w, type AIVectorBackend as x, type AIVectorStore as y, type AIVersionedRecord as z };
+/**
+ * ACP 子系统；资源占用通过 CAS 持久化，不以超时推断失联进程已停止。
+ * @param provider - 与 AI 模块共享的持久存储；工厂创建表后由调用方统一初始化。
+ * @param config - 经 AIConfigSchema 校验的模块配置，包括只读智能体和工作区。
+ * @param extensions - 可信原生配置适配器，可覆盖同名内置适配器。
+ * @param modelConfig - 获取包含数据库模型的实时配置；默认使用初始化配置。
+ * @param mcpLookup - 将合并清单 ID 解析为原生 MCP 定义，启动时解析环境变量。
+ * @returns 智能体、工作区、会话管理器和低层连接入口；业务失败返回 HaiResult。
+ * @example
+ * ```ts
+ * // 模块内部上下文；存储在工厂创建所有表后统一初始化。
+ * async function assemble(provider: AIStoreProvider, config: AIConfig) { const acp = createACPOperations(provider, config); await provider.initialize(); return acp }
+ * ```
+ */
+declare function createACPOperations(provider: AIStoreProvider, config: AIConfig, extensions?: Record<string, ACPAgentAdapter>, modelConfig?: () => Promise<AIConfig>, mcpLookup?: (ids: string[]) => Promise<McpServer[]>): {
+    agents: {
+        /**
+         * 校验模型与适配器后新增数据库智能体；配置同名条目只读。
+         * @param input - 完整智能体定义，必须引用已有 Hai 模型 ID。
+         * @returns 带 source/version 的新增条目；配置同 ID 返回只读错误。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.agents.register({ id: 'coder', name: 'Coder', mode: 'embedded', adapter: 'codex', modelIds: ['coding'] })
+         * ```
+         */
+        register: (input: z.input<typeof ACPAgentSchema>) => Promise<HaiResult<AIResourceEntry<{
+            mode: "custom-service";
+            transport: "http" | "ws";
+            url: string;
+            headerEnv: Record<string, string>;
+            supportedTransports: ("http" | "ws")[];
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            defaultModelId?: string | undefined;
+        } | {
+            mode: "embedded";
+            transport: "stdio";
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            defaultModelId?: string | undefined;
+        } | {
+            mode: "builtin-service";
+            transport: "stdio";
+            image: string;
+            engine: "auto" | "podman" | "docker";
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            defaultModelId?: string | undefined;
+        }>>>;
+        /**
+         * 按 ID 读取合并清单条目；source 区分配置与数据库，数据库 get 返回 version。
+         * @param id - 智能体 ID。
+         * @returns 合并后的资源条目；未找到时返回资源不存在错误。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.agents.get('coder')
+         * ```
+         */
+        get: (id: string) => Promise<HaiResult<AIResourceEntry<{
+            mode: "custom-service";
+            transport: "http" | "ws";
+            url: string;
+            headerEnv: Record<string, string>;
+            supportedTransports: ("http" | "ws")[];
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            defaultModelId?: string | undefined;
+        } | {
+            mode: "embedded";
+            transport: "stdio";
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            defaultModelId?: string | undefined;
+        } | {
+            mode: "builtin-service";
+            transport: "stdio";
+            image: string;
+            engine: "auto" | "podman" | "docker";
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            defaultModelId?: string | undefined;
+        }>>>;
+        /**
+         * 列出配置与数据库合并后的智能体；同 ID 配置优先。
+         * @returns 去重后的智能体条目列表；列表项不带数据库 version。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.agents.list()
+         * ```
+         */
+        list: () => Promise<HaiResult<AIResourceEntry<{
+            mode: "custom-service";
+            transport: "http" | "ws";
+            url: string;
+            headerEnv: Record<string, string>;
+            supportedTransports: ("http" | "ws")[];
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            defaultModelId?: string | undefined;
+        } | {
+            mode: "embedded";
+            transport: "stdio";
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            defaultModelId?: string | undefined;
+        } | {
+            mode: "builtin-service";
+            transport: "stdio";
+            image: string;
+            engine: "auto" | "podman" | "docker";
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            defaultModelId?: string | undefined;
+        }>[]>>;
+        /**
+         * 整体替换数据库智能体；可传入 get 返回的版本防止覆盖并发修改，配置条目不可改。
+         * @param input - 包含原 ID 的完整替换定义。
+         * @param version - get 返回的数据库版本；传入时校验并发修改。
+         * @returns 更新后的资源条目；配置只读、版本冲突均返回失败。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // definition 为完整替换定义；entry 为 get 成功返回的条目。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.agents.update(definition, entry.version)
+         * ```
+         */
+        update: (input: z.input<typeof ACPAgentSchema>, version?: string) => Promise<HaiResult<AIResourceEntry<{
+            mode: "custom-service";
+            transport: "http" | "ws";
+            url: string;
+            headerEnv: Record<string, string>;
+            supportedTransports: ("http" | "ws")[];
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            defaultModelId?: string | undefined;
+        } | {
+            mode: "embedded";
+            transport: "stdio";
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            defaultModelId?: string | undefined;
+        } | {
+            mode: "builtin-service";
+            transport: "stdio";
+            image: string;
+            engine: "auto" | "podman" | "docker";
+            id: string;
+            name: string;
+            enabled: boolean;
+            adapter: string;
+            modelIds: string[];
+            environmentRefs: Record<string, string>;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            defaultModelId?: string | undefined;
+        }>>>;
+        /**
+         * 删除无会话引用的数据库智能体定义；不删除镜像或外部服务。
+         * @param id - 数据库智能体 ID。
+         * @param version - 可选的期望版本。
+         * @returns 删除完成的 HaiResult；存在会话引用时返回 ACP_BUSY。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // entry 为 get 成功返回的数据库条目。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.agents.remove('coder', entry.version)
+         * ```
+         */
+        remove: (id: string, version?: string) => Promise<HaiResult<void>>;
+        /**
+         * 解析模型和原生配置，验证适配器是否兼容；不持久保存模型凭据。
+         * @param id - 已登记智能体 ID。
+         * @param modelId - 可选模型 ID，须在智能体 modelIds 中。
+         * @returns 智能体模式与绑定模型摘要；不返回凭据或原生配置内容。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.agents.initialize('coder')
+         * ```
+         */
+        initialize: (id: string, modelId?: string) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: {
+                agentId: string;
+                mode: "custom-service";
+                modelIds: never[];
+            } | {
+                agentId: string;
+                mode: "embedded" | "builtin-service";
+                modelIds: string[];
+            };
+        }>;
+        /**
+         * 实际启动并握手后关闭连接，返回智能体能力；托管模式需指定工作区。
+         * @param id - 已登记智能体 ID。
+         * @param options - 回调、能力及工作区；托管模式必须传 workspaceId。
+         * @returns 原生初始化结果（智能体能力、认证方法等）的 HaiResult。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.agents.check('coder', { workspaceId: 'project' })
+         * ```
+         */
+        check: (id: string, options?: ACPClientOptions & {
+            workspaceId?: string;
+        }) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: _agentclientprotocol_sdk.InitializeResponse;
+        }>;
+    };
+    workspaces: {
+        /**
+         * 新增数据库工作区并归一化存储位置；拒绝目录重叠或同一 volume 重复登记。
+         * @param input - 工作区存储位置、显式 Git 主分支和环境变量引用。
+         * @returns 带来源和版本的工作区条目；重叠位置返回冲突错误。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.workspaces.register({ id: 'project', storage: { type: 'directory', path: '/srv/project' } })
+         * ```
+         */
+        register: (input: z.input<typeof ACPWorkspaceSchema>) => Promise<HaiResult<AIResourceEntry<{
+            id: string;
+            storage: {
+                type: "directory";
+                path: string;
+            } | {
+                type: "volume";
+                name: string;
+                engine: "auto" | "podman" | "docker";
+                image: string;
+            };
+            repositories: {
+                id: string;
+                url: string;
+                mainBranch: string;
+                remote: string;
+            }[];
+            environmentRefs: Record<string, string>;
+        }>>>;
+        /**
+         * 读取工作区定义及来源；配置条目无数据库版本。
+         * @param id - 工作区 ID。
+         * @returns 工作区资源条目；未找到时返回资源不存在错误。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.workspaces.get('project')
+         * ```
+         */
+        get: (id: string) => Promise<HaiResult<AIResourceEntry<{
+            id: string;
+            storage: {
+                type: "directory";
+                path: string;
+            } | {
+                type: "volume";
+                name: string;
+                engine: "auto" | "podman" | "docker";
+                image: string;
+            };
+            repositories: {
+                id: string;
+                url: string;
+                mainBranch: string;
+                remote: string;
+            }[];
+            environmentRefs: Record<string, string>;
+        }>>>;
+        /**
+         * 列出配置与数据库合并后的工作区；不创建路径或克隆工程。
+         * @returns 去重后的工作区列表；列表项不含数据库 version。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.workspaces.list()
+         * ```
+         */
+        list: () => Promise<HaiResult<AIResourceEntry<{
+            id: string;
+            storage: {
+                type: "directory";
+                path: string;
+            } | {
+                type: "volume";
+                name: string;
+                engine: "auto" | "podman" | "docker";
+                image: string;
+            };
+            repositories: {
+                id: string;
+                url: string;
+                mainBranch: string;
+                remote: string;
+            }[];
+            environmentRefs: Record<string, string>;
+        }>[]>>;
+        /**
+         * 整体替换无会话引用的数据库工作区，重新检查存储位置重叠；配置条目不可修改。
+         * @param input - 包含原 ID 的完整替换定义。
+         * @param version - 可选的数据库期望版本。
+         * @returns 更新后的工作区；有会话引用、位置冲突或版本冲突时失败。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // definition 为完整替换定义；entry 为 get 成功返回的条目。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.workspaces.update(definition, entry.version)
+         * ```
+         */
+        update: (input: z.input<typeof ACPWorkspaceSchema>, version?: string) => Promise<HaiResult<AIResourceEntry<{
+            id: string;
+            storage: {
+                type: "directory";
+                path: string;
+            } | {
+                type: "volume";
+                name: string;
+                engine: "auto" | "podman" | "docker";
+                image: string;
+            };
+            repositories: {
+                id: string;
+                url: string;
+                mainBranch: string;
+                remote: string;
+            }[];
+            environmentRefs: Record<string, string>;
+        }>>>;
+        /**
+         * 创建目录并克隆缺失工程；已有内容不自动 pull 或覆盖，Git 不存在时返回明确错误。
+         * @param id - 已登记工作区 ID。
+         * @returns 准备后的 main 绝对目录；克隆失败保留现场供检查。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.workspaces.prepare('project')
+         * ```
+         */
+        prepare: (id: string) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: string;
+        }>;
+        /**
+         * 将有限大小的文件写入 main/files，拒绝覆盖、路径逃逸和符号链接；失败前已写入文件会保留。
+         * @param id - 已登记工作区 ID。
+         * @param files - 相对路径和 UTF-8 文本或二进制；不允许覆盖或路径逃逸。
+         * @returns 已导入相对路径列表；写入中途失败不回滚已有文件。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.workspaces.importFiles('project', [{ path: 'notes.txt', content: '需求' }])
+         * ```
+         */
+        importFiles: (id: string, files: Array<{
+            path: string;
+            content: string | Uint8Array;
+        }>) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: {
+                imported: string[];
+            };
+        }>;
+        /**
+         * 移除无会话引用的数据库定义，保留磁盘目录、Git 检出和 volume。
+         * @param id - 数据库工作区 ID。
+         * @param version - 可选的数据库期望版本。
+         * @returns 删除定义的 HaiResult；引用存在时失败，文件始终保留。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // entry 为 get 成功返回的数据库条目。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.workspaces.remove('project', entry.version)
+         * ```
+         */
+        remove: (id: string, version?: string) => Promise<HaiResult<void>>;
+    };
+    sessions: {
+        /**
+         * 绑定模型、工作区和 MCP，准备目录后建立原生会话；newWorktree 可选择独立工程分支。
+         * @param options - 智能体、工作区、模型、MCP 及可信回调；newWorktree 默认 false。
+         * @returns 可用于 prompt/stream/publish 的会话句柄；启动失败保留失败记录。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.sessions.create({ agentId: 'coder', workspaceId: 'project', newWorktree: true })
+         * ```
+         */
+        create: (options: ACPCreateSessionOptions) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: {
+                id: string;
+                /**
+                 * 读取持久会话信息，包括状态、原生 ID 和当前容器。
+                 * @returns 包含 ACPSessionInfo 的 HaiResult；记录不存在时返回失败。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.info()
+                 * ```
+                 */
+                info: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPSessionInfo;
+                }>;
+                /**
+                 * 发送一轮内容，等待最终停止原因、最终消息文本和完整事件；同一会话不允许并发轮次。
+                 * @param content - 原生 ACP 内容块，不允许同一会话并发执行。
+                 * @param signal - 本轮取消信号；取消超时会关闭连接。
+                 * @returns 最终文本、停止原因和事件的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.prompt([{ type: 'text', text: '检查工程' }])
+                 * ```
+                 */
+                prompt: (content: ContentBlock[], signal?: AbortSignal) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: {
+                        text: string;
+                        events: SessionNotification[];
+                        stopReason: _agentclientprotocol_sdk.StopReason;
+                        _meta?: {
+                            [key: string]: unknown;
+                        } | null;
+                    };
+                }>;
+                /**
+                 * 仅接受正常结束的一份 JSON（允许完整 JSON 代码围栏），再按 schema 校验；前后夹杂文本视为失败。
+                 * @param content - 要求返回结构化 JSON 的原生内容块。
+                 * @param schema - 最终 JSON 的 Zod 校验器。
+                 * @param signal - 可选的本轮取消信号。
+                 * @returns 经过 schema 校验的数据；输出不合法时返回 ACP_OUTPUT_INVALID。
+                 * @example
+                 * ```ts
+                 * import { z } from 'zod'
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.promptStructured([{ type: 'text', text: '返回 JSON' }], z.object({ ok: z.boolean() }))
+                 * ```
+                 */
+                promptStructured: <T>(content: ContentBlock[], schema: z.ZodType<T>, signal?: AbortSignal) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: Awaited<T>;
+                }>;
+                /**
+                 * 迭代本轮 ACP 事件；中途退出迭代会取消本轮，失败会抛错，调用方需 try/finally 清理。
+                 * @param content - 本轮原生内容块。
+                 * @param signal - 可选取消信号；结束迭代同样会取消本轮。
+                 * @returns 异步事件迭代器；流式失败抛出异常，需在调用方捕获。
+                 * @throws 连接关闭、取消超时、输出超限或原生请求失败。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * for await (const event of session.stream([{ type: 'text', text: '检查工程' }])) { const update = event.update }
+                 * ```
+                 */
+                stream(content: ContentBlock[], signal?: AbortSignal): AsyncGenerator<SessionNotification>;
+                /**
+                 * 请求取消正在执行的一轮；超时未停止时关闭所拥有的传输。
+                 * @returns 取消完成的 HaiResult；超时或清理失败返回错误。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.cancel()
+                 * ```
+                 */
+                cancel: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: void;
+                }>;
+                /**
+                 * 选择智能体公布的原生模式 ID；不兼容时返回协议失败。
+                 * @param mode - 握手或事件中公布的原生模式 ID。
+                 * @returns 原生模式设置结果的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.setMode('code')
+                 * ```
+                 */
+                setMode: (mode: string) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: _agentclientprotocol_sdk.SetSessionModeResponse;
+                }>;
+                /**
+                 * 设置智能体公布的原生配置选项；值必须符合该智能体的选项定义。
+                 * @param key - 原生配置选项 ID。
+                 * @param value - 该选项允许的值。
+                 * @returns 原生配置更新结果的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.setConfigOption('model', 'coding')
+                 * ```
+                 */
+                setConfigOption: (key: string, value: string) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: _agentclientprotocol_sdk.SetSessionConfigOptionResponse;
+                }>;
+                /**
+                 * 先关闭会话执行环境，再 fetch 并仅快进各工程明确配置的主分支；不修改会话分支。
+                 * @returns 各仓更新报告；部分失败时报告位于 error.cause.reports。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.updateMain()
+                 * ```
+                 */
+                updateMain: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPGitReport[];
+                }>;
+                /**
+                 * 关闭执行环境后逐仓提交并推送；仅支持受管理的独立会话，部分失败保留各仓报告，禁止强推。
+                 * @param request - 发布模式、提交说明和作者；仅支持受管理的独立会话。
+                 * @returns 各仓提交/推送报告；部分失败时报告位于 error.cause.reports。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.publish({ mode: 'merge-main', message: '完成任务', author: { name: 'Developer', email: 'dev@example.com' } })
+                 * ```
+                 */
+                publish: (request: z.input<typeof ACPPublishSchema>) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPGitReport[];
+                }>;
+                /**
+                 * 停止拥有的进程或容器，释放占用；保留工作目录和原生状态，供后续显式恢复。
+                 * @returns 关闭完成的 HaiResult；清理失败时不释放仍在占用的资源。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.close()
+                 * ```
+                 */
+                close: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: void;
+                }>;
+            };
+        }>;
+        /**
+         * 获取持久会话的管理句柄；已关闭会话需要 resume 后才能执行 prompt。
+         * @param id - 框架会话 ID，不是智能体原生 ID。
+         * @returns 管理句柄的 HaiResult；不会自动重新启动智能体。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.sessions.get('task-1')
+         * ```
+         */
+        get: (id: string) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: {
+                id: string;
+                /**
+                 * 读取持久会话信息，包括状态、原生 ID 和当前容器。
+                 * @returns 包含 ACPSessionInfo 的 HaiResult；记录不存在时返回失败。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.info()
+                 * ```
+                 */
+                info: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPSessionInfo;
+                }>;
+                /**
+                 * 发送一轮内容，等待最终停止原因、最终消息文本和完整事件；同一会话不允许并发轮次。
+                 * @param content - 原生 ACP 内容块，不允许同一会话并发执行。
+                 * @param signal - 本轮取消信号；取消超时会关闭连接。
+                 * @returns 最终文本、停止原因和事件的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.prompt([{ type: 'text', text: '检查工程' }])
+                 * ```
+                 */
+                prompt: (content: ContentBlock[], signal?: AbortSignal) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: {
+                        text: string;
+                        events: SessionNotification[];
+                        stopReason: _agentclientprotocol_sdk.StopReason;
+                        _meta?: {
+                            [key: string]: unknown;
+                        } | null;
+                    };
+                }>;
+                /**
+                 * 仅接受正常结束的一份 JSON（允许完整 JSON 代码围栏），再按 schema 校验；前后夹杂文本视为失败。
+                 * @param content - 要求返回结构化 JSON 的原生内容块。
+                 * @param schema - 最终 JSON 的 Zod 校验器。
+                 * @param signal - 可选的本轮取消信号。
+                 * @returns 经过 schema 校验的数据；输出不合法时返回 ACP_OUTPUT_INVALID。
+                 * @example
+                 * ```ts
+                 * import { z } from 'zod'
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.promptStructured([{ type: 'text', text: '返回 JSON' }], z.object({ ok: z.boolean() }))
+                 * ```
+                 */
+                promptStructured: <T>(content: ContentBlock[], schema: z.ZodType<T>, signal?: AbortSignal) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: Awaited<T>;
+                }>;
+                /**
+                 * 迭代本轮 ACP 事件；中途退出迭代会取消本轮，失败会抛错，调用方需 try/finally 清理。
+                 * @param content - 本轮原生内容块。
+                 * @param signal - 可选取消信号；结束迭代同样会取消本轮。
+                 * @returns 异步事件迭代器；流式失败抛出异常，需在调用方捕获。
+                 * @throws 连接关闭、取消超时、输出超限或原生请求失败。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * for await (const event of session.stream([{ type: 'text', text: '检查工程' }])) { const update = event.update }
+                 * ```
+                 */
+                stream(content: ContentBlock[], signal?: AbortSignal): AsyncGenerator<SessionNotification>;
+                /**
+                 * 请求取消正在执行的一轮；超时未停止时关闭所拥有的传输。
+                 * @returns 取消完成的 HaiResult；超时或清理失败返回错误。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.cancel()
+                 * ```
+                 */
+                cancel: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: void;
+                }>;
+                /**
+                 * 选择智能体公布的原生模式 ID；不兼容时返回协议失败。
+                 * @param mode - 握手或事件中公布的原生模式 ID。
+                 * @returns 原生模式设置结果的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.setMode('code')
+                 * ```
+                 */
+                setMode: (mode: string) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: _agentclientprotocol_sdk.SetSessionModeResponse;
+                }>;
+                /**
+                 * 设置智能体公布的原生配置选项；值必须符合该智能体的选项定义。
+                 * @param key - 原生配置选项 ID。
+                 * @param value - 该选项允许的值。
+                 * @returns 原生配置更新结果的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.setConfigOption('model', 'coding')
+                 * ```
+                 */
+                setConfigOption: (key: string, value: string) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: _agentclientprotocol_sdk.SetSessionConfigOptionResponse;
+                }>;
+                /**
+                 * 先关闭会话执行环境，再 fetch 并仅快进各工程明确配置的主分支；不修改会话分支。
+                 * @returns 各仓更新报告；部分失败时报告位于 error.cause.reports。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.updateMain()
+                 * ```
+                 */
+                updateMain: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPGitReport[];
+                }>;
+                /**
+                 * 关闭执行环境后逐仓提交并推送；仅支持受管理的独立会话，部分失败保留各仓报告，禁止强推。
+                 * @param request - 发布模式、提交说明和作者；仅支持受管理的独立会话。
+                 * @returns 各仓提交/推送报告；部分失败时报告位于 error.cause.reports。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.publish({ mode: 'merge-main', message: '完成任务', author: { name: 'Developer', email: 'dev@example.com' } })
+                 * ```
+                 */
+                publish: (request: z.input<typeof ACPPublishSchema>) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPGitReport[];
+                }>;
+                /**
+                 * 停止拥有的进程或容器，释放占用；保留工作目录和原生状态，供后续显式恢复。
+                 * @returns 关闭完成的 HaiResult；清理失败时不释放仍在占用的资源。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.close()
+                 * ```
+                 */
+                close: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: void;
+                }>;
+            };
+        }>;
+        /**
+         * 列出持久会话，可按工作区 ID 过滤。
+         * @param workspaceId - 可选工作区筛选条件；省略返回全部会话。
+         * @returns 持久 ACPSessionInfo 列表的 HaiResult。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.sessions.list('project')
+         * ```
+         */
+        list: (workspaceId?: string) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: ACPSessionInfo[];
+        }>;
+        /**
+         * 使用原生会话 ID 和保留状态恢复；智能体定义或模型能力已改变时拒绝恢复。
+         * @param id - 已关闭或失败的框架会话 ID。
+         * @param options - 本次连接的回调、能力和取消信号，不从数据库恢复回调。
+         * @returns 恢复后的会话句柄；原生服务不支持恢复或配置变化时失败。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.sessions.resume('task-1')
+         * ```
+         */
+        resume: (id: string, options?: ACPClientOptions) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: {
+                id: string;
+                /**
+                 * 读取持久会话信息，包括状态、原生 ID 和当前容器。
+                 * @returns 包含 ACPSessionInfo 的 HaiResult；记录不存在时返回失败。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.info()
+                 * ```
+                 */
+                info: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPSessionInfo;
+                }>;
+                /**
+                 * 发送一轮内容，等待最终停止原因、最终消息文本和完整事件；同一会话不允许并发轮次。
+                 * @param content - 原生 ACP 内容块，不允许同一会话并发执行。
+                 * @param signal - 本轮取消信号；取消超时会关闭连接。
+                 * @returns 最终文本、停止原因和事件的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.prompt([{ type: 'text', text: '检查工程' }])
+                 * ```
+                 */
+                prompt: (content: ContentBlock[], signal?: AbortSignal) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: {
+                        text: string;
+                        events: SessionNotification[];
+                        stopReason: _agentclientprotocol_sdk.StopReason;
+                        _meta?: {
+                            [key: string]: unknown;
+                        } | null;
+                    };
+                }>;
+                /**
+                 * 仅接受正常结束的一份 JSON（允许完整 JSON 代码围栏），再按 schema 校验；前后夹杂文本视为失败。
+                 * @param content - 要求返回结构化 JSON 的原生内容块。
+                 * @param schema - 最终 JSON 的 Zod 校验器。
+                 * @param signal - 可选的本轮取消信号。
+                 * @returns 经过 schema 校验的数据；输出不合法时返回 ACP_OUTPUT_INVALID。
+                 * @example
+                 * ```ts
+                 * import { z } from 'zod'
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.promptStructured([{ type: 'text', text: '返回 JSON' }], z.object({ ok: z.boolean() }))
+                 * ```
+                 */
+                promptStructured: <T>(content: ContentBlock[], schema: z.ZodType<T>, signal?: AbortSignal) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: Awaited<T>;
+                }>;
+                /**
+                 * 迭代本轮 ACP 事件；中途退出迭代会取消本轮，失败会抛错，调用方需 try/finally 清理。
+                 * @param content - 本轮原生内容块。
+                 * @param signal - 可选取消信号；结束迭代同样会取消本轮。
+                 * @returns 异步事件迭代器；流式失败抛出异常，需在调用方捕获。
+                 * @throws 连接关闭、取消超时、输出超限或原生请求失败。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * for await (const event of session.stream([{ type: 'text', text: '检查工程' }])) { const update = event.update }
+                 * ```
+                 */
+                stream(content: ContentBlock[], signal?: AbortSignal): AsyncGenerator<SessionNotification>;
+                /**
+                 * 请求取消正在执行的一轮；超时未停止时关闭所拥有的传输。
+                 * @returns 取消完成的 HaiResult；超时或清理失败返回错误。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.cancel()
+                 * ```
+                 */
+                cancel: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: void;
+                }>;
+                /**
+                 * 选择智能体公布的原生模式 ID；不兼容时返回协议失败。
+                 * @param mode - 握手或事件中公布的原生模式 ID。
+                 * @returns 原生模式设置结果的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.setMode('code')
+                 * ```
+                 */
+                setMode: (mode: string) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: _agentclientprotocol_sdk.SetSessionModeResponse;
+                }>;
+                /**
+                 * 设置智能体公布的原生配置选项；值必须符合该智能体的选项定义。
+                 * @param key - 原生配置选项 ID。
+                 * @param value - 该选项允许的值。
+                 * @returns 原生配置更新结果的 HaiResult。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.setConfigOption('model', 'coding')
+                 * ```
+                 */
+                setConfigOption: (key: string, value: string) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: _agentclientprotocol_sdk.SetSessionConfigOptionResponse;
+                }>;
+                /**
+                 * 先关闭会话执行环境，再 fetch 并仅快进各工程明确配置的主分支；不修改会话分支。
+                 * @returns 各仓更新报告；部分失败时报告位于 error.cause.reports。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.updateMain()
+                 * ```
+                 */
+                updateMain: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPGitReport[];
+                }>;
+                /**
+                 * 关闭执行环境后逐仓提交并推送；仅支持受管理的独立会话，部分失败保留各仓报告，禁止强推。
+                 * @param request - 发布模式、提交说明和作者；仅支持受管理的独立会话。
+                 * @returns 各仓提交/推送报告；部分失败时报告位于 error.cause.reports。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.publish({ mode: 'merge-main', message: '完成任务', author: { name: 'Developer', email: 'dev@example.com' } })
+                 * ```
+                 */
+                publish: (request: z.input<typeof ACPPublishSchema>) => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: ACPGitReport[];
+                }>;
+                /**
+                 * 停止拥有的进程或容器，释放占用；保留工作目录和原生状态，供后续显式恢复。
+                 * @returns 关闭完成的 HaiResult；清理失败时不释放仍在占用的资源。
+                 * @example
+                 * ```ts
+                 * // session 为 sessions.create/get/resume 成功返回的 data。
+                 * // 普通 API 先检查 result.success，再读取 data 或 error。
+                 * const result = await session.close()
+                 * ```
+                 */
+                close: () => Promise<{
+                    success: false;
+                    error: _h_ai_core.HaiError;
+                } | {
+                    success: true;
+                    data: void;
+                }>;
+            };
+        }>;
+        /**
+         * 关闭本进程拥有的会话并释放锁，不删除历史和工程内容。
+         * @param id - 框架会话 ID。
+         * @returns 关闭完成的 HaiResult；不允许关闭其他进程拥有的执行环境。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.sessions.close('task-1')
+         * ```
+         */
+        close: (id: string) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: void;
+        }>;
+        /**
+         * 仅删除已关闭或失败的会话记录；不删除工作树及原生文件，不替代 Git worktree 清理。
+         * @param id - 框架会话 ID。
+         * @returns 删除完成的 HaiResult；活动会话返回忙碌错误。
+         * @example
+         * ```ts
+         * import { ai } from '@h-ai/ai'
+         * // 前提：ai 已成功初始化。
+         * // 普通 API 先检查 result.success，再读取 data 或 error。
+         * const result = await ai.acp.sessions.remove('task-1')
+         * ```
+         */
+        remove: (id: string) => Promise<{
+            success: false;
+            error: _h_ai_core.HaiError;
+        } | {
+            success: true;
+            data: void;
+        }>;
+    };
+    /**
+     * 连接原生 stdio/HTTP/WS 服务；不创建工作区或提供传输兼容桥。
+     * @param transport - 智能体实际支持的原生传输与命令或地址。
+     * @param options - 可信回调、声明能力和初始化取消信号。
+     * @returns 低层连接句柄的 HaiResult；连接失败不自动转换传输。
+     * @example
+     * ```ts
+     * import { ai } from '@h-ai/ai'
+     * // 前提：ai 已成功初始化。
+     * // 普通 API 先检查 result.success，再读取 data 或 error。
+     * const result = await ai.acp.connect({ type: 'http', url: 'https://agent.example.com/acp' })
+     * ```
+     */
+    connect: (transport: ACPTransport, options?: ACPClientOptions) => Promise<{
+        success: false;
+        error: _h_ai_core.HaiError;
+    } | {
+        success: true;
+        data: {
+            info: _agentclientprotocol_sdk.InitializeResponse;
+            /**
+             * 选择对端握手公布的认证方法，返回 HaiResult。
+             * @param method - initialize 返回的认证方法 ID。
+             * @returns 认证响应的 HaiResult。
+             * @example
+             * ```ts
+             * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+             * const result = await connection.authenticate('api-key')
+             * ```
+             */
+            authenticate: (method: string) => Promise<{
+                success: false;
+                error: _h_ai_core.HaiError;
+            } | {
+                success: true;
+                data: _agentclientprotocol_sdk.AuthenticateResponse;
+            }>;
+            /**
+             * 在对端可见的绝对 cwd 创建原生会话，返回 prompt/cancel 句柄。
+             * @param cwd - 对端文件系统可见的绝对工作目录。
+             * @param mcpServers - 可选原生 MCP 定义；调用方负责凭据与授权。
+             * @returns 原生会话句柄；不创建框架持久会话记录。
+             * @example
+             * ```ts
+             * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+             * const result = await connection.createSession('/srv/project', [])
+             * ```
+             */
+            createSession: (cwd: string, mcpServers?: McpServer[]) => Promise<{
+                success: false;
+                error: _h_ai_core.HaiError;
+            } | {
+                success: true;
+                data: {
+                    id: string;
+                    /**
+                     * 发送一轮原生内容，返回最终文本、停止原因和事件。
+                     * @param content - 原生 ACP 内容块。
+                     * @param signal - 可选本轮取消信号。
+                     * @returns 最终文本、停止原因和事件的 HaiResult。
+                     * @example
+                     * ```ts
+                     * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+                     * const result = await session.prompt([{ type: 'text', text: '检查工程' }])
+                     * ```
+                     */
+                    prompt: (content: ContentBlock[], signal?: AbortSignal) => Promise<{
+                        success: false;
+                        error: _h_ai_core.HaiError;
+                    } | {
+                        success: true;
+                        data: {
+                            text: string;
+                            events: SessionNotification[];
+                            stopReason: _agentclientprotocol_sdk.StopReason;
+                            _meta?: {
+                                [key: string]: unknown;
+                            } | null;
+                        };
+                    }>;
+                    /**
+                     * 取消当前轮次，超时则关闭连接。
+                     * @returns 取消完成的 HaiResult。
+                     * @example
+                     * ```ts
+                     * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+                     * const result = await session.cancel()
+                     * ```
+                     */
+                    cancel: () => Promise<{
+                        success: false;
+                        error: _h_ai_core.HaiError;
+                    } | {
+                        success: true;
+                        data: void;
+                    }>;
+                };
+            }>;
+            /**
+             * 读取对端原生会话列表；未声明相应能力时返回错误。
+             * @param cursor - 上一次原生列表响应中的分页游标。
+             * @returns 原生分页响应的 HaiResult。
+             * @example
+             * ```ts
+             * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+             * const result = await connection.listSessions()
+             * ```
+             */
+            listSessions: (cursor?: string) => Promise<{
+                success: false;
+                error: _h_ai_core.HaiError;
+            } | {
+                success: true;
+                data: _agentclientprotocol_sdk.ListSessionsResponse;
+            }>;
+            /**
+             * 按原生 ID 删除远端会话；不会删除框架数据库会话记录。
+             * @param id - 对端返回的原生会话 ID。
+             * @returns 原生删除响应的 HaiResult；不支持时返回协议错误。
+             * @example
+             * ```ts
+             * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+             * const result = await connection.deleteSession('native-id')
+             * ```
+             */
+            deleteSession: (id: string) => Promise<{
+                success: false;
+                error: _h_ai_core.HaiError;
+            } | {
+                success: true;
+                data: _agentclientprotocol_sdk.DeleteSessionResponse;
+            }>;
+            /**
+             * 关闭连接和拥有的子进程；不删除远端文件或持久状态。
+             * @returns 关闭完成的 HaiResult；可重复关闭。
+             * @example
+             * ```ts
+             * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+             * const result = await connection.close()
+             * ```
+             */
+            close: () => Promise<{
+                success: false;
+                error: _h_ai_core.HaiError;
+            } | {
+                success: true;
+                data: void;
+            }>;
+        };
+    }>;
+    /**
+     * 关闭子系统及拥有的资源；由 ai.close 生命周期调用。
+     * @returns 所有已接受操作结束和拥有资源完成清理后的 Promise。
+     * @throws 清理进程或容器失败时抛出 ACPFailure，由 ai.close 统一处理。
+     * @example
+     * ```ts
+     * import { ai } from '@h-ai/ai'
+     * // 前提：ai 已成功初始化。
+     * // 普通 API 先检查 result.success，再读取 data 或 error。
+     * await ai.close()
+     * ```
+     */
+    close(): Promise<void>;
+};
+
+/**
+ * 原生传输参数；HTTP/WS 使用锁定版本的官方实验传输，不进行隐式转换。
+ * @example
+ * ```ts
+ * import type { ACPTransport } from '@h-ai/ai'
+ * const transport: ACPTransport = { type: 'stdio', command: 'codex-acp' }
+ * ```
+ */
+type ACPTransport = {
+    /** 通过独占子进程 stdin/stdout 传输 ACP。 */
+    type: 'stdio';
+    /** 直接执行的程序路径，不通过 shell。 */
+    command: string;
+    /** 原生参数数组。 */
+    args?: string[];
+    /** 子进程工作目录。 */
+    cwd?: string;
+    /** 传给子进程的环境变量，与最小宿主环境合并。 */
+    env?: Record<string, string>;
+} | {
+    /** 原生远程传输；对端必须支持相同 SDK 协议版本。 */
+    type: 'http' | 'ws';
+    /** ACP 服务地址，协议应与 type 一致。 */
+    url: string;
+    /** 当前连接的认证请求头，仅保存在内存。 */
+    headers?: Record<string, string>;
+};
+/**
+ * 可信宿主回调。声明能力必须提供对应实现；默认拒绝权限请求。
+ * @example
+ * ```ts
+ * import type { ACPClientOptions } from '@h-ai/ai'
+ * const options: ACPClientOptions = { handlers: { 'session/request_permission': () => ({ outcome: { outcome: 'cancelled' } }) } }
+ * ```
+ */
+interface ACPClientOptions {
+    /** 接收原生会话事件，包括 session/new 完成前的事件；抛错将关闭连接。 */
+    onEvent?: (event: SessionNotification) => void;
+    /** 可信客户端回调实现；未提供权限回调时默认拒绝。 */
+    handlers?: Partial<ClientRequestHandlersByMethod>;
+    /** 向智能体声明的能力；声明的文件、终端和 elicitation 能力必须配齐回调。 */
+    capabilities?: ClientCapabilities;
+    /** 初始化连接的取消信号；每轮 prompt 的取消信号独立传入。 */
+    signal?: AbortSignal;
+}
+/**
+ * 可信原生配置扩展；返回值只传给进程，不写入 Agent 定义存储。
+ * @example
+ * ```ts
+ * import type { ACPAgentAdapter } from '@h-ai/ai'
+ * const adapter: ACPAgentAdapter = { configure: () => ({ command: 'my-agent', args: ['--acp'], env: {} }) }
+ * ```
+ */
+interface ACPAgentAdapter {
+    /**
+     * 生成当前会话的原生启动参数；实现可以异步，不应在此启动进程或持久保存密钥。
+     * @param input - 智能体、已解析模型与独立状态目录。
+     * @returns 原生可执行文件、参数、临时环境和可选配置文件。
+     * @example
+     * ```ts
+     * const adapter: ACPAgentAdapter = { configure: ({ statePath }) => ({ command: 'my-agent', args: ['--acp'], env: { AGENT_HOME: statePath } }) }
+     * ```
+     */
+    configure: (input: ACPAgentAdapterInput) => ACPAgentLaunch | Promise<ACPAgentLaunch>;
+}
+/**
+ * 原生适配器输入；模型来源由框架统一解析，适配器不维护独立模型清单。
+ * @example
+ * ```ts
+ * import type { ACPAgentAdapterInput } from '@h-ai/ai'
+ * function selected(input: ACPAgentAdapterInput) { return input.models.find(model => model.id === input.modelId) }
+ * ```
+ */
+interface ACPAgentAdapterInput {
+    /** 合并清单中的智能体定义。 */
+    agent: z.infer<typeof ACPAgentSchema>;
+    /** 智能体绑定的全部模型及已解析协议、凭据、容量和模态信息。 */
+    models: Array<{
+        id: string;
+        config: ResolvedModelConfig;
+    }>;
+    /** 本次会话选择的模型 ID。 */
+    modelId?: string;
+    /** 已创建的专属状态目录；托管容器内使用 /state/<会话 ID>。 */
+    statePath: string;
+}
+/**
+ * 单次启动的原生配置；env 可能含凭据，不可向浏览器或日志直接公开。
+ * @example
+ * ```ts
+ * import type { ACPAgentLaunch } from '@h-ai/ai'
+ * const launch: ACPAgentLaunch = { command: 'my-agent', args: ['--acp'], env: {} }
+ * ```
+ */
+interface ACPAgentLaunch {
+    /** 直接执行的程序，禁止拼接 shell 命令。 */
+    command: string;
+    /** 原生参数数组。 */
+    args: string[];
+    /** 仅向当前执行环境注入的变量。 */
+    env: Record<string, string>;
+    /** 状态目录下的普通配置文件，文件名不允许路径分隔符。 */
+    files?: Record<string, string>;
+}
+/**
+ * 持久会话绑定；原生 ID 不等于框架 ID，工作目录只能由登记信息生成。
+ * @example
+ * ```ts
+ * import type { ACPSessionInfo } from '@h-ai/ai'
+ * function sessionStatus(session: ACPSessionInfo) { return session.status }
+ * ```
+ */
+interface ACPSessionInfo {
+    /** 框架会话 ID，与智能体返回的 nativeId 分开维护。 */
+    id: string;
+    /** 合并清单中的智能体 ID。 */
+    agentId: string;
+    /** 受管理工作区 ID；远程自定义服务可省略。 */
+    workspaceId?: string;
+    /** 智能体实际可见的绝对工作目录。 */
+    cwd: string;
+    /** 是否使用独立检出目录；false 表示共享工作区主目录。 */
+    newWorktree: boolean;
+    /** 独立会话中所有工程共用的分支名。 */
+    branch?: string;
+    /** 启动时选定的 Hai 模型 ID。 */
+    modelId?: string;
+    /** 模型非密钥配置的摘要；用于阻止不兼容的会话恢复。 */
+    modelSignature?: string;
+    /** 智能体原生会话 ID，恢复时原样传回。 */
+    nativeId?: string;
+    /** 打开中、运行中、已关闭或打开失败。 */
+    status: 'opening' | 'active' | 'closed' | 'failed';
+    /** 创建会话时的智能体定义快照。 */
+    agent: z.infer<typeof ACPAgentSchema>;
+    /** 直接绑定的原生 MCP 参数；可能含凭据，仅供可信服务端管理。 */
+    mcpServers: McpServer[];
+    /** 从 MCP 合并清单选择的服务 ID；凭据在启动时解析。 */
+    mcpServerIds?: string[];
+    /** 当前拥有的容器；关闭后清空，volume 内容仍保留。 */
+    resource?: {
+        engine?: 'podman' | 'docker';
+        container: string;
+    };
+}
+/**
+ * 创建会话参数；远程服务使用它自身可见的绝对路径。
+ * @example
+ * ```ts
+ * import type { ACPCreateSessionOptions } from '@h-ai/ai'
+ * const options: ACPCreateSessionOptions = { agentId: 'coder', workspaceId: 'project', newWorktree: true }
+ * ```
+ */
+interface ACPCreateSessionOptions extends ACPClientOptions {
+    /** 可选业务会话 ID；省略时生成 UUID。 */
+    id?: string;
+    /** 合并清单中的智能体 ID。 */
+    agentId: string;
+    /** 托管模式必填的工作区 ID。 */
+    workspaceId?: string;
+    /** 自定义远程服务可见的绝对路径；托管模式由工作区计算。 */
+    cwd?: string;
+    /** 默认 false；true 时从每个工程当前本地主分支创建 worktree。 */
+    newWorktree?: boolean;
+    /** 独立会话分支名；默认 acp/<会话 ID>。 */
+    branch?: string;
+    /** 本次会话的模型 ID，必须在智能体 modelIds 内。 */
+    modelId?: string;
+    /** 直接传给智能体的 MCP 定义；与 mcpServerIds 合并。 */
+    mcpServers?: McpServer[];
+    /** 从 ai.mcp.servers 选择的登记服务。 */
+    mcpServerIds?: string[];
+}
+/**
+ * 每个工程分别报告，保留失败前已发生的提交和推送结果。
+ * @example
+ * ```ts
+ * import type { ACPGitReport } from '@h-ai/ai'
+ * function failedRepositories(reports: ACPGitReport[]) { return reports.filter(report => !report.success).map(report => report.repositoryId) }
+ * ```
+ */
+interface ACPGitReport {
+    /** 工作区中声明的工程 ID。 */
+    repositoryId: string;
+    /** 该工程是否完成全部请求操作。 */
+    success: boolean;
+    /** 成功时为 done；失败时标明停止阶段。 */
+    phase: 'check' | 'commit' | 'fetch' | 'merge' | 'push' | 'done';
+    /** 已创建或发布的提交 SHA；失败前可能已经产生提交。 */
+    commit?: string;
+    /** 脱敏的失败原因，不包含 Git stderr 或认证资料。 */
+    error?: string;
+}
+/**
+ * ACP 操作入口。
+ * @example
+ * ```ts
+ * import { ai } from '@h-ai/ai'
+ * async function listAgents() { const result = await ai.acp.agents.list(); if (!result.success) return result; return result.data }
+ * ```
+ */
+type ACPOperations = ReturnType<typeof createACPOperations>;
+
+export { type AudioModelEntry as $, type A2AAgentCardConfig as A, ACPRepositorySchema as B, type ACPSessionInfo as C, type ACPTransport as D, ACPWorkspaceSchema as E, type AIConfig as F, type AIConfigInput as G, AIConfigSchema as H, type AIFunctions as I, type AIInitOptions as J, type AIRelStore as K, type AIRelStoreCompareAndSwap as L, type AIRelStoreOptions as M, type AIResourceEntry as N, type AIResourceRegistry as O, type AIStoreProvider as P, type AIVectorBackend as Q, type AIVectorStore as R, type AIVersionedRecord as S, AUDIO_WS_PATH as T, type ApiType as U, ApiTypeSchema as V, type AskOptions as W, type AssistantMessage as X, type AudioConfig as Y, AudioConfigSchema as Z, AudioFormatSchema as _, type A2AApiKeySecurity as a, type FileConfig as a$, AudioModelEntrySchema as a0, type AudioOperation as a1, AudioOperationSchema as a2, AudioOperationsSchema as a3, type AudioProviderName as a4, AudioProviderSchema as a5, type AudioWsClientMessage as a6, AudioWsClientMessageSchema as a7, type AudioWsDoneMessage as a8, AudioWsDoneMessageSchema as a9, type CompressionStrategy as aA, CompressionStrategySchema as aB, type ConsolidateOptions as aC, type ConsolidateResult as aD, type ContextChatOptions as aE, type ContextChatResult as aF, type ContextManager as aG, type ContextManagerOptions as aH, type ContextOperations as aI, type ContextResetOptions as aJ, type ContextStreamEvent as aK, type ConversationTurn as aL, type ConversationTurnStatus as aM, type DefineToolOptions as aN, type DeveloperMessage as aO, type EmbeddingConfig as aP, EmbeddingConfigSchema as aQ, type EmbeddingItem as aR, type EmbeddingOperations as aS, type EmbeddingRequest as aT, type EmbeddingResponse as aU, type EntityDocumentRelation as aV, type EntityDocumentResult as aW, type EntityListOptions as aX, type EntityQueryOptions as aY, type EntityType as aZ, EntityTypeSchema as a_, type AudioWsEndMessage as aa, type AudioWsErrorMessage as ab, type AudioWsSegmentDoneMessage as ac, type AudioWsSegmentStartedMessage as ad, type AudioWsServerMessage as ae, type AudioWsSpeechMessage as af, type AudioWsStartMessage as ag, AudioWsStartMessageSchema as ah, type AudioWsTextMessage as ai, AudioWsTextMessageSchema as aj, type AudioWsTranscriptMessage as ak, type ChatCompletionChoice as al, type ChatCompletionChunk as am, type ChatCompletionDelta as an, type ChatCompletionRequest as ao, type ChatCompletionResponse as ap, type ChatHistoryOptions as aq, type ChatMessage as ar, type ChatRecord as as, type Citation as at, type CommitTurnInput as au, type CompressConfig as av, CompressConfigSchema as aw, type CompressOperations as ax, type CompressOptions as ay, type CompressResult as az, type A2AAuthenticator as b, MCPServerConfigSchema as b$, FileConfigSchema as b0, type FileOperations as b1, type FileParseMethod as b2, type FileParseOptions as b3, type FileParseRequest as b4, type FileParseResult as b5, type GenerateImageRequest as b6, type GenerateImageResult as b7, type GenerateObjectRequest as b8, type GeneratedImage as b9, type KnowledgeOperations as bA, type KnowledgeRepairOptions as bB, type KnowledgeRepairProgress as bC, type KnowledgeRepairResult as bD, type KnowledgeRetrieveItem as bE, type KnowledgeRetrieveOptions as bF, type KnowledgeRetrieveResult as bG, type KnowledgeSetupOptions as bH, type KnowledgeStore as bI, type LLMConfig as bJ, LLMConfigSchema as bK, type LLMOperations as bL, type MCPConfig as bM, MCPConfigSchema as bN, type MCPContext as bO, type MCPExternalServer as bP, MCPExternalServerSchema as bQ, type MCPOperations as bR, type MCPPrompt as bS, type MCPPromptArgument as bT, type MCPPromptContent as bU, type MCPPromptMessage as bV, type MCPResource as bW, type MCPResourceContent as bX, type MCPServerCapabilities as bY, MCPServerCapabilitiesSchema as bZ, type MCPServerConfig as b_, HaiAIError as ba, type ImageConfig as bb, ImageConfigSchema as bc, type ImageContent as bd, type ImageModelEntry as be, ImageModelEntrySchema as bf, type ImageOperations as bg, type ImageProviderName as bh, ImageProviderSchema as bi, type ImageSize as bj, type InteractionScope as bk, type KnowledgeAskOptions as bl, type KnowledgeAskResult as bm, type KnowledgeConfig as bn, KnowledgeConfigSchema as bo, type KnowledgeDocumentInfo as bp, type KnowledgeDocumentListOptions as bq, type KnowledgeDocumentMetadata as br, type KnowledgeDocumentRemoveOptions as bs, type KnowledgeDocumentRevision as bt, type KnowledgeEntity as bu, type KnowledgeIngestBatchProgress as bv, type KnowledgeIngestBatchResult as bw, type KnowledgeIngestFileInput as bx, type KnowledgeIngestInput as by, type KnowledgeIngestResult as bz, type A2ACallOptions as c, type RetrievalConfig as c$, type MCPToolDefinition as c0, type MCPToolHandler as c1, type ManagedAudioOperations as c2, type ManagedImageOperations as c3, type ManagedLLMOperations as c4, type ManagedMCPOperations as c5, type ManagedRetrievalOperations as c6, type McpServerOptions as c7, type MemoryAccessScope as c8, type MemoryAdminOperations as c9, type PersonaOperations as cA, type PersonaProfile as cB, type PersonaProfileInput as cC, type PersonaProfileUpdate as cD, type PersonaScopeOptions as cE, type RagContextItem as cF, type RagOperations as cG, type RagOptions as cH, type RagResult as cI, type RagStreamEvent as cJ, type ReasoningOperations as cK, type ReasoningOptions as cL, type ReasoningResult as cM, type ReasoningStep as cN, type ReasoningStepType as cO, type ReasoningStrategy as cP, type ReasoningStreamEvent as cQ, type ReferenceImage as cR, type RerankDocument as cS, type RerankItem as cT, type RerankOperations as cU, type RerankRequest as cV, type RerankResponse as cW, type ResolveRequiredModelEntryOptions as cX, type ResolvedAudioModel as cY, type ResolvedImageModel as cZ, type ResolvedModelConfig as c_, type MemoryClearAllOptions as ca, type MemoryClearOptions as cb, type MemoryConfig as cc, MemoryConfigSchema as cd, type MemoryCoreOperations as ce, type MemoryEntry as cf, type MemoryEntryInput as cg, type MemoryExtractOptions as ch, type MemoryInjectionOptions as ci, type MemoryListOptions as cj, type MemoryListPageOptions as ck, type MemoryOperations as cl, type MemoryRecallOptions as cm, type MemoryType as cn, MemoryTypeSchema as co, type MemoryUpdateInput as cp, type MessageContent as cq, type MessageRole as cr, ModelCapabilitiesSchema as cs, type ModelEntry as ct, ModelEntrySchema as cu, type ModelScenario as cv, ModelScenarioSchema as cw, type ObjectRef as cx, OptionalSecretSchema as cy, type OutputFormat as cz, type A2ACallResult as d, RetrievalConfigSchema as d0, type RetrievalOperations as d1, type RetrievalRequest as d2, type RetrievalResult as d3, type RetrievalResultItem as d4, type RetrievalSource as d5, type RetrievalSourceConfig as d6, RetrievalSourceSchema as d7, type SSEDecoder as d8, type SSEEvent as d9, type ToolDefinition as dA, type ToolErrorType as dB, type ToolExecutionContext as dC, type ToolExecutionOptions as dD, type ToolMessage as dE, type ToolRegistryOperations as dF, type ToolRegistryOptions as dG, type ToolsOperations as dH, type UserMessage as dI, type WhereClause as dJ, type WhereOperator as dK, type WhereValue as dL, ensureAudioCredential as dM, resolveAudioModel as dN, resolveImageModel as dO, resolveModelApi as dP, resolveModelEntry as dQ, serializePlayableAudio as dR, type ScopedMemoryBinding as da, type ScopedMemoryOperations as db, type SessionInfo as dc, type StoreFilter as dd, type StorePage as de, type StoreScope as df, type StreamOperations as dg, type StreamProcessor as dh, type StreamResult as di, type SummaryConfig as dj, SummaryConfigSchema as dk, type SummaryOperations as dl, type SummaryOptions as dm, type SummaryResult as dn, type SystemMessage as dp, type TempModelConfig as dq, type TextContent as dr, type TokenConfig as ds, TokenConfigSchema as dt, type TokenOperations as du, type TokenUsage as dv, type Tool as dw, type ToolAuthorizationRequest as dx, type ToolAuthorizer as dy, type ToolCall as dz, type A2ACallerIdentity as e, type A2AConfig as f, A2AConfigSchema as g, type A2AContextInfo as h, type A2AHandleResult as i, type A2AMessageRecord as j, type A2AOperations as k, type A2ASecurityConfig as l, A2ASkillConfigSchema as m, type A2ATaskFilter as n, type ACPAgentAdapter as o, type ACPAgentAdapterInput as p, type ACPAgentLaunch as q, ACPAgentSchema as r, type ACPClientOptions as s, type ACPConfig as t, type ACPConfigInput as u, ACPConfigSchema as v, type ACPCreateSessionOptions as w, type ACPGitReport as x, type ACPOperations as y, ACPPublishSchema as z };