@h-ai/ai 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/index.js

@@ -1,8 +1,8 @@
-import { aiM, AIConfigSchema, MemoryConfigSchema, RetrievalConfigSchema, KnowledgeConfigSchema, TokenConfigSchema, SummaryConfigSchema, CompressConfigSchema, AudioConfigSchema, ImageConfigSchema, resolveImageModel, resolveModelEntry, resolveAudioModel, ensureAudioCredential, resolveModelApi } from './chunk-GAC5RLAG.js';
-export { A2AConfigSchema, A2ASkillConfigSchema, AIConfigSchema, AUDIO_WS_PATH, ApiTypeSchema, AudioConfigSchema, AudioFormatSchema, AudioModelEntrySchema, AudioOperationSchema, AudioOperationsSchema, AudioProviderSchema, AudioWsClientMessageSchema, AudioWsDoneMessageSchema, AudioWsStartMessageSchema, AudioWsTextMessageSchema, CompressConfigSchema, CompressionStrategySchema, EmbeddingConfigSchema, EntityTypeSchema, FileConfigSchema, ImageConfigSchema, ImageModelEntrySchema, ImageProviderSchema, KnowledgeConfigSchema, LLMConfigSchema, MCPConfigSchema, MCPServerCapabilitiesSchema, MCPServerConfigSchema, MemoryConfigSchema, MemoryTypeSchema, ModelEntrySchema, ModelScenarioSchema, OptionalSecretSchema, RetrievalConfigSchema, RetrievalSourceSchema, SummaryConfigSchema, TokenConfigSchema, ensureAudioCredential, resolveAudioModel, resolveImageModel, resolveModelApi, resolveModelEntry, serializePlayableAudio } from './chunk-GAC5RLAG.js';
-import { HaiAIError } from './chunk-HYMP57AC.js';
-export { HaiAIError } from './chunk-HYMP57AC.js';
-import process from 'process';
+import { aiM, AIConfigSchema, MemoryConfigSchema, ModelEntrySchema, AudioModelEntrySchema, ImageModelEntrySchema, MCPExternalServerSchema, RetrievalSourceSchema, KnowledgeConfigSchema, TokenConfigSchema, SummaryConfigSchema, CompressConfigSchema, ACPConfigSchema, ACPAgentSchema, ACPWorkspaceSchema, AudioConfigSchema, resolveModelEntry, resolveAudioModel, ensureAudioCredential, resolveModelApi, sessionIdentitySchema, ImageConfigSchema, resolveImageModel, ACPPublishSchema, branchNameSchema } from './chunk-HEYVFQC6.js';
+export { A2AConfigSchema, A2ASkillConfigSchema, ACPAgentSchema, ACPConfigSchema, ACPPublishSchema, ACPRepositorySchema, ACPWorkspaceSchema, AIConfigSchema, AUDIO_WS_PATH, ApiTypeSchema, AudioConfigSchema, AudioFormatSchema, AudioModelEntrySchema, AudioOperationSchema, AudioOperationsSchema, AudioProviderSchema, AudioWsClientMessageSchema, AudioWsDoneMessageSchema, AudioWsStartMessageSchema, AudioWsTextMessageSchema, CompressConfigSchema, CompressionStrategySchema, EmbeddingConfigSchema, EntityTypeSchema, FileConfigSchema, ImageConfigSchema, ImageModelEntrySchema, ImageProviderSchema, KnowledgeConfigSchema, LLMConfigSchema, MCPConfigSchema, MCPExternalServerSchema, MCPServerCapabilitiesSchema, MCPServerConfigSchema, MemoryConfigSchema, MemoryTypeSchema, ModelCapabilitiesSchema, ModelEntrySchema, ModelScenarioSchema, OptionalSecretSchema, RetrievalConfigSchema, RetrievalSourceSchema, SummaryConfigSchema, TokenConfigSchema, ensureAudioCredential, resolveAudioModel, resolveImageModel, resolveModelApi, resolveModelEntry, serializePlayableAudio } from './chunk-HEYVFQC6.js';
+import { HaiAIError } from './chunk-M77C3VAP.js';
+export { HaiAIError } from './chunk-M77C3VAP.js';
+import process2 from 'process';
 import { core, err, ok } from '@h-ai/core';
 import { datapipe } from '@h-ai/datapipe';
 import { A2AClient } from '@a2a-js/sdk/client';
@@ -10,14 +10,21 @@ import { JsonRpcTransportHandler, ServerCallContext, A2AError, RequestContext, R
 import { Buffer } from 'buffer';
 import { createHash, randomUUID } from 'crypto';
 import { setTimeout as setTimeout$1 } from 'timers/promises';
+import { z, ZodError } from 'zod';
+import { mkdir, realpath } from 'fs/promises';
+import { isAbsolute, resolve, relative, dirname, basename } from 'path';
+import { spawn } from 'child_process';
+import { Writable, Readable } from 'stream';
+import { methods, ndJsonStream, client, PROTOCOL_VERSION } from '@agentclientprotocol/sdk';
+import { createHttpStream } from '@agentclientprotocol/sdk/experimental/http-client';
+import { createWebSocketStream } from '@agentclientprotocol/sdk/experimental/ws-client';
+import WebSocket2, { WebSocket } from 'ws';
 import { gunzipSync } from 'zlib';
-import WebSocket from 'ws';
 import { FormData as FormData$1, Agent, fetch as fetch$1 } from 'undici';
 import OpenAI3, { toFile } from 'openai';
 import { nanoid } from 'nanoid';
 import dns from 'dns';
 import { BlockList, isIP } from 'net';
-import { z } from 'zod';
 import { PromptMessageSchema, TextResourceContentsSchema, BlobResourceContentsSchema } from '@modelcontextprotocol/sdk/types.js';
 import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
 import { reldb } from '@h-ai/reldb';
@@ -520,7 +527,7 @@ async function executeRemoteAgentCall(remoteUrl, message, options) {
     safeLabel = validatedUrl.safeLabel;
     const customHeaders = options?.headers;
     const timeoutMs = Math.max(1, options?.timeout ?? DEFAULT_A2A_CALL_TIMEOUT_MS);
-    const client = new A2AClient(requestUrl, {
+    const client2 = new A2AClient(requestUrl, {
       fetchImpl: ((input, init) => {
         const existingHeaders = init?.headers ? Object.fromEntries(new Headers(init.headers).entries()) : {};
         const signals = [init?.signal, AbortSignal.timeout(timeoutMs)].filter((signal) => Boolean(signal));
@@ -540,7 +547,7 @@ async function executeRemoteAgentCall(remoteUrl, message, options) {
         parts: [{ kind: "text", text: message }]
       }
     };
-    const response = await client.sendMessage(params);
+    const response = await client2.sendMessage(params);
     if ("error" in response) {
       return err(HaiAIError.A2A_REMOTE_CALL_FAILED, aiM("ai_a2aRemoteCallFailed", { params: { url: safeLabel, error: "Remote agent returned an error" } }));
     }
@@ -702,6 +709,2762 @@ function createA2ALazyProxy(deps) {
     }
   };
 }
+var ACPFailure = class extends Error {
+  /**
+   * 创建只携带允许公开诊断信息的内部异常。
+   * @param kind - 固定错误类别。
+   * @param details - 脱敏数据，不得包含凭据或原始 stderr。
+   * @returns 内部异常实例。
+   * @example
+   * ```ts
+   * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+   * const failure = new ACPFailure('busy')
+   * ```
+   */
+  constructor(kind, details) {
+    super(kind);
+    this.kind = kind;
+    this.details = details;
+  }
+  kind;
+  details;
+};
+var mappings = {
+  invalid: ["ACP_INVALID_REQUEST", "ai_acpInvalid"],
+  missing: ["ACP_NOT_FOUND", "ai_acpNotFound"],
+  busy: ["ACP_BUSY", "ai_acpBusy"],
+  unsupported: ["ACP_UNSUPPORTED", "ai_acpUnsupported"],
+  cancelled: ["ACP_CANCELLED", "ai_acpCancelled"],
+  timeout: ["ACP_TIMEOUT", "ai_acpTimeout"],
+  output: ["ACP_OUTPUT_INVALID", "ai_acpOutput"],
+  conflict: ["ACP_CONFLICT", "ai_acpConflict"],
+  partial: ["ACP_PARTIAL_FAILURE", "ai_acpPartial"],
+  closed: ["ACP_CLOSED", "ai_acpClosed"],
+  runtime: ["ACP_RUNTIME_UNAVAILABLE", "ai_acpRuntime"],
+  model: ["ACP_MODEL_INCOMPATIBLE", "ai_acpModel"],
+  cleanup: ["ACP_CLEANUP_FAILED", "ai_acpCleanup"],
+  gitMissing: ["ACP_GIT_NOT_FOUND", "ai_acpGitNotFound"],
+  failed: ["ACP_OPERATION_FAILED", "ai_acpOperationFailed"]
+};
+function acpError(error) {
+  const failure = error instanceof ACPFailure ? error : new ACPFailure(error instanceof ZodError ? "invalid" : "failed");
+  const [code, message] = mappings[failure.kind];
+  return err(HaiAIError[code], aiM(message), failure.details);
+}
+
+// src/acp/ai-acp-adapters.ts
+function resolveAgentModels(agent, config) {
+  return agent.modelIds.map((id) => {
+    if (!config.llm?.models?.some((entry2) => entry2.id === id))
+      throw new ACPFailure("model", { modelId: id });
+    const entry = config.llm.models.find((model) => model.id === id);
+    const protocol = entry.protocol ?? config.llm.protocol;
+    const llm = protocol === "anthropic" ? {
+      ...config.llm,
+      apiKey: entry.apiKey ?? config.llm.apiKey ?? (process2.env.HAI_AI_LLM_APIKEY?.trim() || process2.env.ANTHROPIC_API_KEY),
+      baseUrl: entry.baseUrl ?? (config.llm.protocol === "anthropic" ? config.llm.baseUrl ?? process2.env.HAI_AI_LLM_BASEURL : void 0) ?? process2.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com"
+    } : config.llm;
+    if (protocol === "anthropic" && !llm.apiKey)
+      throw new ACPFailure("model", { modelId: id });
+    const result = resolveModelEntry(llm, "default", id);
+    if (!result.success)
+      throw new ACPFailure("model", { modelId: id });
+    if (result.data.capabilities?.toolCalling === false)
+      throw new ACPFailure("model", { modelId: id });
+    return { id, config: result.data };
+  });
+}
+function resolveEnvironment(references) {
+  const env = {};
+  for (const [key, source] of Object.entries(references)) {
+    const value = process2.env[source];
+    if (!value)
+      throw new ACPFailure("invalid", { environment: source });
+    env[key] = value;
+  }
+  return env;
+}
+var nativeAdapters = {
+  "deepseek-harness": {
+    configure({ agent, models, modelId, statePath }) {
+      const selected = models.findIndex((item) => item.id === modelId);
+      if (selected < 0)
+        throw new ACPFailure("model", { modelId });
+      const env = { DSH_HOME: statePath };
+      const providers = {};
+      for (const [index, entry] of models.entries()) {
+        const model = entry.config;
+        const caps = model.capabilities;
+        if (!caps?.contextWindow || !caps.maxOutputTokens || !caps.inputModalities || caps.toolCalling !== true || !caps.reasoning || caps.reasoning.supported && !caps.reasoning.efforts?.length) {
+          throw new ACPFailure("model", { modelId: entry.id });
+        }
+        if (caps.inputModalities.some((item) => !["text", "image"].includes(item)))
+          throw new ACPFailure("model", { modelId: entry.id });
+        const key = `HAI_ACP_MODEL_${index}`;
+        env[key] = model.apiKey;
+        providers[`hai-${index}`] = {
+          apiKeyEnv: key,
+          baseURL: model.baseUrl,
+          api: model.protocol === "chat" ? "openai-completions" : model.protocol === "responses" ? "openai-responses" : "anthropic-messages",
+          // 输出容量是能力声明；单轮预算沿用 Hai 模型的 maxTokens。
+          defaultMaxTokens: Math.min(model.maxTokens, caps.maxOutputTokens),
+          defaultContextWindow: caps.contextWindow,
+          timeoutMs: model.timeout,
+          retryPolicy: { mode: "normal", maxRetries: 0 },
+          models: [
+            {
+              id: model.model,
+              contextWindow: caps.contextWindow,
+              input: caps.inputModalities,
+              reasoningEfforts: caps.reasoning.supported ? Object.fromEntries(
+                (caps.reasoning.efforts ?? []).map((effort) => [
+                  effort,
+                  effort
+                ])
+              ) : false
+            }
+          ]
+        };
+      }
+      const patch = [
+        { id: "llm-pi-ai", config: { providers } },
+        {
+          id: "acp",
+          config: {
+            provider: `hai-${selected}`,
+            model: models[selected].config.model
+          }
+        }
+      ];
+      return {
+        command: agent.mode === "custom-service" ? "dsh" : agent.command ?? "dsh",
+        args: [
+          // 自定义命令可能是 node + JS 入口，入口参数必须先于 dsh 的原生选项。
+          ...agent.mode === "custom-service" ? [] : agent.args ?? [],
+          "--profile",
+          "acp",
+          "--patch",
+          `${statePath}/hai-config.json`
+        ],
+        env,
+        files: { "hai-config.json": JSON.stringify(patch) }
+      };
+    }
+  },
+  "generic": {
+    configure({ agent, models }) {
+      if (agent.mode === "custom-service" || !agent.command || models.length)
+        throw new ACPFailure("model");
+      return { command: agent.command, args: agent.args ?? [], env: {} };
+    }
+  },
+  "codex": {
+    configure({ agent, models, modelId, statePath }) {
+      const selected = models.find((item) => item.id === modelId);
+      if (!selected || selected.config.protocol !== "responses")
+        throw new ACPFailure("model", { modelId });
+      const model = selected.config;
+      return {
+        command: agent.mode === "custom-service" ? "codex-acp" : agent.command ?? "codex-acp",
+        args: agent.mode === "custom-service" ? [] : agent.args ?? [],
+        env: {
+          CODEX_HOME: statePath,
+          CODEX_API_KEY: model.apiKey,
+          OPENAI_API_KEY: model.apiKey,
+          NO_BROWSER: "1",
+          DEFAULT_AUTH_REQUEST: JSON.stringify({ methodId: "api-key" }),
+          MODEL_PROVIDER: "hai",
+          CODEX_CONFIG: JSON.stringify({
+            model: model.model,
+            model_provider: "hai",
+            model_context_window: model.capabilities?.contextWindow,
+            model_providers: {
+              hai: {
+                name: "Hai",
+                base_url: model.baseUrl,
+                wire_api: "responses",
+                env_key: "CODEX_API_KEY"
+              }
+            }
+          })
+        }
+      };
+    }
+  }
+};
+function createResourceRegistry(store, schema, configured, isOpen) {
+  const config = new Map(
+    configured.map((item) => [item.id, structuredClone(item)])
+  );
+  if (config.size !== configured.length)
+    throw new Error("Duplicate configuration resource ID");
+  const copy = (record) => {
+    const { __deleted: _deleted, ...value } = record;
+    return structuredClone(value);
+  };
+  function ensure() {
+    if (!isOpen())
+      throw new Error("Resource registry closed");
+  }
+  async function read(id) {
+    ensure();
+    const fixed = config.get(id);
+    if (fixed)
+      return { value: structuredClone(fixed), source: "config" };
+    const saved = await store.readVersioned(id);
+    return saved && !saved.data.__deleted ? { value: copy(saved.data), source: "database", version: saved.version } : void 0;
+  }
+  async function entries() {
+    ensure();
+    const saved = await store.query({});
+    return [
+      ...[...config.values()].map((value) => ({
+        value: structuredClone(value),
+        source: "config"
+      })),
+      ...saved.filter((item) => !item.__deleted && !config.has(item.id)).map((item) => ({ value: copy(item), source: "database" }))
+    ];
+  }
+  async function protect(operation) {
+    if (!isOpen())
+      return err(HaiAIError.NOT_INITIALIZED, aiM("ai_notInitialized"));
+    try {
+      return ok(await operation());
+    } catch {
+      return err(
+        HaiAIError.RESOURCE_OPERATION_FAILED,
+        aiM("ai_resourceOperationFailed")
+      );
+    }
+  }
+  async function write(input, update, expectedVersion) {
+    if (!isOpen())
+      return err(HaiAIError.NOT_INITIALIZED, aiM("ai_notInitialized"));
+    const parsed = schema.safeParse(input);
+    if (!parsed.success || !parsed.data.id)
+      return err(HaiAIError.RESOURCE_INVALID, aiM("ai_resourceInvalid"));
+    const value = parsed.data;
+    if (config.has(value.id))
+      return err(HaiAIError.RESOURCE_READ_ONLY, aiM("ai_resourceReadOnly"));
+    try {
+      const previous = await store.readVersioned(value.id);
+      const exists = previous && !previous.data.__deleted;
+      if (update && !exists)
+        return err(HaiAIError.RESOURCE_NOT_FOUND, aiM("ai_resourceNotFound"));
+      if (!update && exists || expectedVersion !== void 0 && expectedVersion !== previous?.version) {
+        return err(HaiAIError.RESOURCE_CONFLICT, aiM("ai_resourceConflict"));
+      }
+      const version = await store.compareAndSwap(value.id, {
+        expectedVersion: previous?.version,
+        data: value
+      });
+      if (!version)
+        return err(HaiAIError.RESOURCE_CONFLICT, aiM("ai_resourceConflict"));
+      return ok({
+        value: structuredClone(value),
+        source: "database",
+        version
+      });
+    } catch {
+      return err(
+        HaiAIError.RESOURCE_OPERATION_FAILED,
+        aiM("ai_resourceOperationFailed")
+      );
+    }
+  }
+  const operations = {
+    list: () => protect(entries),
+    get: async (id) => {
+      const result = await protect(() => read(id));
+      if (!result.success)
+        return result;
+      return result.data ? ok(result.data) : err(HaiAIError.RESOURCE_NOT_FOUND, aiM("ai_resourceNotFound"));
+    },
+    register: (input) => write(input, false),
+    update: (input, version) => write(input, true, version),
+    remove: async (id, expectedVersion) => {
+      if (!isOpen())
+        return err(HaiAIError.NOT_INITIALIZED, aiM("ai_notInitialized"));
+      if (config.has(id))
+        return err(HaiAIError.RESOURCE_READ_ONLY, aiM("ai_resourceReadOnly"));
+      try {
+        const previous = await store.readVersioned(id);
+        if (!previous || previous.data.__deleted)
+          return err(HaiAIError.RESOURCE_NOT_FOUND, aiM("ai_resourceNotFound"));
+        if (expectedVersion !== void 0 && expectedVersion !== previous.version) {
+          return err(HaiAIError.RESOURCE_CONFLICT, aiM("ai_resourceConflict"));
+        }
+        if (!await store.compareAndSwap(id, {
+          expectedVersion: previous.version,
+          data: { ...previous.data, __deleted: true }
+        })) {
+          return err(HaiAIError.RESOURCE_CONFLICT, aiM("ai_resourceConflict"));
+        }
+        return ok(void 0);
+      } catch {
+        return err(
+          HaiAIError.RESOURCE_OPERATION_FAILED,
+          aiM("ai_resourceOperationFailed")
+        );
+      }
+    }
+  };
+  return {
+    operations,
+    read,
+    entries,
+    values: async () => (await entries()).map((entry) => entry.value)
+  };
+}
+var nativeJob = String.raw`
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+
+public static class HaiACPCommandJob {
+  [StructLayout(LayoutKind.Sequential)] struct BasicLimits {
+    public long ProcessTime, JobTime;
+    public uint Flags;
+    public UIntPtr MinimumWorkingSet, MaximumWorkingSet;
+    public uint ActiveProcessLimit;
+    public UIntPtr Affinity;
+    public uint PriorityClass, SchedulingClass;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct IoCounters {
+    public ulong ReadOperations, WriteOperations, OtherOperations, ReadBytes, WriteBytes, OtherBytes;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct ExtendedLimits {
+    public BasicLimits Basic;
+    public IoCounters Io;
+    public UIntPtr ProcessMemory, JobMemory, PeakProcessMemory, PeakJobMemory;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct Accounting {
+    public long UserTime, KernelTime, PeriodUserTime, PeriodKernelTime;
+    public uint Faults, Total, Active, Terminated;
+  }
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] struct Startup {
+    public uint Size;
+    public string Reserved, Desktop, Title;
+    public uint X, Y, Width, Height, XChars, YChars, Fill, Flags;
+    public ushort Show, ReservedSize;
+    public IntPtr ReservedData, Input, Output, Error;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct ProcessInfo {
+    public IntPtr Process, Thread;
+    public uint ProcessId, ThreadId;
+  }
+  [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)] static extern IntPtr CreateJobObject(IntPtr attributes, string name);
+  [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)] static extern IntPtr OpenJobObject(uint access, bool inherit, string name);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern bool SetInformationJobObject(IntPtr job, int kind, ref ExtendedLimits information, uint size);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern bool QueryInformationJobObject(IntPtr job, int kind, out Accounting information, uint size, IntPtr length);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern bool AssignProcessToJobObject(IntPtr job, IntPtr process);
+  [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)] static extern bool CreateProcess(string application, StringBuilder command, IntPtr processAttributes, IntPtr threadAttributes, bool inherit, uint flags, IntPtr environment, string directory, ref Startup startup, out ProcessInfo information);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern uint ResumeThread(IntPtr thread);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern bool TerminateProcess(IntPtr process, uint code);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern bool TerminateJobObject(IntPtr job, uint code);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern bool GetExitCodeProcess(IntPtr process, out uint code);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern bool CloseHandle(IntPtr handle);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern IntPtr GetStdHandle(int kind);
+  [DllImport("kernel32.dll", SetLastError = true)] static extern bool SetHandleInformation(IntPtr handle, uint mask, uint flags);
+
+  static void Check(bool success) { if (!success) throw new Win32Exception(Marshal.GetLastWin32Error()); }
+  static uint Active(IntPtr job) {
+    Accounting information;
+    Check(QueryInformationJobObject(job, 1, out information, (uint)Marshal.SizeOf(typeof(Accounting)), IntPtr.Zero));
+    return information.Active;
+  }
+  // Windows argv 编码：引号前与结尾的反斜杠加倍，其余字符原样传递，不经过命令 shell。
+  static string Quote(string value) {
+    StringBuilder result = new StringBuilder("\"");
+    int slashes = 0;
+    foreach (char current in value) {
+      if (current == '\\') { slashes++; continue; }
+      if (current == '"') result.Append('\\', slashes * 2 + 1);
+      else result.Append('\\', slashes);
+      result.Append(current);
+      slashes = 0;
+    }
+    result.Append('\\', slashes * 2).Append('"');
+    return result.ToString();
+  }
+  public static int Run(string name, string command, string[] arguments) {
+    IntPtr job = CreateJobObject(IntPtr.Zero, name);
+    if (job == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
+    ProcessInfo process = new ProcessInfo();
+    bool assigned = false;
+    try {
+      ExtendedLimits limits = new ExtendedLimits();
+      limits.Basic.Flags = 0x2000; // JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE；不允许 breakaway。
+      Check(SetInformationJobObject(job, 9, ref limits, (uint)Marshal.SizeOf(typeof(ExtendedLimits))));
+      StringBuilder line = new StringBuilder(Quote(command));
+      foreach (string argument in arguments) line.Append(' ').Append(Quote(argument));
+      Startup startup = new Startup();
+      startup.Size = (uint)Marshal.SizeOf(typeof(Startup));
+      startup.Flags = 0x100;
+      startup.Input = GetStdHandle(-10); startup.Output = GetStdHandle(-11); startup.Error = GetStdHandle(-12);
+      Check(SetHandleInformation(startup.Input, 1, 1));
+      Check(SetHandleInformation(startup.Output, 1, 1));
+      Check(SetHandleInformation(startup.Error, 1, 1));
+      Check(CreateProcess(null, line, IntPtr.Zero, IntPtr.Zero, true, 0x08000004, IntPtr.Zero, null, ref startup, out process));
+      Check(AssignProcessToJobObject(job, process.Process));
+      assigned = true;
+      if (ResumeThread(process.Thread) == 0xFFFFFFFF) throw new Win32Exception(Marshal.GetLastWin32Error());
+      if (WaitForSingleObject(process.Process, 0xFFFFFFFF) != 0) throw new Win32Exception(Marshal.GetLastWin32Error());
+      uint code;
+      Check(GetExitCodeProcess(process.Process, out code));
+      while (Active(job) != 0) Thread.Sleep(20);
+      return unchecked((int)code);
+    }
+    finally {
+      if (process.Process != IntPtr.Zero) {
+        // 分配失败时进程仍挂起，直接终止，不允许裸进程恢复；Job 在其他异常时同样清空。
+        if (!assigned) TerminateProcess(process.Process, 125);
+        else TerminateJobObject(job, 125);
+        WaitForSingleObject(process.Process, 5000);
+      }
+      if (process.Thread != IntPtr.Zero) CloseHandle(process.Thread);
+      if (process.Process != IntPtr.Zero) CloseHandle(process.Process);
+      CloseHandle(job);
+    }
+  }
+  public static bool Empty(string name) {
+    IntPtr job = OpenJobObject(4, false, name); // JOB_OBJECT_QUERY
+    if (job == IntPtr.Zero) {
+      if (Marshal.GetLastWin32Error() == 2) return true;
+      throw new Win32Exception(Marshal.GetLastWin32Error());
+    }
+    try { return Active(job) == 0; }
+    finally { CloseHandle(job); }
+  }
+}
+`;
+function powershell(script) {
+  return ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")];
+}
+function windowsACPCommand(command, args) {
+  const name = `Local\\hai-ai-acp-${randomUUID()}`;
+  const key = `__HAI_AI_ACP_JOB_${randomUUID().replaceAll("-", "")}`;
+  const script = `$ErrorActionPreference='Stop'; $ProgressPreference='SilentlyContinue'; $InformationPreference='SilentlyContinue'
+try {
+  Add-Type -TypeDefinition @'
+${nativeJob}
+'@
+  $inputConfig = [Environment]::GetEnvironmentVariable('${key}') | ConvertFrom-Json
+  [Environment]::SetEnvironmentVariable('${key}', $null)
+  exit ([HaiACPCommandJob]::Run([string]$inputConfig.name, [string]$inputConfig.command, [string[]]$inputConfig.args))
+} catch { [Console]::Error.WriteLine('Windows ACP job failed'); exit 125 }`;
+  return { name, args: powershell(script), env: { [key]: JSON.stringify({ name, command, args }) } };
+}
+function windowsACPJobProbe(name) {
+  return powershell(`$ErrorActionPreference='Stop'; $ProgressPreference='SilentlyContinue'; $InformationPreference='SilentlyContinue'
+try {
+  Add-Type -TypeDefinition @'
+${nativeJob}
+'@
+  if ([HaiACPCommandJob]::Empty('${name}')) { exit 0 } else { exit 1 }
+} catch { exit 2 }`);
+}
+async function jobProbe(name, timeout) {
+  return new Promise((resolve3) => {
+    const probe = spawn("powershell.exe", windowsACPJobProbe(name), { shell: false, windowsHide: true, stdio: "ignore", env: baseEnvironment() });
+    let settled = false;
+    let timer;
+    const finish = (code) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve3(code);
+    };
+    timer = setTimeout(() => {
+      void stopProcess(probe).catch(() => {
+      }).finally(() => finish(2));
+      probe.kill("SIGKILL");
+      finish(2);
+    }, Math.max(1, timeout));
+    probe.once("error", () => finish(2));
+    probe.once("close", (code) => finish(code ?? 2));
+  });
+}
+async function stopWindowsJob(child, name, closeObserved) {
+  const deadline = performance.now() + 15e3;
+  let timer;
+  try {
+    await Promise.race([
+      stopProcess(child, { closeObserved }),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          child.kill("SIGKILL");
+          reject(new ACPFailure("cleanup"));
+        }, Math.max(1, deadline - performance.now()));
+      })
+    ]);
+    while (performance.now() < deadline) {
+      const state = await jobProbe(name, deadline - performance.now());
+      if (state === 0)
+        return;
+      if (state !== 1)
+        throw new ACPFailure("cleanup");
+      await new Promise((resolve3) => setTimeout(resolve3, 20));
+    }
+    throw new ACPFailure("cleanup");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function stopProcess(child, options = {}) {
+  if (process2.platform === "win32" && options.windowsJob)
+    return stopWindowsJob(child, options.windowsJob, options.closeObserved);
+  const exited = child.exitCode !== null || child.signalCode !== null;
+  if (!child.pid || exited && !options.ownedTree)
+    return;
+  if (process2.platform === "win32" && exited && options.ownedTree)
+    throw new ACPFailure("cleanup");
+  const closed = options.closeObserved ? Promise.resolve() : new Promise((resolve3) => child.once("close", () => resolve3()));
+  if (process2.platform === "win32") {
+    await new Promise((resolve3, reject) => {
+      const killer = spawn(
+        "taskkill",
+        ["/PID", String(child.pid), "/T", "/F"],
+        { windowsHide: true, stdio: "ignore" }
+      );
+      killer.once("error", reject);
+      killer.once("exit", (code) => code === 0 || !options.ownedTree && child.exitCode !== null ? resolve3() : reject(new ACPFailure("cleanup")));
+    });
+  } else {
+    try {
+      process2.kill(-child.pid, "SIGKILL");
+    } catch (error) {
+      if (error.code !== "ESRCH")
+        throw new ACPFailure("cleanup");
+    }
+  }
+  await closed;
+}
+function baseEnvironment() {
+  const output = {};
+  for (const [key, value] of Object.entries(process2.env)) {
+    if (value !== void 0 && /^(?:path|pathext|systemroot|windir|comspec|temp|tmp|lang|lc_all|ssl_cert_file|node_extra_ca_certs)$/i.test(
+      key
+    )) {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+function engineEnvironment() {
+  const output = baseEnvironment();
+  for (const [key, value] of Object.entries(process2.env)) {
+    if (value !== void 0 && /^(?:HOME|USERPROFILE|APPDATA|LOCALAPPDATA|XDG_CONFIG_HOME|XDG_RUNTIME_DIR|DOCKER_HOST|DOCKER_CONTEXT|DOCKER_CONFIG|CONTAINER_HOST|CONTAINER_CONNECTION|SSH_AUTH_SOCK)$/i.test(
+      key
+    )) {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+async function execute(command, args, cwd, env, timeout = 12e4) {
+  return await new Promise((resolve3, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: {
+        ...command === "podman" || command === "docker" ? engineEnvironment() : baseEnvironment(),
+        ...env
+      },
+      shell: false,
+      detached: process2.platform !== "win32",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let output = "";
+    let failure;
+    const stop = (error) => {
+      failure ??= error;
+      void stopProcess(child).catch((error2) => {
+        failure = error2;
+      });
+    };
+    const timer = setTimeout(() => stop(new ACPFailure("timeout")), timeout);
+    child.stdout.on("data", (chunk) => {
+      output += chunk.toString("utf8");
+      if (Buffer.byteLength(output) > 8 * 1024 * 1024)
+        stop(new ACPFailure("output"));
+    });
+    child.stderr.resume();
+    child.once("error", (error) => {
+      failure = new ACPFailure(
+        command === "git" && error.code === "ENOENT" ? "gitMissing" : "runtime"
+      );
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      if (failure)
+        reject(failure);
+      else if (code !== 0)
+        reject(new ACPFailure("failed", { exitCode: code }));
+      else resolve3(output.trim());
+    });
+  });
+}
+
+// src/acp/ai-acp-client.ts
+async function connectACP(transport, options = {}, inputLimits) {
+  const limits = ACPConfigSchema.parse(inputLimits ?? {});
+  const handlers = options.handlers ?? {};
+  const capabilities = options.capabilities ?? {};
+  const required2 = [];
+  if (capabilities.fs?.readTextFile)
+    required2.push(methods.client.fs.readTextFile);
+  if (capabilities.fs?.writeTextFile)
+    required2.push(methods.client.fs.writeTextFile);
+  if (capabilities.terminal)
+    required2.push(...Object.values(methods.client.terminal));
+  if (capabilities.elicitation)
+    required2.push(methods.client.elicitation.create);
+  if (required2.some((name) => !Object.hasOwn(handlers, name))) {
+    throw new ACPFailure("invalid");
+  }
+  if (options.signal?.aborted)
+    throw new ACPFailure("cancelled");
+  let stop = async () => {
+  };
+  let stream;
+  if (transport.type === "stdio") {
+    const job = process2.platform === "win32" ? windowsACPCommand(transport.command, transport.args ?? []) : void 0;
+    const child = spawn(job ? "powershell.exe" : transport.command, job?.args ?? transport.args ?? [], {
+      cwd: transport.cwd,
+      env: { ...baseEnvironment(), ...transport.env, ...job?.env },
+      detached: process2.platform !== "win32",
+      shell: false,
+      windowsHide: true,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let childClosed = false;
+    child.once("close", () => {
+      childClosed = true;
+    });
+    child.stderr.resume();
+    await new Promise((resolve3, reject) => {
+      child.once("spawn", resolve3);
+      child.once("error", () => reject(new ACPFailure("runtime")));
+    });
+    stop = () => stopProcess(child, { ownedTree: true, closeObserved: childClosed, windowsJob: job?.name });
+    stream = ndJsonStream(
+      Writable.toWeb(child.stdin),
+      Readable.toWeb(child.stdout),
+      { maxMessageBytes: limits.maxContentBytes }
+    );
+  } else if (transport.type === "http") {
+    stream = createHttpStream(transport.url, {
+      headers: transport.headers,
+      maxMessageBytes: limits.maxContentBytes
+    });
+  } else {
+    class BoundedWebSocket extends WebSocket {
+      constructor(url, protocols, options2) {
+        super(url, protocols, {
+          ...options2,
+          maxPayload: limits.maxContentBytes
+        });
+      }
+    }
+    stream = createWebSocketStream(transport.url, {
+      headers: transport.headers,
+      WebSocket: BoundedWebSocket
+    });
+  }
+  const requests = /* @__PURE__ */ new Set();
+  const originalWriter = stream.writable.getWriter();
+  const guardedStream = {
+    writable: new WritableStream({
+      async write(message) {
+        if ("method" in message && "id" in message && message.id !== void 0 && message.id !== null) {
+          requests.add(message.id);
+        }
+        await originalWriter.write(message);
+      },
+      close: () => originalWriter.close(),
+      abort: (reason) => originalWriter.abort(reason)
+    }),
+    readable: stream.readable.pipeThrough(
+      new TransformStream({
+        transform(message, controller) {
+          if (!("method" in message) && "id" in message && message.id !== void 0 && message.id !== null) {
+            requests.delete(message.id);
+          }
+          controller.enqueue(message);
+        }
+      })
+    )
+  };
+  let sessionId;
+  let sessionOpening = false;
+  let closed = false;
+  let failure;
+  let closePromise;
+  const listeners = /* @__PURE__ */ new Set();
+  const app = client({ name: "hai-ai" });
+  app.onNotification(methods.client.session.update, ({ params }) => {
+    if (sessionId && params.sessionId !== sessionId)
+      return;
+    try {
+      options.onEvent?.(params);
+      for (const listener of listeners) listener(params);
+    } catch (error) {
+      failure = error;
+      void close().catch(() => {
+      });
+    }
+  });
+  function owned(id) {
+    if (!sessionId || id !== sessionId)
+      throw new ACPFailure("missing");
+  }
+  app.onRequest(methods.client.session.requestPermission, async (context) => {
+    owned(context.params.sessionId);
+    const handler = handlers["session/request_permission"];
+    if (!handler)
+      return { outcome: { outcome: "cancelled" } };
+    return handler(context);
+  });
+  app.onRequest(methods.client.fs.readTextFile, async (context) => {
+    owned(context.params.sessionId);
+    const handler = handlers["fs/read_text_file"];
+    if (!handler)
+      throw new ACPFailure("unsupported");
+    return handler(context);
+  });
+  app.onRequest(methods.client.fs.writeTextFile, async (context) => {
+    owned(context.params.sessionId);
+    const handler = handlers["fs/write_text_file"];
+    if (!handler)
+      throw new ACPFailure("unsupported");
+    return handler(context);
+  });
+  app.onRequest(methods.client.terminal.create, async (context) => {
+    owned(context.params.sessionId);
+    const handler = handlers["terminal/create"];
+    if (!handler)
+      throw new ACPFailure("unsupported");
+    return handler(context);
+  });
+  app.onRequest(methods.client.terminal.output, async (context) => {
+    owned(context.params.sessionId);
+    const handler = handlers["terminal/output"];
+    if (!handler)
+      throw new ACPFailure("unsupported");
+    return handler(context);
+  });
+  app.onRequest(methods.client.terminal.release, async (context) => {
+    owned(context.params.sessionId);
+    const handler = handlers["terminal/release"];
+    if (!handler)
+      throw new ACPFailure("unsupported");
+    return handler(context);
+  });
+  app.onRequest(methods.client.terminal.waitForExit, async (context) => {
+    owned(context.params.sessionId);
+    const handler = handlers["terminal/wait_for_exit"];
+    if (!handler)
+      throw new ACPFailure("unsupported");
+    return handler(context);
+  });
+  app.onRequest(methods.client.terminal.kill, async (context) => {
+    owned(context.params.sessionId);
+    const handler = handlers["terminal/kill"];
+    if (!handler)
+      throw new ACPFailure("unsupported");
+    return handler(context);
+  });
+  app.onRequest(methods.client.elicitation.create, async (context) => {
+    if ("sessionId" in context.params && typeof context.params.sessionId === "string") {
+      owned(context.params.sessionId);
+    } else if (!("requestId" in context.params) || typeof context.params.requestId !== "string" && typeof context.params.requestId !== "number" || !requests.has(context.params.requestId)) {
+      throw new ACPFailure("missing");
+    }
+    const handler = handlers["elicitation/create"];
+    if (!handler)
+      throw new ACPFailure("unsupported");
+    return handler(context);
+  });
+  const connection = app.connect(guardedStream);
+  function close() {
+    closed = true;
+    if (!closePromise) {
+      const task = (async () => {
+        try {
+          await stop();
+        } finally {
+          connection.close();
+        }
+      })();
+      closePromise = task;
+      void task.catch(() => {
+        if (closePromise === task)
+          closePromise = void 0;
+      });
+    }
+    return closePromise;
+  }
+  async function request(operation, timeout = limits.requestTimeout, signal, prompt = false, isCancelledResponse) {
+    if (closed)
+      throw new ACPFailure("closed");
+    if (signal?.aborted)
+      throw new ACPFailure("cancelled");
+    let timer;
+    let abort = () => {
+    };
+    let reason;
+    const deadline = new Promise((_, reject) => {
+      const fail = (kind) => {
+        if (reason)
+          return;
+        reason = new ACPFailure(kind);
+        if (prompt && sessionId) {
+          void connection.agent.notify(methods.agent.session.cancel, { sessionId }).catch(() => {
+          });
+        }
+        clearTimeout(timer);
+        timer = setTimeout(
+          () => {
+            void close().then(() => reject(reason), reject);
+          },
+          prompt ? limits.cancelTimeout : 0
+        );
+      };
+      timer = setTimeout(fail, timeout, "timeout");
+      abort = () => fail("cancelled");
+      signal?.addEventListener("abort", abort, { once: true });
+    });
+    try {
+      const output = await Promise.race([operation(), deadline]);
+      if (failure)
+        throw failure;
+      if (reason) {
+        if (!(reason.kind === "cancelled" && prompt && isCancelledResponse?.(output)))
+          await close();
+        throw reason;
+      }
+      return output;
+    } catch (error) {
+      if (failure)
+        throw failure;
+      if (reason)
+        throw reason;
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+  try {
+    let checkMcp2 = function(servers) {
+      for (const server of servers) {
+        if ("type" in server && server.type === "http" && !agentCapabilities.mcpCapabilities?.http) {
+          throw new ACPFailure("unsupported");
+        }
+        if ("type" in server && server.type === "sse" && !agentCapabilities.mcpCapabilities?.sse) {
+          throw new ACPFailure("unsupported");
+        }
+      }
+    };
+    var checkMcp = checkMcp2;
+    const initialized = await request(
+      () => connection.agent.request(methods.agent.initialize, {
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: capabilities
+      }),
+      limits.requestTimeout,
+      options.signal
+    );
+    if (initialized.protocolVersion !== PROTOCOL_VERSION)
+      throw new ACPFailure("unsupported");
+    const agentCapabilities = initialized.agentCapabilities ?? {};
+    let activePrompt;
+    async function prompt(content, signal) {
+      if (activePrompt)
+        throw new ACPFailure("busy");
+      if (!sessionId)
+        throw new ACPFailure("missing");
+      if (Buffer.byteLength(JSON.stringify(content)) > limits.maxContentBytes)
+        throw new ACPFailure("output");
+      for (const item of content) {
+        if (item.type === "image" && !agentCapabilities.promptCapabilities?.image || item.type === "audio" && !agentCapabilities.promptCapabilities?.audio || item.type === "resource" && !agentCapabilities.promptCapabilities?.embeddedContext) {
+          throw new ACPFailure("unsupported");
+        }
+      }
+      const events = [];
+      let bytes = 0;
+      let text = "";
+      let messageId;
+      const listener = (event) => {
+        bytes += Buffer.byteLength(JSON.stringify(event));
+        if (events.length >= limits.maxPendingEvents || bytes > limits.maxContentBytes) {
+          throw new ACPFailure("output");
+        }
+        events.push(event);
+        if (event.update.sessionUpdate === "agent_message_chunk" && event.update.content.type === "text") {
+          if (event.update.messageId && event.update.messageId !== messageId)
+            text = "";
+          messageId = event.update.messageId;
+          text += event.update.content.text;
+        }
+      };
+      listeners.add(listener);
+      activePrompt = new AbortController();
+      try {
+        const response = await request(
+          () => connection.agent.request(methods.agent.session.prompt, {
+            sessionId,
+            prompt: content
+          }),
+          limits.promptTimeout,
+          signal ? AbortSignal.any([activePrompt.signal, signal]) : activePrompt.signal,
+          true,
+          (output) => output.stopReason === "cancelled"
+        );
+        if (response.stopReason === "cancelled")
+          throw new ACPFailure("cancelled");
+        return { ...response, text, events };
+      } finally {
+        listeners.delete(listener);
+        activePrompt = void 0;
+      }
+    }
+    return {
+      initialized,
+      /**
+       * 关闭传输并终止拥有的进程树，可重复调用。
+       * @returns 清理完成的 Promise；清理失败抛错。
+       * @example
+       * ```ts
+       * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+       * await connection.close()
+       * ```
+       */
+      close,
+      /**
+       * 执行单轮原生请求并收集有限事件。
+       * @param content - 原生内容块。
+       * @param signal - 本轮取消信号。
+       * @returns 最终文本、停止原因及事件；业务边界负责转换异常。
+       * @example
+       * ```ts
+       * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+       * const response = await connection.prompt([{ type: 'text', text: '检查工程' }])
+       * ```
+       */
+      prompt,
+      /**
+       * 订阅会话事件；返回取消订阅函数。
+       * @param listener - 消费原生事件的回调；抛错会关闭连接。
+       * @returns 取消订阅函数。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * const unsubscribe = connection.subscribe(event => consume(event)); unsubscribe()
+       * ```
+       */
+      subscribe(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      /**
+       * 发送原生取消通知并触发正在执行轮次的取消期限。
+       * @returns 通知发送后的 Promise；本轮终止由 prompt 的取消期限保证。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * await connection.cancel()
+       * ```
+       */
+      cancel: async () => {
+        activePrompt?.abort();
+        if (sessionId && !closed) {
+          await connection.agent.notify(methods.agent.session.cancel, {
+            sessionId
+          });
+        }
+      },
+      /**
+       * 选择握手 authMethods 中的认证方法，凭据由原生进程或远程服务提供。
+       * @param methodId - 对端握手声明的认证方法。
+       * @returns 原生认证响应。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * await connection.authenticate('api-key')
+       * ```
+       */
+      authenticate: (methodId) => request(
+        () => connection.agent.request(methods.agent.authenticate, { methodId })
+      ),
+      /**
+       * 创建此连接唯一的原生会话；MCP 类型必须由智能体声明支持。
+       * @param cwd - 对端可见的绝对工作目录。
+       * @param mcpServers - 原生 MCP 定义，默认空列表。
+       * @returns 包含原生 sessionId 的新建响应。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * await connection.createSession('/srv/project', [])
+       * ```
+       */
+      async createSession(cwd, mcpServers = []) {
+        if (sessionId || sessionOpening)
+          throw new ACPFailure("busy");
+        sessionOpening = true;
+        try {
+          checkMcp2(mcpServers);
+          const response = await request(
+            () => connection.agent.request(methods.agent.session.new, {
+              cwd,
+              mcpServers
+            })
+          );
+          sessionId = response.sessionId;
+          return response;
+        } finally {
+          sessionOpening = false;
+        }
+      },
+      /**
+       * 优先调用原生 resume，否则使用已声明的 load；均不支持则失败。
+       * @param id - 原生会话 ID。
+       * @param cwd - 原会话绝对工作目录。
+       * @param mcpServers - 当前原生 MCP 定义。
+       * @returns 恢复或加载响应；能力缺失时抛错。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * await connection.resumeSession('native-id', '/srv/project')
+       * ```
+       */
+      async resumeSession(id, cwd, mcpServers = []) {
+        if (sessionId || sessionOpening)
+          throw new ACPFailure("busy");
+        checkMcp2(mcpServers);
+        sessionId = id;
+        if (agentCapabilities.sessionCapabilities?.resume) {
+          return request(
+            () => connection.agent.request(methods.agent.session.resume, {
+              sessionId: id,
+              cwd,
+              mcpServers
+            })
+          );
+        }
+        if (agentCapabilities.loadSession) {
+          return request(
+            () => connection.agent.request(methods.agent.session.load, {
+              sessionId: id,
+              cwd,
+              mcpServers
+            })
+          );
+        }
+        throw new ACPFailure("unsupported");
+      },
+      /**
+       * 按智能体原生游标列出会话；未声明 list 能力则失败。
+       * @param cursor - 可选分页游标。
+       * @returns 原生分页会话列表。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * const page = await connection.listSessions()
+       * ```
+       */
+      async listSessions(cursor) {
+        if (!agentCapabilities.sessionCapabilities?.list)
+          throw new ACPFailure("unsupported");
+        return request(
+          () => connection.agent.request(methods.agent.session.list, { cursor })
+        );
+      },
+      /**
+       * 要求远端删除指定原生会话；不代替框架工作区清理。
+       * @param id - 原生会话 ID。
+       * @returns 原生删除响应。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * await connection.deleteSession('native-id')
+       * ```
+       */
+      async deleteSession(id) {
+        if (!agentCapabilities.sessionCapabilities?.delete)
+          throw new ACPFailure("unsupported");
+        return request(
+          () => connection.agent.request(methods.agent.session.delete, {
+            sessionId: id
+          })
+        );
+      },
+      /**
+       * 若远端声明 close 能力则关闭原生会话；进程停止由 close 负责。
+       * @returns 原生关闭完成的 Promise；未声明能力时无需请求。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * await connection.closeSession()
+       * ```
+       */
+      async closeSession() {
+        if (!closed && sessionId && agentCapabilities.sessionCapabilities?.close) {
+          await request(
+            () => connection.agent.request(methods.agent.session.close, {
+              sessionId
+            })
+          );
+        }
+      },
+      /**
+       * 给当前原生会话设置智能体公布的模式。
+       * @param modeId - 原生模式 ID。
+       * @returns 原生模式响应。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * await connection.setMode('code')
+       * ```
+       */
+      setMode: (modeId) => request(
+        () => connection.agent.request(methods.agent.session.setMode, {
+          sessionId,
+          modeId
+        })
+      ),
+      /**
+       * 给当前原生会话设置智能体公布的配置选项。
+       * @param configId - 原生配置选项 ID。
+       * @param value - 智能体允许的选项值。
+       * @returns 原生配置响应。
+       * @example
+       * ```ts
+       * // 模块内部，connection 为 connectACP 返回值，异常由业务边界转换。
+       * await connection.setConfigOption('model', 'coding')
+       * ```
+       */
+      setConfigOption: (configId, value) => request(
+        () => connection.agent.request(methods.agent.session.setConfigOption, {
+          sessionId,
+          configId,
+          value
+        })
+      )
+    };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}
+
+// src/acp/ai-acp-git.ts
+function createGitOperations(workspace, runtime) {
+  const git = (cwd, args, env) => runtime.run("git", ["-C", cwd, ...args], void 0, {
+    GIT_TERMINAL_PROMPT: "0",
+    ...env
+  });
+  const source = (id) => runtime.path(`main/${id}`);
+  async function ready() {
+    if (!workspace.repositories.length)
+      return;
+    try {
+      await runtime.run("git", ["--version"]);
+    } catch {
+      throw new ACPFailure("gitMissing");
+    }
+  }
+  async function clean(path) {
+    if (await git(path, ["status", "--porcelain"]))
+      throw new ACPFailure("conflict");
+  }
+  async function supportedContent(path) {
+    const index = await git(path, ["ls-files", "--stage", "-z"]);
+    if (index.split("\0").some((entry) => entry.startsWith("160000 ")))
+      throw new ACPFailure("unsupported");
+    const attributes = await git(path, ["ls-files", "-z", "--", ".gitattributes", ":(glob)**/.gitattributes"]);
+    for (const file of attributes.split("\0").filter(Boolean)) {
+      const content = await git(path, ["show", `HEAD:${file}`]);
+      if (content.split("\n").some((line) => !line.trimStart().startsWith("#") && /\bfilter=lfs\b/.test(line)))
+        throw new ACPFailure("unsupported");
+    }
+  }
+  async function checked(repo, path = source(repo.id), branch = repo.mainBranch) {
+    if (await git(path, ["branch", "--show-current"]) !== branch)
+      throw new ACPFailure("conflict");
+    if (await git(path, ["remote", "get-url", repo.remote]) !== repo.url)
+      throw new ACPFailure("conflict");
+    await runtime.file("exists", path);
+  }
+  async function reports(operation) {
+    await ready();
+    const output = [];
+    for (const repo of workspace.repositories) {
+      const report = {
+        repositoryId: repo.id,
+        success: false,
+        phase: "check"
+      };
+      try {
+        await operation(repo, report);
+        report.success = true;
+        report.phase = "done";
+      } catch (error) {
+        report.error = error instanceof ACPFailure ? error.kind : "failed";
+      }
+      output.push(report);
+    }
+    if (output.some((item) => !item.success))
+      throw new ACPFailure("partial", { reports: output });
+    return output;
+  }
+  return {
+    /**
+     * 准备工程主目录，只克隆缺失仓库，不覆盖已有内容。
+     * @returns main 的绝对路径；失败保留已创建文件。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * const main = await git.prepare()
+     * ```
+     */
+    async prepare() {
+      await ready();
+      await runtime.file("mkdir", "main/files");
+      for (const repo of workspace.repositories) {
+        await git(runtime.root, [
+          "check-ref-format",
+          "--branch",
+          repo.mainBranch
+        ]);
+        if (await runtime.file("exists", `main/${repo.id}`) === "false") {
+          await git(runtime.root, [
+            "clone",
+            "--origin",
+            repo.remote,
+            "--branch",
+            repo.mainBranch,
+            "--",
+            repo.url,
+            source(repo.id)
+          ]);
+        }
+        await checked(repo);
+        await supportedContent(source(repo.id));
+      }
+      return runtime.path("main");
+    },
+    /**
+     * 从每个工程本地主分支创建独立工作树并复制普通文件。
+     * @param sessionId - 已校验的框架会话 ID。
+     * @param branch - 所有工程使用的同名新分支。
+     * @returns 独立会话目录；中途失败不回滚已有工作树。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * const directory = await git.createWorktree('task-1', 'acp/task-1')
+     * ```
+     */
+    async createWorktree(sessionId, branch) {
+      await ready();
+      await runtime.file("mkdir", `sessions/${sessionId}`);
+      for (const repo of workspace.repositories) {
+        await checked(repo);
+        await supportedContent(source(repo.id));
+        await git(source(repo.id), ["check-ref-format", "--branch", branch]);
+        await git(source(repo.id), [
+          "worktree",
+          "add",
+          "-b",
+          branch,
+          runtime.path(`sessions/${sessionId}/${repo.id}`),
+          `refs/heads/${repo.mainBranch}`
+        ]);
+      }
+      await runtime.file("copy", "main/files", `sessions/${sessionId}/files`);
+      return runtime.path(`sessions/${sessionId}`);
+    },
+    /**
+     * 更新各工程主分支，只允许快进合并。
+     * @returns 每个工程的更新报告；部分失败抛出携带 reports 的异常。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * const reports = await git.updateMain()
+     * ```
+     */
+    updateMain: () => reports(async (repo, report) => {
+      const path = source(repo.id);
+      await checked(repo);
+      await clean(path);
+      report.phase = "fetch";
+      await git(path, [
+        "fetch",
+        "--",
+        repo.remote,
+        `refs/heads/${repo.mainBranch}`
+      ]);
+      report.phase = "merge";
+      await git(path, ["merge", "--ff-only", "FETCH_HEAD"]);
+      report.commit = await git(path, ["rev-parse", "HEAD"]);
+    }),
+    /**
+     * 逐仓提交会话修改并发布，禁止强推。
+     * @param sessionId - 已登记的独立会话 ID。
+     * @param branch - 会话工作树分支名。
+     * @param request - 经过 schema 校验的模式、提交说明及作者。
+     * @returns 各仓发布报告；部分失败保留已提交和已推送的结果。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * const reports = await git.publish('task-1', 'acp/task-1', { mode: 'push-branch', message: '完成任务', author: { name: 'Developer', email: 'dev@example.com' } })
+     * ```
+     */
+    publish: (sessionId, branch, request) => reports(async (repo, report) => {
+      const session = runtime.path(`sessions/${sessionId}/${repo.id}`);
+      const main = source(repo.id);
+      const author = {
+        GIT_AUTHOR_NAME: request.author.name,
+        GIT_AUTHOR_EMAIL: request.author.email,
+        GIT_COMMITTER_NAME: request.author.name,
+        GIT_COMMITTER_EMAIL: request.author.email
+      };
+      await checked(repo, session, branch);
+      if (request.mode === "merge-main") {
+        await checked(repo);
+        await clean(main);
+      }
+      report.phase = "commit";
+      if (await git(session, ["status", "--porcelain"])) {
+        await git(session, ["add", "--all"]);
+        await git(session, ["commit", "-m", request.message], author);
+      }
+      report.commit = await git(session, ["rev-parse", "HEAD"]);
+      let target = session;
+      let targetBranch = branch;
+      if (request.mode === "merge-main") {
+        report.phase = "fetch";
+        await git(main, [
+          "fetch",
+          "--",
+          repo.remote,
+          `refs/heads/${repo.mainBranch}`
+        ]);
+        report.phase = "merge";
+        const remoteHead = await git(main, ["rev-parse", "FETCH_HEAD"]);
+        const localHead = await git(main, ["rev-parse", "HEAD"]);
+        const base = await git(main, ["merge-base", "HEAD", "FETCH_HEAD"]);
+        if (base === localHead)
+          await git(main, ["merge", "--ff-only", "FETCH_HEAD"]);
+        else if (base !== remoteHead)
+          throw new ACPFailure("conflict");
+        await git(main, ["merge", "--no-edit", "--", branch], author);
+        target = main;
+        targetBranch = repo.mainBranch;
+      }
+      report.phase = "push";
+      await git(target, [
+        "push",
+        "--",
+        repo.remote,
+        `HEAD:refs/heads/${targetBranch}`
+      ]);
+      report.commit = await git(target, ["rev-parse", "HEAD"]);
+    })
+  };
+}
+var fileProgram = String.raw`
+const fs = require('node:fs/promises'); const path = require('node:path');
+(async () => {
+ const [root, op, name, content] = process.argv.slice(1);
+ const base = await fs.realpath(root);
+ const target = path.resolve(base, name || '.');
+ const rel = path.relative(base, target);
+ if (rel.startsWith('..') || path.isAbsolute(rel)) throw Error('scope');
+ let cursor = base;
+ for (const part of rel.split(path.sep).filter(Boolean)) {
+   cursor = path.join(cursor, part);
+   try { if ((await fs.lstat(cursor)).isSymbolicLink()) throw Error('link'); }
+   catch (e) { if (e.code !== 'ENOENT') throw e; }
+ }
+ if (op === 'mkdir') await fs.mkdir(target, { recursive: true });
+ else if (op === 'exists') process.stdout.write(String(await fs.stat(target).then(() => true, e => { if(e.code === 'ENOENT') return false; throw e; })));
+ else if (op === 'write') { await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, Buffer.from(content, 'base64'), { flag: 'wx', mode: 0o600 }); }
+ else if (op === 'read') process.stdout.write((await fs.readFile(target)).toString('base64'));
+ else if (op === 'copy') {
+   const destination = path.resolve(base, content);
+   const destRel = path.relative(base, destination);
+   if(destRel.startsWith('..') || path.isAbsolute(destRel)) throw Error('scope');
+   let destCursor = base;
+   for (const part of destRel.split(path.sep).filter(Boolean)) {
+     destCursor = path.join(destCursor, part);
+     try { if ((await fs.lstat(destCursor)).isSymbolicLink()) throw Error('link'); }
+     catch(e) { if(e.code !== 'ENOENT') throw e; }
+   }
+   async function copy(src, dst) {
+     try { if ((await fs.lstat(dst)).isSymbolicLink()) throw Error('link'); }
+     catch(e) { if(e.code !== 'ENOENT') throw e; }
+     const stat = await fs.lstat(src); if(stat.isSymbolicLink()) throw Error('link');
+     if(stat.isDirectory()) { await fs.mkdir(dst, { recursive: true }); for(const item of await fs.readdir(src)) await copy(path.join(src,item),path.join(dst,item)); }
+     else if(stat.isFile()) await fs.copyFile(src,dst,require('node:fs').constants.COPYFILE_EXCL);
+     else throw Error('special file');
+   }
+   await copy(target,destination);
+ }
+ else throw Error('operation');
+})().catch(() => { process.exitCode = 1 });`;
+async function selectEngine(preference) {
+  for (const engine of preference === "auto" ? ["podman", "docker"] : [preference]) {
+    try {
+      await execute(engine, ["info"], void 0, void 0, 15e3);
+      return engine;
+    } catch {
+      if (preference !== "auto")
+        throw new ACPFailure("runtime", { engine });
+    }
+  }
+  throw new ACPFailure("runtime");
+}
+async function openRuntime(workspace) {
+  const environment = {};
+  for (const [target, source] of Object.entries(workspace.environmentRefs)) {
+    if (!process2.env[source])
+      throw new ACPFailure("invalid", { environment: source });
+    environment[target] = process2.env[source];
+  }
+  let root;
+  let container;
+  let engine;
+  let closed = false;
+  if (workspace.storage.type === "directory") {
+    await mkdir(workspace.storage.path, { recursive: true });
+    root = await realpath(resolve(workspace.storage.path));
+  } else {
+    engine = await selectEngine(workspace.storage.engine);
+    root = "/workspace";
+    container = await execute(engine, [
+      "create",
+      // 远程 Podman 会从服务端继承代理，绕过最小环境白名单；只允许显式 environmentRefs 注入。
+      ...engine === "podman" ? ["--http-proxy=false"] : [],
+      "--init",
+      "--mount",
+      `type=volume,src=${workspace.storage.name},dst=/workspace`,
+      "--mount",
+      `type=volume,src=${workspace.storage.name}-state,dst=/state`,
+      "--workdir",
+      root,
+      "--entrypoint",
+      "node",
+      workspace.storage.image,
+      "-e",
+      "setInterval(() => {}, 2147483647)"
+    ]);
+    if (!/^[a-f0-9]{12,64}$/.test(container))
+      throw new ACPFailure("runtime");
+    try {
+      await execute(engine, ["start", container]);
+    } catch (error) {
+      await execute(engine, ["rm", "-f", container]);
+      throw error;
+    }
+  }
+  const ensure = () => {
+    if (closed)
+      throw new ACPFailure("closed");
+  };
+  const path = (relative2) => workspace.storage.type === "volume" ? `${root}/${relative2}` : resolve(root, relative2);
+  function transport(command, args, cwd, env = {}) {
+    ensure();
+    const values = { ...environment, ...env };
+    return engine && container ? {
+      type: "stdio",
+      command: engine,
+      args: [
+        "exec",
+        "-i",
+        "--workdir",
+        cwd,
+        ...Object.keys(values).flatMap((key) => [
+          "--env",
+          Object.hasOwn(engineEnvironment(), key) ? `${key}=${values[key]}` : key
+        ]),
+        container,
+        command,
+        ...args
+      ],
+      env: { ...values, ...engineEnvironment() }
+    } : { type: "stdio", command, args, cwd, env: values };
+  }
+  async function run(command, args, cwd = root, env) {
+    const launch = transport(command, args, cwd, env);
+    if (launch.type !== "stdio")
+      throw new ACPFailure("runtime");
+    return execute(launch.command, launch.args ?? [], launch.cwd, launch.env);
+  }
+  return {
+    root,
+    path,
+    transport,
+    run,
+    resource: container ? { engine, container } : void 0,
+    /**
+     * 计算受管理的会话状态目录。
+     * @param sessionId - 已校验的会话 ID。
+     * @returns 状态目录绝对路径；不创建目录。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * const state = runtime.state('task-1')
+     * ```
+     */
+    state: (sessionId) => workspace.storage.type === "volume" ? `/state/${sessionId}` : path(`.state/${sessionId}`),
+    /**
+     * 执行受工作区约束的文件操作，拒绝链接和路径逃逸。
+     * @param op - mkdir/exists/write/read/copy 操作。
+     * @param name - 工作区内相对路径或已校验的内部绝对路径。
+     * @param content - write 时为 Base64，copy 时为目标路径，其余为空。
+     * @returns 文本结果：exists 为 true/false，read 为 Base64，其余为空。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * await runtime.file('mkdir', 'main/files')
+     * ```
+     */
+    async file(op, name, content = "") {
+      return run(
+        workspace.storage.type === "volume" ? "node" : process2.execPath,
+        ["-e", fileProgram, root, op, name, content]
+      );
+    },
+    /**
+     * 向已创建的独立状态目录写入配置，拒绝符号链接。
+     * @param sessionId - 已校验的会话 ID。
+     * @param name - 无目录分隔符的配置文件名。
+     * @param content - 原生配置文本，可能含凭据，不应记录日志。
+     * @returns 完成写入的 Promise。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * await runtime.writeState('task-1', 'config.json', '{}')
+     * ```
+     */
+    async writeState(sessionId, name, content) {
+      if (!/^[\w-]+\.[a-z0-9]+$/i.test(name))
+        throw new ACPFailure("invalid");
+      const directory = workspace.storage.type === "volume" ? `/state/${sessionId}` : path(`.state/${sessionId}`);
+      await run(
+        workspace.storage.type === "volume" ? "node" : process2.execPath,
+        [
+          "-e",
+          'const f=require("node:fs"),p=require("node:path");const d=process.argv[1];let c=p.parse(d).root;for(const part of d.slice(c.length).split(p.sep).filter(Boolean)){c=p.join(c,part);if(f.lstatSync(c).isSymbolicLink())process.exit(1)}const t=p.join(d,process.argv[2]);try{if(f.lstatSync(t).isSymbolicLink())process.exit(1)}catch(e){if(e.code!=="ENOENT")throw e}f.writeFileSync(t,process.argv[3],{mode:384})',
+          directory,
+          name,
+          content
+        ]
+      );
+    },
+    /**
+     * 创建私有状态目录，拒绝祖先目录中的符号链接。
+     * @param sessionId - 已校验的会话 ID。
+     * @returns 已创建的状态目录绝对路径。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * const directory = await runtime.stateDirectory('task-1')
+     * ```
+     */
+    async stateDirectory(sessionId) {
+      const target = workspace.storage.type === "volume" ? `/state/${sessionId}` : path(`.state/${sessionId}`);
+      await run(
+        workspace.storage.type === "volume" ? "node" : process2.execPath,
+        [
+          "-e",
+          'const f=require("node:fs"),p=require("node:path"),d=process.argv[1];let c=p.parse(d).root;for(const part of d.slice(c.length).split(p.sep).filter(Boolean)){c=p.join(c,part);try{if(f.lstatSync(c).isSymbolicLink())process.exit(1)}catch(e){if(e.code!=="ENOENT")throw e;f.mkdirSync(c,{mode:448})}}',
+          target
+        ]
+      );
+      return target;
+    },
+    /**
+     * 关闭本次拥有的容器；目录和 volume 保留。
+     * @returns 清理完成的 Promise；失败抛错，不能视为资源已释放。
+     * @example
+     * ```ts
+     * // 内部上下文：runtime/git/connection 为相应工厂已创建的句柄。
+     * await runtime.close()
+     * ```
+     */
+    async close() {
+      if (closed)
+        return;
+      if (engine && container) {
+        try {
+          await execute(engine, ["rm", "--force", container]);
+        } catch {
+          throw new ACPFailure("cleanup", { engine, container });
+        }
+      }
+      closed = true;
+    }
+  };
+}
+
+// src/acp/ai-acp-functions.ts
+function createACPOperations(provider, config, extensions = {}, modelConfig = async () => config, mcpLookup) {
+  const workspaces = provider.createRelStore(
+    "hai_ai_acp_workspaces"
+  );
+  const agents = provider.createRelStore("hai_ai_acp_agents");
+  const sessions = provider.createRelStore(
+    "hai_ai_acp_sessions"
+  );
+  const locks = provider.createRelStore(
+    "hai_ai_acp_locks"
+  );
+  const adapters = { ...nativeAdapters, ...extensions };
+  const live = /* @__PURE__ */ new Map();
+  const connections = /* @__PURE__ */ new Set();
+  const limits = ACPConfigSchema.parse(config.acp ?? {});
+  const pending = /* @__PURE__ */ new Set();
+  const stopping = /* @__PURE__ */ new Map();
+  let closed = false;
+  const agentRegistry = createResourceRegistry(
+    agents,
+    ACPAgentSchema,
+    config.acp?.agents ?? [],
+    () => !closed
+  );
+  const workspaceRegistry = createResourceRegistry(
+    workspaces,
+    ACPWorkspaceSchema,
+    config.acp?.workspaces ?? [],
+    () => !closed
+  );
+  function ensure() {
+    if (closed)
+      throw new ACPFailure("closed");
+  }
+  async function protect(operation) {
+    const task = (async () => {
+      try {
+        ensure();
+        return ok(await operation());
+      } catch (error) {
+        return acpError(error);
+      }
+    })();
+    pending.add(task);
+    try {
+      return await task;
+    } finally {
+      pending.delete(task);
+    }
+  }
+  async function modelSignature(agent) {
+    return createHash("sha256").update(
+      JSON.stringify(
+        resolveAgentModels(agent, await modelConfig()).map(
+          ({ id, config: model }) => ({
+            id,
+            model: model.model,
+            protocol: model.protocol,
+            baseUrl: model.baseUrl,
+            capabilities: model.capabilities
+          })
+        )
+      )
+    ).digest("hex");
+  }
+  async function protectResult(operation) {
+    const result = await protect(operation);
+    return result.success ? result.data : result;
+  }
+  async function getAgent(id) {
+    const entry = await agentRegistry.read(id);
+    if (!entry)
+      throw new ACPFailure("missing", { id });
+    return entry.value;
+  }
+  async function getWorkspace(id) {
+    const entry = await workspaceRegistry.read(id);
+    if (!entry)
+      throw new ACPFailure("missing", { id });
+    const workspace = await normalizeWorkspace(entry.value);
+    await checkWorkspaceOverlap(workspace);
+    return workspace;
+  }
+  const workspaceKey = (workspace) => workspace.storage.type === "directory" ? `directory:${process2.platform === "win32" ? workspace.storage.path.toLowerCase() : workspace.storage.path}` : `volume:${workspace.storage.engine}:${workspace.storage.name}`;
+  async function normalizeWorkspace(workspace) {
+    if (workspace.storage.type === "directory") {
+      await mkdir(workspace.storage.path, { recursive: true });
+      workspace.storage.path = await realpath(resolve(workspace.storage.path));
+    } else {
+      workspace.storage.engine = await selectEngine(workspace.storage.engine);
+    }
+    return workspace;
+  }
+  async function canonicalDirectory(path) {
+    const target = resolve(path);
+    try {
+      return await realpath(target);
+    } catch (error) {
+      if (error.code !== "ENOENT" || dirname(target) === target) {
+        throw error;
+      }
+      return resolve(
+        await canonicalDirectory(dirname(target)),
+        basename(target)
+      );
+    }
+  }
+  async function checkWorkspaceOverlap(workspace) {
+    for (const entry of await workspaceRegistry.values()) {
+      if (entry.id === workspace.id)
+        continue;
+      if (entry.storage.type === "directory" && workspace.storage.type === "directory") {
+        const existing = await canonicalDirectory(entry.storage.path);
+        const child = relative(existing, workspace.storage.path);
+        const parent = relative(workspace.storage.path, existing);
+        if (!child.startsWith("..") && !isAbsolute(child) || !parent.startsWith("..") && !isAbsolute(parent)) {
+          throw new ACPFailure("conflict");
+        }
+      } else if (entry.storage.type === "volume" && workspace.storage.type === "volume" && entry.storage.name === workspace.storage.name && (entry.storage.engine === "auto" || entry.storage.engine === workspace.storage.engine)) {
+        throw new ACPFailure("conflict");
+      }
+    }
+  }
+  async function get(store, id) {
+    sessionIdentitySchema.parse(id);
+    const data = await store.get(id);
+    if (!data)
+      throw new ACPFailure("missing", { id });
+    return data;
+  }
+  async function acquire(key) {
+    const previous = await locks.readVersioned(key);
+    if (previous?.data.owner)
+      throw new ACPFailure("busy");
+    const owner = randomUUID();
+    const version = await locks.compareAndSwap(key, {
+      expectedVersion: previous?.version,
+      data: { owner }
+    });
+    if (!version)
+      throw new ACPFailure("busy");
+    return async () => {
+      if (!await locks.compareAndSwap(key, {
+        expectedVersion: version,
+        data: { owner: null }
+      })) {
+        throw new ACPFailure("cleanup");
+      }
+    };
+  }
+  async function withDefinitions(operation) {
+    const release = await acquire("definition-registry");
+    try {
+      return await operation();
+    } finally {
+      await release();
+    }
+  }
+  async function workspaceOperation(workspace, action) {
+    const release = await acquire(`${workspaceKey(workspace)}:main`);
+    let runtime;
+    try {
+      runtime = await openRuntime(workspace);
+      return await action(runtime);
+    } finally {
+      await runtime?.close();
+      await release();
+    }
+  }
+  async function unique(store, id, data) {
+    if (!await store.compareAndSwap(id, { expectedVersion: void 0, data }))
+      throw new ACPFailure("conflict", { id });
+    return data;
+  }
+  async function validateAgent(agent) {
+    if (agent.mode === "custom-service")
+      return;
+    if (!adapters[agent.adapter])
+      throw new ACPFailure("unsupported", { adapter: agent.adapter });
+    resolveAgentModels(agent, await modelConfig());
+  }
+  async function launchAgent(agent, runtime, info) {
+    if (agent.mode === "custom-service") {
+      return {
+        type: agent.transport,
+        url: agent.url,
+        headers: resolveEnvironment(agent.headerEnv)
+      };
+    }
+    if (!runtime)
+      throw new ACPFailure("missing");
+    const statePath = await runtime.stateDirectory(info.id);
+    const native = await adapters[agent.adapter].configure({
+      agent,
+      models: resolveAgentModels(agent, await modelConfig()),
+      modelId: info.modelId,
+      statePath
+    });
+    for (const [name, content] of Object.entries(native.files ?? {}))
+      await runtime.writeState(info.id, name, content);
+    return runtime.transport(native.command, native.args, info.cwd, {
+      HOME: statePath,
+      USERPROFILE: statePath,
+      ...resolveEnvironment(agent.environmentRefs),
+      ...native.env
+    });
+  }
+  async function stop(id) {
+    const existing = stopping.get(id);
+    if (existing)
+      return existing;
+    const task = stopOne(id);
+    stopping.set(id, task);
+    try {
+      await task;
+    } finally {
+      stopping.delete(id);
+    }
+  }
+  async function stopOne(id) {
+    const current = live.get(id);
+    if (!current)
+      return;
+    await current.connection.cancel();
+    try {
+      await current.connection.closeSession();
+    } catch {
+    } finally {
+      await current.connection.close();
+      await current.runtime?.close();
+    }
+    current.info.status = "closed";
+    current.info.resource = void 0;
+    await sessions.save(id, current.info);
+    await current.release();
+    live.delete(id);
+  }
+  async function start(info, options, resume) {
+    const agent = info.agent;
+    const releaseSession = await acquire(`session:${info.id}`);
+    let releaseDirectory;
+    let runtime;
+    let connection;
+    let recordExists = true;
+    try {
+      const workspace = info.workspaceId ? await getWorkspace(info.workspaceId) : void 0;
+      if (!agent.enabled)
+        throw new ACPFailure("unsupported");
+      if (resume && !await sessions.get(info.id)) {
+        recordExists = false;
+        throw new ACPFailure("missing");
+      }
+      if (workspace) {
+        if (agent.mode === "custom-service")
+          throw new ACPFailure("unsupported");
+        if (agent.mode === "embedded" && workspace.storage.type !== "directory" || agent.mode === "builtin-service" && workspace.storage.type !== "volume") {
+          throw new ACPFailure("unsupported");
+        }
+        if (agent.mode === "builtin-service" && workspace.storage.type === "volume" && (agent.image !== workspace.storage.image || agent.engine !== "auto" && agent.engine !== workspace.storage.engine)) {
+          throw new ACPFailure("conflict");
+        }
+        if (!info.newWorktree)
+          releaseDirectory = await acquire(`${workspaceKey(workspace)}:main`);
+        if (!resume) {
+          const releasePrepare = info.newWorktree ? await acquire(`${workspaceKey(workspace)}:main`) : void 0;
+          try {
+            runtime = await openRuntime(workspace);
+            info.resource = runtime.resource;
+            await sessions.save(info.id, info);
+            const git = createGitOperations(workspace, runtime);
+            await git.prepare();
+            info.cwd = info.newWorktree ? await git.createWorktree(info.id, info.branch) : runtime.path("main");
+          } finally {
+            await releasePrepare?.();
+          }
+        } else {
+          runtime = await openRuntime(workspace);
+        }
+      } else if (agent.mode !== "custom-service" || !info.cwd || info.newWorktree) {
+        throw new ACPFailure("invalid");
+      }
+      ensure();
+      const transport = await launchAgent(agent, runtime, info);
+      connection = await connectACP(transport, options, limits);
+      if (info.mcpServerIds?.length && !mcpLookup)
+        throw new ACPFailure("unsupported");
+      const mcpServers = [
+        ...info.mcpServers,
+        ...info.mcpServerIds?.length && mcpLookup ? await mcpLookup(info.mcpServerIds) : []
+      ];
+      if (resume) {
+        if (!info.nativeId)
+          throw new ACPFailure("unsupported");
+        await connection.resumeSession(info.nativeId, info.cwd, mcpServers);
+      } else {
+        info.nativeId = (await connection.createSession(info.cwd, mcpServers)).sessionId;
+      }
+      ensure();
+      info.status = "active";
+      info.resource = runtime?.resource;
+      await sessions.save(info.id, info);
+      const value = {
+        info,
+        connection,
+        runtime,
+        release: async () => {
+          await releaseDirectory?.();
+          await releaseSession();
+        }
+      };
+      live.set(info.id, value);
+      return handle(info.id, value);
+    } catch (error) {
+      await connection?.close();
+      await runtime?.close();
+      info.status = "failed";
+      info.resource = void 0;
+      if (recordExists)
+        await sessions.save(info.id, info);
+      await releaseDirectory?.();
+      await releaseSession();
+      throw error;
+    }
+  }
+  function handle(id, expected) {
+    function current() {
+      ensure();
+      const value = live.get(id);
+      if (!value || expected && value !== expected)
+        throw new ACPFailure("closed");
+      return value;
+    }
+    async function gitOperation(publish) {
+      const request = publish ? ACPPublishSchema.parse(publish) : void 0;
+      const info = await get(sessions, id);
+      if (!info.workspaceId || request && !info.newWorktree)
+        throw new ACPFailure("unsupported");
+      const workspace = await getWorkspace(info.workspaceId);
+      await stop(id);
+      const release = await acquire(`session:${id}`);
+      try {
+        return await workspaceOperation(workspace, (runtime) => request ? createGitOperations(workspace, runtime).publish(
+          id,
+          info.branch,
+          request
+        ) : createGitOperations(workspace, runtime).updateMain());
+      } finally {
+        await release();
+      }
+    }
+    return {
+      id,
+      /**
+       * 读取持久会话信息，包括状态、原生 ID 和当前容器。
+       * @returns 包含 ACPSessionInfo 的 HaiResult；记录不存在时返回失败。
+       * @example
+       * ```ts
+       * // session 为 sessions.create/get/resume 成功返回的 data。
+       * // 普通 API 先检查 result.success，再读取 data 或 error。
+       * const result = await session.info()
+       * ```
+       */
+      info: () => protect(() => get(sessions, id)),
+      /**
+       * 发送一轮内容，等待最终停止原因、最终消息文本和完整事件；同一会话不允许并发轮次。
+       * @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, signal) => protect(() => current().connection.prompt(content, signal)),
+      /**
+       * 仅接受正常结束的一份 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: (content, schema, signal) => protect(async () => {
+        const response = await current().connection.prompt(content, signal);
+        if (response.stopReason !== "end_turn")
+          throw new ACPFailure("output");
+        let text = response.text.trim();
+        const fenced = /^```(?:json)?[ \t]*\n([\s\S]*?)\n```$/.exec(text);
+        if (fenced)
+          text = fenced[1];
+        try {
+          return schema.parse(JSON.parse(text));
+        } catch {
+          throw new ACPFailure("output");
+        }
+      }),
+      /**
+       * 迭代本轮 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 }
+       * ```
+       */
+      async *stream(content, signal) {
+        const value = current();
+        const controller = new AbortController();
+        const queue = [];
+        let wake;
+        const completion = { done: false };
+        let error;
+        const unsubscribe = value.connection.subscribe((event) => {
+          if (queue.length >= limits.maxPendingEvents)
+            throw new ACPFailure("output");
+          queue.push(event);
+          wake?.();
+        });
+        const task = value.connection.prompt(
+          content,
+          signal ? AbortSignal.any([signal, controller.signal]) : controller.signal
+        ).catch((reason) => {
+          error = reason;
+        }).finally(() => {
+          completion.done = true;
+          wake?.();
+        });
+        try {
+          while (!completion.done || queue.length) {
+            if (queue.length) {
+              yield queue.shift();
+            } else {
+              await new Promise((resolve3) => {
+                wake = resolve3;
+              });
+            }
+          }
+          if (error)
+            throw error;
+        } finally {
+          unsubscribe();
+          controller.abort();
+          await task;
+        }
+      },
+      /**
+       * 请求取消正在执行的一轮；超时未停止时关闭所拥有的传输。
+       * @returns 取消完成的 HaiResult；超时或清理失败返回错误。
+       * @example
+       * ```ts
+       * // session 为 sessions.create/get/resume 成功返回的 data。
+       * // 普通 API 先检查 result.success，再读取 data 或 error。
+       * const result = await session.cancel()
+       * ```
+       */
+      cancel: () => protect(() => current().connection.cancel()),
+      /**
+       * 选择智能体公布的原生模式 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) => protect(() => current().connection.setMode(mode)),
+      /**
+       * 设置智能体公布的原生配置选项；值必须符合该智能体的选项定义。
+       * @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, value) => protect(() => current().connection.setConfigOption(key, value)),
+      /**
+       * 先关闭会话执行环境，再 fetch 并仅快进各工程明确配置的主分支；不修改会话分支。
+       * @returns 各仓更新报告；部分失败时报告位于 error.cause.reports。
+       * @example
+       * ```ts
+       * // session 为 sessions.create/get/resume 成功返回的 data。
+       * // 普通 API 先检查 result.success，再读取 data 或 error。
+       * const result = await session.updateMain()
+       * ```
+       */
+      updateMain: () => protect(() => gitOperation()),
+      /**
+       * 关闭执行环境后逐仓提交并推送；仅支持受管理的独立会话，部分失败保留各仓报告，禁止强推。
+       * @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) => protect(() => gitOperation(request)),
+      /**
+       * 停止拥有的进程或容器，释放占用；保留工作目录和原生状态，供后续显式恢复。
+       * @returns 关闭完成的 HaiResult；清理失败时不释放仍在占用的资源。
+       * @example
+       * ```ts
+       * // session 为 sessions.create/get/resume 成功返回的 data。
+       * // 普通 API 先检查 result.success，再读取 data 或 error。
+       * const result = await session.close()
+       * ```
+       */
+      close: () => protect(() => stop(id))
+    };
+  }
+  return {
+    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) => protectResult(async () => {
+        const agent = ACPAgentSchema.parse(input);
+        await validateAgent(agent);
+        return agentRegistry.operations.register(agent);
+      }),
+      /**
+       * 按 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: agentRegistry.operations.get,
+      /**
+       * 列出配置与数据库合并后的智能体；同 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: agentRegistry.operations.list,
+      /**
+       * 整体替换数据库智能体；可传入 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, version) => protectResult(async () => {
+        const agent = ACPAgentSchema.parse(input);
+        await validateAgent(agent);
+        return agentRegistry.operations.update(agent, version);
+      }),
+      /**
+       * 删除无会话引用的数据库智能体定义；不删除镜像或外部服务。
+       * @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, version) => protectResult(async () => {
+        return withDefinitions(async () => {
+          const existing = await agentRegistry.read(id);
+          if (existing?.source === "config")
+            return agentRegistry.operations.remove(id, version);
+          if ((await sessions.query({ where: { agentId: id } })).length)
+            throw new ACPFailure("busy");
+          return agentRegistry.operations.remove(id, version);
+        });
+      }),
+      /**
+       * 解析模型和原生配置，验证适配器是否兼容；不持久保存模型凭据。
+       * @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, modelId) => protect(async () => {
+        const agent = await getAgent(id);
+        await validateAgent(agent);
+        if (agent.mode === "custom-service")
+          return { agentId: id, mode: agent.mode, modelIds: [] };
+        await adapters[agent.adapter].configure({
+          agent,
+          models: resolveAgentModels(agent, await modelConfig()),
+          modelId: modelId ?? agent.defaultModelId ?? agent.modelIds[0],
+          statePath: "/state/validation"
+        });
+        return { agentId: id, mode: agent.mode, modelIds: agent.modelIds };
+      }),
+      /**
+       * 实际启动并握手后关闭连接，返回智能体能力；托管模式需指定工作区。
+       * @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, options = {}) => protect(async () => {
+        const agent = await getAgent(id);
+        await validateAgent(agent);
+        if (agent.mode !== "custom-service") {
+          if (!options.workspaceId)
+            throw new ACPFailure("invalid");
+          const workspace = await getWorkspace(options.workspaceId);
+          if (agent.mode === "embedded" && workspace.storage.type !== "directory" || agent.mode === "builtin-service" && (workspace.storage.type !== "volume" || workspace.storage.image !== agent.image)) {
+            throw new ACPFailure("unsupported");
+          }
+          return workspaceOperation(workspace, async (runtime) => {
+            const info = {
+              id: randomUUID(),
+              agentId: id,
+              cwd: runtime.root,
+              newWorktree: false,
+              agent,
+              status: "opening",
+              mcpServers: [],
+              modelId: agent.defaultModelId ?? agent.modelIds[0]
+            };
+            const connection2 = await connectACP(
+              await launchAgent(agent, runtime, info),
+              options,
+              limits
+            );
+            try {
+              return connection2.initialized;
+            } finally {
+              await connection2.close();
+            }
+          });
+        }
+        const connection = await connectACP(
+          {
+            type: agent.transport,
+            url: agent.url,
+            headers: resolveEnvironment(agent.headerEnv)
+          },
+          options,
+          limits
+        );
+        try {
+          return connection.initialized;
+        } finally {
+          await connection.close();
+        }
+      })
+    },
+    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) => protectResult(async () => {
+        const workspace = ACPWorkspaceSchema.parse(input);
+        if ((await workspaceRegistry.read(workspace.id))?.source === "config")
+          return workspaceRegistry.operations.register(workspace);
+        await normalizeWorkspace(workspace);
+        const release = await acquire("definition-registry");
+        try {
+          await checkWorkspaceOverlap(workspace);
+          return await workspaceRegistry.operations.register(workspace);
+        } finally {
+          await release();
+        }
+      }),
+      /**
+       * 读取工作区定义及来源；配置条目无数据库版本。
+       * @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: workspaceRegistry.operations.get,
+      /**
+       * 列出配置与数据库合并后的工作区；不创建路径或克隆工程。
+       * @returns 去重后的工作区列表；列表项不含数据库 version。
+       * @example
+       * ```ts
+       * import { ai } from '@h-ai/ai'
+       * // 前提：ai 已成功初始化。
+       * // 普通 API 先检查 result.success，再读取 data 或 error。
+       * const result = await ai.acp.workspaces.list()
+       * ```
+       */
+      list: workspaceRegistry.operations.list,
+      /**
+       * 整体替换无会话引用的数据库工作区，重新检查存储位置重叠；配置条目不可修改。
+       * @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, version) => protectResult(async () => {
+        const workspace = ACPWorkspaceSchema.parse(input);
+        const existing = await workspaceRegistry.read(workspace.id);
+        if (existing?.source === "config")
+          return workspaceRegistry.operations.update(workspace, version);
+        const release = await acquire("definition-registry");
+        try {
+          if ((await sessions.query({ where: { workspaceId: workspace.id } })).length) {
+            throw new ACPFailure("busy");
+          }
+          await normalizeWorkspace(workspace);
+          await checkWorkspaceOverlap(workspace);
+          return await workspaceRegistry.operations.update(
+            workspace,
+            version
+          );
+        } finally {
+          await release();
+        }
+      }),
+      /**
+       * 创建目录并克隆缺失工程；已有内容不自动 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) => protect(
+        async () => workspaceOperation(await getWorkspace(id), (runtime) => createGitOperationsInput(id, runtime))
+      ),
+      /**
+       * 将有限大小的文件写入 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, files) => protect(async () => {
+        if (files.length > 1e3 || files.reduce(
+          (sum, file) => sum + Buffer.byteLength(file.content),
+          0
+        ) > limits.maxContentBytes) {
+          throw new ACPFailure("output");
+        }
+        for (const file of files) {
+          if (!file.path || file.path.split(/[\\/]/).some(
+            (part) => !part || part === "." || part === ".." || part === ".git"
+          ) || isAbsolute(file.path)) {
+            throw new ACPFailure("invalid");
+          }
+        }
+        return workspaceOperation(await getWorkspace(id), async (runtime) => {
+          await runtime.file("mkdir", "main/files");
+          for (const file of files) {
+            if (await runtime.file("exists", `main/files/${file.path}`) === "true") {
+              throw new ACPFailure("conflict");
+            }
+          }
+          for (const file of files) {
+            await runtime.file(
+              "write",
+              `main/files/${file.path}`,
+              Buffer.from(file.content).toString("base64")
+            );
+          }
+          return { imported: files.map((file) => file.path) };
+        });
+      }),
+      /**
+       * 移除无会话引用的数据库定义，保留磁盘目录、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, version) => protectResult(async () => {
+        return withDefinitions(async () => {
+          const existing = await workspaceRegistry.read(id);
+          if (existing?.source === "config")
+            return workspaceRegistry.operations.remove(id, version);
+          if ((await sessions.query({ where: { workspaceId: id } })).length)
+            throw new ACPFailure("busy");
+          return workspaceRegistry.operations.remove(id, version);
+        });
+      })
+    },
+    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) => protect(async () => {
+        const info = await withDefinitions(async () => {
+          const agent = await getAgent(options.agentId);
+          await validateAgent(agent);
+          if (!agent.enabled)
+            throw new ACPFailure("unsupported");
+          const id = sessionIdentitySchema.parse(options.id ?? randomUUID());
+          const modelId = options.modelId ?? agent.defaultModelId ?? agent.modelIds[0];
+          if (modelId && !agent.modelIds.includes(modelId))
+            throw new ACPFailure("model");
+          const info2 = {
+            id,
+            agentId: agent.id,
+            workspaceId: options.workspaceId,
+            cwd: options.cwd ?? "",
+            newWorktree: options.newWorktree ?? false,
+            branch: options.newWorktree ? branchNameSchema.parse(options.branch ?? `acp/${id}`) : void 0,
+            modelId,
+            modelSignature: await modelSignature(agent),
+            status: "opening",
+            agent,
+            mcpServers: options.mcpServers ?? [],
+            mcpServerIds: options.mcpServerIds
+          };
+          if (options.workspaceId)
+            await getWorkspace(options.workspaceId);
+          await unique(sessions, id, info2);
+          return info2;
+        });
+        return start(info, options, false);
+      }),
+      /**
+       * 获取持久会话的管理句柄；已关闭会话需要 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) => protect(async () => {
+        await get(sessions, id);
+        return handle(id);
+      }),
+      /**
+       * 列出持久会话，可按工作区 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) => protect(
+        () => sessions.query({ where: workspaceId ? { workspaceId } : {} })
+      ),
+      /**
+       * 使用原生会话 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, options = {}) => protect(async () => {
+        const info = await get(sessions, id);
+        if (info.status === "opening" || info.status === "active")
+          throw new ACPFailure("busy");
+        const agent = await getAgent(info.agentId);
+        if (!agent.enabled || JSON.stringify(agent) !== JSON.stringify(info.agent)) {
+          throw new ACPFailure("conflict");
+        }
+        if (info.modelSignature !== await modelSignature(agent))
+          throw new ACPFailure("conflict");
+        return start(info, options, true);
+      }),
+      /**
+       * 关闭本进程拥有的会话并释放锁，不删除历史和工程内容。
+       * @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) => protect(() => stop(id)),
+      /**
+       * 仅删除已关闭或失败的会话记录；不删除工作树及原生文件，不替代 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) => protect(async () => {
+        const info = await get(sessions, id);
+        if (live.has(id) || info.status === "active" || info.status === "opening") {
+          throw new ACPFailure("busy");
+        }
+        const release = await acquire(`session:${id}`);
+        try {
+          await sessions.remove(id);
+        } finally {
+          await release();
+        }
+      })
+    },
+    /**
+     * 连接原生 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, options = {}) => protect(async () => {
+      const connection = await connectACP(transport, options, limits);
+      connections.add(connection);
+      return {
+        info: connection.initialized,
+        /**
+         * 选择对端握手公布的认证方法，返回 HaiResult。
+         * @param method - initialize 返回的认证方法 ID。
+         * @returns 认证响应的 HaiResult。
+         * @example
+         * ```ts
+         * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+         * const result = await connection.authenticate('api-key')
+         * ```
+         */
+        authenticate: (method) => protect(() => connection.authenticate(method)),
+        /**
+         * 在对端可见的绝对 cwd 创建原生会话，返回 prompt/cancel 句柄。
+         * @param cwd - 对端文件系统可见的绝对工作目录。
+         * @param mcpServers - 可选原生 MCP 定义；调用方负责凭据与授权。
+         * @returns 原生会话句柄；不创建框架持久会话记录。
+         * @example
+         * ```ts
+         * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+         * const result = await connection.createSession('/srv/project', [])
+         * ```
+         */
+        createSession: (cwd, mcpServers) => protect(async () => {
+          const session = await connection.createSession(cwd, mcpServers);
+          return {
+            id: session.sessionId,
+            /**
+             * 发送一轮原生内容，返回最终文本、停止原因和事件。
+             * @param content - 原生 ACP 内容块。
+             * @param signal - 可选本轮取消信号。
+             * @returns 最终文本、停止原因和事件的 HaiResult。
+             * @example
+             * ```ts
+             * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+             * const result = await session.prompt([{ type: 'text', text: '检查工程' }])
+             * ```
+             */
+            prompt: (content, signal) => protect(() => connection.prompt(content, signal)),
+            /**
+             * 取消当前轮次，超时则关闭连接。
+             * @returns 取消完成的 HaiResult。
+             * @example
+             * ```ts
+             * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+             * const result = await session.cancel()
+             * ```
+             */
+            cancel: () => protect(() => connection.cancel())
+          };
+        }),
+        /**
+         * 读取对端原生会话列表；未声明相应能力时返回错误。
+         * @param cursor - 上一次原生列表响应中的分页游标。
+         * @returns 原生分页响应的 HaiResult。
+         * @example
+         * ```ts
+         * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+         * const result = await connection.listSessions()
+         * ```
+         */
+        listSessions: (cursor) => protect(() => connection.listSessions(cursor)),
+        /**
+         * 按原生 ID 删除远端会话；不会删除框架数据库会话记录。
+         * @param id - 对端返回的原生会话 ID。
+         * @returns 原生删除响应的 HaiResult；不支持时返回协议错误。
+         * @example
+         * ```ts
+         * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+         * const result = await connection.deleteSession('native-id')
+         * ```
+         */
+        deleteSession: (id) => protect(() => connection.deleteSession(id)),
+        /**
+         * 关闭连接和拥有的子进程；不删除远端文件或持久状态。
+         * @returns 关闭完成的 HaiResult；可重复关闭。
+         * @example
+         * ```ts
+         * // connection/session 为已成功连接或创建的句柄，先检查 result.success。
+         * const result = await connection.close()
+         * ```
+         */
+        close: () => protect(async () => {
+          await connection.close();
+          connections.delete(connection);
+        })
+      };
+    }),
+    /**
+     * 关闭子系统及拥有的资源；由 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()
+     * ```
+     */
+    async close() {
+      closed = true;
+      await Promise.allSettled(
+        [...live.values()].map((value) => value.connection.cancel())
+      );
+      await Promise.allSettled(
+        [...connections].map((connection) => connection.close())
+      );
+      await Promise.allSettled([...pending]);
+      const results = await Promise.allSettled([...live.keys()].map(stop));
+      const more = await Promise.allSettled(
+        [...connections].map((connection) => connection.close())
+      );
+      connections.clear();
+      if ([...results, ...more].some((result) => result.status === "rejected"))
+        throw new ACPFailure("cleanup");
+    }
+  };
+  async function createGitOperationsInput(id, runtime) {
+    return createGitOperations(await getWorkspace(id), runtime).prepare();
+  }
+}
 var SENTENCE_BOUNDARY_REGEX = /[。！？；!?;\n]|\.(?=\s|$)/;
 async function* streamSentences(stream) {
   let buffer = "";
@@ -799,8 +3562,8 @@ async function describeHttpError(response) {
 }
 var logger3 = core.logger.child({ module: "ai", scope: "audio-ws" });
 function openAudioWebSocket(url, headers, options) {
-  return new Promise((resolve, reject) => {
-    const ws = new WebSocket(url, { headers, handshakeTimeout: options?.timeout ?? 15e3 });
+  return new Promise((resolve3, reject) => {
+    const ws = new WebSocket2(url, { headers, handshakeTimeout: options?.timeout ?? 15e3 });
     ws.binaryType = "arraybuffer";
     const queue = [];
     let waiting = null;
@@ -903,7 +3666,7 @@ function openAudioWebSocket(url, headers, options) {
           }
         }
       };
-      resolve(connection);
+      resolve3(connection);
     });
   });
 }
@@ -914,7 +3677,7 @@ var DOUBAO_CAPABILITIES = {
   transcribe: { supported: true, realtimeAudioInput: true, speechBoundaryEvents: false, streamingTranscriptOutput: true },
   synthesize: { supported: true, incrementalTextInput: true, streamingAudioOutput: true }
 };
-var PROTOCOL_VERSION = 1;
+var PROTOCOL_VERSION2 = 1;
 var HEADER_SIZE = 1;
 var MSG_FULL_CLIENT = 1;
 var MSG_AUDIO_ONLY_CLIENT = 2;
@@ -952,7 +3715,7 @@ var DOUBAO_FORMAT = {
 };
 function buildHeader(messageType, flags, serialization, compression) {
   return Buffer.from([
-    PROTOCOL_VERSION << 4 | HEADER_SIZE,
+    PROTOCOL_VERSION2 << 4 | HEADER_SIZE,
     messageType << 4 | flags,
     serialization << 4 | compression,
     0
@@ -1726,9 +4489,9 @@ function createOpenAIAudioProvider() {
     if (!model.apiKey)
       return err(HaiAIError.CONFIGURATION_ERROR, aiM("ai_audioMissingApiKey", { params: { provider: "openai" } }));
     try {
-      const client = createClient(model.apiKey, model.baseUrl, model.timeout);
+      const client2 = createClient(model.apiKey, model.baseUrl, model.timeout);
       const file = await toUploadFile(audio);
-      const result = await client.audio.transcriptions.create({
+      const result = await client2.audio.transcriptions.create({
         file,
         model: model.model,
         language,
@@ -1750,9 +4513,9 @@ function createOpenAIAudioProvider() {
         aiM("ai_audioUnsupportedInput", { params: { provider: "openai", reason: "streaming audio input" } })
       );
     }
-    const client = createClient(model.apiKey, model.baseUrl, model.timeout);
+    const client2 = createClient(model.apiKey, model.baseUrl, model.timeout);
     const file = await toUploadFile(audio);
-    const stream = await client.audio.transcriptions.create({
+    const stream = await client2.audio.transcriptions.create({
       file,
       model: model.model,
       language,
@@ -1775,8 +4538,8 @@ function createOpenAIAudioProvider() {
       return err(HaiAIError.CONFIGURATION_ERROR, aiM("ai_audioMissingApiKey", { params: { provider: "openai" } }));
     const out = resolveSynthesisOutput4({ format, sampleRate });
     try {
-      const client = createClient(model.apiKey, model.baseUrl, model.timeout);
-      const response = await client.audio.speech.create({
+      const client2 = createClient(model.apiKey, model.baseUrl, model.timeout);
+      const response = await client2.audio.speech.create({
         model: model.model,
         voice: voice ?? "alloy",
         input: text,
@@ -1795,12 +4558,12 @@ function createOpenAIAudioProvider() {
     if (!model.apiKey)
       throw audioError(HaiAIError.CONFIGURATION_ERROR, aiM("ai_audioMissingApiKey", { params: { provider: "openai" } }));
     const outFormat = resolveSynthesisOutput4({ format }).format;
-    const client = createClient(model.apiKey, model.baseUrl, model.timeout);
+    const client2 = createClient(model.apiKey, model.baseUrl, model.timeout);
     const segments = typeof text === "string" ? [text] : streamSentences(text);
     for await (const segment of segments) {
       if (!segment)
         continue;
-      const response = await client.audio.speech.create({
+      const response = await client2.audio.speech.create({
         model: model.model,
         voice: voice ?? "alloy",
         input: segment,
@@ -2854,12 +5617,12 @@ function createContextOperations(compressConfig, tokenOps, compressOps, contextS
       delete candidate.active;
     }
     async function waitForContext(signal) {
-      await new Promise((resolve, reject) => {
+      await new Promise((resolve3, reject) => {
         const timer = setTimeout(finish, 50);
         function finish() {
           clearTimeout(timer);
           signal?.removeEventListener("abort", abort);
-          resolve();
+          resolve3();
         }
         function abort() {
           clearTimeout(timer);
@@ -3579,7 +6342,7 @@ function createEmbeddingOperations(config) {
     const resolved = resolvedResult.data;
     const input = Array.isArray(request.input) ? request.input : [request.input];
     try {
-      const client = getOrCreateClient(resolved);
+      const client2 = getOrCreateClient(resolved);
       const params = {
         model: resolved.model,
         input
@@ -3587,7 +6350,7 @@ function createEmbeddingOperations(config) {
       if (request.dimensions ?? embeddingConfig.dimensions) {
         params.dimensions = request.dimensions ?? embeddingConfig.dimensions;
       }
-      const response = await client.embeddings.create(params);
+      const response = await client2.embeddings.create(params);
       return ok({
         model: response.model,
         data: response.data.map((item) => ({
@@ -5217,9 +7980,9 @@ ${contextText}
     async ingestFile(input) {
       try {
         const { readFile } = await import('fs/promises');
-        const { basename } = await import('path');
+        const { basename: basename2 } = await import('path');
         const content = await readFile(input.filePath, { encoding: input.encoding ?? "utf-8" });
-        const fileName = basename(input.filePath);
+        const fileName = basename2(input.filePath);
         const documentId = input.documentId ?? fileName;
         return this.ingest({
           documentId,
@@ -5294,13 +8057,13 @@ async function runWithCancellation(run, context) {
   const { signal } = context;
   if (signal.aborted)
     throw new DOMException("Aborted", "AbortError");
-  return await new Promise((resolve, reject) => {
+  return await new Promise((resolve3, reject) => {
     const onAbort = () => reject(new DOMException("Aborted", "AbortError"));
     signal.addEventListener("abort", onAbort, { once: true });
     Promise.resolve().then(() => run(context)).then(
       (value) => {
         signal.removeEventListener("abort", onAbort);
-        resolve(value);
+        resolve3(value);
       },
       (error) => {
         signal.removeEventListener("abort", onAbort);
@@ -5612,11 +8375,11 @@ function createAnthropicProvider(deps) {
   function resolveAnthropic(requestModel, tempModel) {
     const entry = requestModel ? config.llm.models?.find((m) => m.id === requestModel || m.model === requestModel) : void 0;
     const model = tempModel?.model ?? entry?.model ?? requestModel ?? config.llm.model ?? "claude-3-5-sonnet-latest";
-    const apiKey = tempModel?.apiKey ?? entry?.apiKey ?? config.llm.apiKey ?? (process.env.HAI_AI_LLM_APIKEY?.trim() || process.env.ANTHROPIC_API_KEY);
+    const apiKey = tempModel?.apiKey ?? entry?.apiKey ?? config.llm.apiKey ?? (process2.env.HAI_AI_LLM_APIKEY?.trim() || process2.env.ANTHROPIC_API_KEY);
     if (!apiKey)
       return err(HaiAIError.CONFIGURATION_ERROR, aiM("ai_configError", { params: { error: "API Key is required for Anthropic" } }));
-    const globalBaseUrl = config.llm.protocol === "anthropic" ? config.llm.baseUrl ?? (process.env.HAI_AI_LLM_BASEURL?.trim() || void 0) : void 0;
-    const baseUrl = (tempModel?.baseUrl ?? entry?.baseUrl ?? globalBaseUrl ?? process.env.ANTHROPIC_BASE_URL ?? DEFAULT_ANTHROPIC_BASE_URL).replace(/\/+$/, "");
+    const globalBaseUrl = config.llm.protocol === "anthropic" ? config.llm.baseUrl ?? (process2.env.HAI_AI_LLM_BASEURL?.trim() || void 0) : void 0;
+    const baseUrl = (tempModel?.baseUrl ?? entry?.baseUrl ?? globalBaseUrl ?? process2.env.ANTHROPIC_BASE_URL ?? DEFAULT_ANTHROPIC_BASE_URL).replace(/\/+$/, "");
     return ok({
       apiKey,
       baseUrl,
@@ -5926,12 +8689,12 @@ function createOpenAIProvider(deps) {
   const tempCacheTtl = config.llm.tempModelCacheTtl ?? 6e5;
   function getClient(apiKey, baseURL, timeout) {
     const key = `${apiKey}::${baseURL}::${timeout}`;
-    let client = clientCache.get(key);
-    if (!client) {
-      client = new OpenAI3({ apiKey, baseURL, timeout });
-      clientCache.set(key, client);
+    let client2 = clientCache.get(key);
+    if (!client2) {
+      client2 = new OpenAI3({ apiKey, baseURL, timeout });
+      clientCache.set(key, client2);
     }
-    return client;
+    return client2;
   }
   function getTempClient(apiKey, baseURL, timeout) {
     const now = Date.now();
@@ -5943,9 +8706,9 @@ function createOpenAIProvider(deps) {
     const cached = tempClientCache.get(key);
     if (cached)
       return cached.client;
-    const client = new OpenAI3({ apiKey, baseURL, timeout });
-    tempClientCache.set(key, { client, expiresAt: now + tempCacheTtl });
-    return client;
+    const client2 = new OpenAI3({ apiKey, baseURL, timeout });
+    tempClientCache.set(key, { client: client2, expiresAt: now + tempCacheTtl });
+    return client2;
   }
   function resolveClient(requestModel, tempModel) {
     if (tempModel)
@@ -5960,10 +8723,10 @@ function createOpenAIProvider(deps) {
     return ok({ client: getClient(apiKey ?? "", baseUrl ?? "https://api.openai.com/v1", timeout), model, protocol: resolvedApi });
   }
   function resolveTempClient(tempModel) {
-    const apiKey = tempModel.apiKey ?? config.llm.apiKey ?? (process.env.HAI_AI_LLM_APIKEY?.trim() || process.env.OPENAI_API_KEY);
+    const apiKey = tempModel.apiKey ?? config.llm.apiKey ?? (process2.env.HAI_AI_LLM_APIKEY?.trim() || process2.env.OPENAI_API_KEY);
     if (!apiKey)
       return err(HaiAIError.CONFIGURATION_ERROR, aiM("ai_configError", { params: { error: "API Key is required for temp model" } }));
-    const baseUrl = tempModel.baseUrl ?? config.llm.baseUrl ?? (process.env.HAI_AI_LLM_BASEURL?.trim() || process.env.OPENAI_BASE_URL) ?? "https://api.openai.com/v1";
+    const baseUrl = tempModel.baseUrl ?? config.llm.baseUrl ?? (process2.env.HAI_AI_LLM_BASEURL?.trim() || process2.env.OPENAI_BASE_URL) ?? "https://api.openai.com/v1";
     const timeout = tempModel.timeout ?? config.llm.timeout ?? 6e4;
     const api = (tempModel.protocol ?? config.llm.protocol) === "responses" ? "responses" : "chat";
     return ok({
@@ -5995,11 +8758,11 @@ function createOpenAIProvider(deps) {
       if (!clientResult.success)
         return clientResult;
       const resolved = clientResult.data;
-      const { client, model, maxTokens, temperature, protocol: api } = resolved;
+      const { client: client2, model, maxTokens, temperature, protocol: api } = resolved;
       const { objectId: _objectId, sessionId: _sessionId, tempModel: _tempModel, signal, ...openaiRequest } = request;
       try {
         if (api === "responses") {
-          const response2 = await client.responses.create(buildResponsesParams(request, resolved), { signal });
+          const response2 = await client2.responses.create(buildResponsesParams(request, resolved), { signal });
           return ok(responsesToChatResponse(response2, model));
         }
         const openaiMessages = request.messages.map(toOpenAIMessage);
@@ -6011,7 +8774,7 @@ function createOpenAIProvider(deps) {
           ...temperature !== void 0 && openaiRequest.temperature == null ? { temperature } : {},
           stream: false
         };
-        const response = signal ? await client.chat.completions.create(params, { signal }) : await client.chat.completions.create(params);
+        const response = signal ? await client2.chat.completions.create(params, { signal }) : await client2.chat.completions.create(params);
         return ok(response);
       } catch (error) {
         const mapped = toAIError(error);
@@ -6023,10 +8786,10 @@ function createOpenAIProvider(deps) {
       if (!clientResult.success)
         throw new Error(clientResult.error.message);
       const resolved = clientResult.data;
-      const { client, model, maxTokens, temperature, protocol: api } = resolved;
+      const { client: client2, model, maxTokens, temperature, protocol: api } = resolved;
       const { objectId: _objectId, sessionId: _sessionId, tempModel: _tempModel, signal, ...openaiRequest } = request;
       if (api === "responses") {
-        const responsesStream = await client.responses.create(
+        const responsesStream = await client2.responses.create(
           { ...buildResponsesParams(request, resolved), stream: true },
           { signal }
         );
@@ -6046,7 +8809,7 @@ function createOpenAIProvider(deps) {
         ...temperature !== void 0 && openaiRequest.temperature == null ? { temperature } : {},
         stream: true
       };
-      const stream = signal ? await client.chat.completions.create(params, { signal }) : await client.chat.completions.create(params);
+      const stream = signal ? await client2.chat.completions.create(params, { signal }) : await client2.chat.completions.create(params);
       for await (const chunk of stream) {
         yield chunk;
       }
@@ -6055,9 +8818,9 @@ function createOpenAIProvider(deps) {
       const clientResult = resolveClient();
       if (!clientResult.success)
         return clientResult;
-      const { client } = clientResult.data;
+      const { client: client2 } = clientResult.data;
       try {
-        const response = await client.models.list();
+        const response = await client2.models.list();
         const models = response.data.map((m) => m.id);
         return ok(models);
       } catch (error) {
@@ -6093,7 +8856,19 @@ function createLLMProvider(deps) {
 // src/llm/ai-llm-functions.ts
 var logger18 = core.logger.child({ module: "ai", scope: "llm" });
 function createAILLMFunctions(config, deps) {
-  const provider = createLLMProvider({ config });
+  let provider = createLLMProvider({ config });
+  let signature = JSON.stringify(config.llm);
+  async function currentProvider() {
+    if (!deps?.resolveConfig)
+      return provider;
+    const snapshot2 = await deps.resolveConfig();
+    const next = JSON.stringify(snapshot2.llm);
+    if (next !== signature) {
+      provider = createLLMProvider({ config: snapshot2 });
+      signature = next;
+    }
+    return provider;
+  }
   const recordStore = deps?.recordStore;
   const sessionStore = deps?.sessionStore;
   let recordSeq = 0;
@@ -6108,13 +8883,26 @@ function createAILLMFunctions(config, deps) {
     return "New Session";
   }
   async function saveRecordAndSession(record, messages) {
-    await recordStore.save(record.id, record, { objectId: record.objectId, sessionId: record.sessionId });
-    logger18.trace("Chat record saved", { id: record.id, objectId: record.objectId, sessionId: record.sessionId });
+    await recordStore.save(record.id, record, {
+      objectId: record.objectId,
+      sessionId: record.sessionId
+    });
+    logger18.trace("Chat record saved", {
+      id: record.id,
+      objectId: record.objectId,
+      sessionId: record.sessionId
+    });
     if (sessionStore) {
       await updateSessionInfo(sessionStore, record, (existing, now) => {
         if (existing?.deleted)
           return void 0;
-        return existing ? { ...existing, updatedAt: now } : { sessionId: record.sessionId, objectId: record.objectId, title: extractTitle(messages), createdAt: now, updatedAt: now };
+        return existing ? { ...existing, updatedAt: now } : {
+          sessionId: record.sessionId,
+          objectId: record.objectId,
+          title: extractTitle(messages),
+          createdAt: now,
+          updatedAt: now
+        };
       });
     }
   }
@@ -6122,9 +8910,20 @@ function createAILLMFunctions(config, deps) {
     if (request.tempModel && Object.hasOwn(request.tempModel, "api"))
       return err(HaiAIError.INVALID_REQUEST, aiM("ai_llmProtocolRenamed"));
     const start = Date.now();
-    const context = { model: request.model ?? request.tempModel?.model, messageCount: request.messages.length };
+    const context = {
+      model: request.model ?? request.tempModel?.model,
+      messageCount: request.messages.length
+    };
     logger18.debug("LLM chat started", context);
-    const result = await provider.chat(request);
+    let result;
+    try {
+      result = await (await currentProvider()).chat(request);
+    } catch {
+      return err(
+        HaiAIError.RESOURCE_OPERATION_FAILED,
+        aiM("ai_resourceOperationFailed")
+      );
+    }
     if (result.success) {
       logger18.info("LLM chat completed", {
         ...context,
@@ -6157,7 +8956,11 @@ function createAILLMFunctions(config, deps) {
             content: choice?.message?.content ?? "",
             toolCalls: choice?.message?.tool_calls,
             finishReason: choice?.finish_reason ?? "stop",
-            usage: response.usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
+            usage: response.usage ?? {
+              prompt_tokens: 0,
+              completion_tokens: 0,
+              total_tokens: 0
+            }
           },
           createdAt: Date.now(),
           duration: Date.now() - start
@@ -6173,7 +8976,10 @@ function createAILLMFunctions(config, deps) {
     if (request.tempModel && Object.hasOwn(request.tempModel, "api"))
       throw new Error(aiM("ai_llmProtocolRenamed"));
     const start = Date.now();
-    const logContext = { model: request.model ?? request.tempModel?.model, messageCount: request.messages.length };
+    const logContext = {
+      model: request.model ?? request.tempModel?.model,
+      messageCount: request.messages.length
+    };
     logger18.debug("LLM chat stream started", logContext);
     const shouldRecord = !!(request.objectId && recordStore && request.enablePersist !== false);
     let content = "";
@@ -6182,7 +8988,7 @@ function createAILLMFunctions(config, deps) {
     let streamId = "";
     let resolvedModel = request.model ?? request.tempModel?.model ?? "";
     try {
-      for await (const chunk of provider.chatStream(request)) {
+      for await (const chunk of (await currentProvider()).chatStream(request)) {
         yield chunk;
         if (!shouldRecord)
           continue;
@@ -6198,7 +9004,11 @@ function createAILLMFunctions(config, deps) {
           if (choice.delta.tool_calls) {
             for (const tc of choice.delta.tool_calls) {
               if (!toolCalls[tc.index]) {
-                toolCalls[tc.index] = { id: tc.id ?? "", type: "function", function: { name: tc.function?.name ?? "", arguments: "" } };
+                toolCalls[tc.index] = {
+                  id: tc.id ?? "",
+                  type: "function",
+                  function: { name: tc.function?.name ?? "", arguments: "" }
+                };
               }
               if (tc.function?.arguments)
                 toolCalls[tc.index].function.arguments += tc.function.arguments;
@@ -6218,12 +9028,20 @@ function createAILLMFunctions(config, deps) {
         finishReason
       });
     } catch (error) {
-      logger18.warn("LLM chat stream failed", { ...logContext, durationMs: Date.now() - start, error });
+      logger18.warn("LLM chat stream failed", {
+        ...logContext,
+        durationMs: Date.now() - start,
+        error
+      });
       throw error;
     }
     if (shouldRecord) {
       try {
-        const usage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+        const usage = {
+          prompt_tokens: 0,
+          completion_tokens: 0,
+          total_tokens: 0
+        };
         const record = {
           id: `${streamId || "stream"}_${Date.now()}_${recordSeq++}`,
           objectId: request.objectId,
@@ -6260,7 +9078,15 @@ function createAILLMFunctions(config, deps) {
       });
       return ok(records);
     } catch (error) {
-      return err(HaiAIError.LLM_HISTORY_FAILED, aiM("ai_llmHistoryFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
+      return err(
+        HaiAIError.LLM_HISTORY_FAILED,
+        aiM("ai_llmHistoryFailed", {
+          params: {
+            error: error instanceof Error ? error.message : String(error)
+          }
+        }),
+        error
+      );
     }
   }
   async function listSessions(objectId) {
@@ -6274,13 +9100,30 @@ function createAILLMFunctions(config, deps) {
       });
       return ok(sessions.filter((item) => !item.deleted));
     } catch (error) {
-      return err(HaiAIError.LLM_HISTORY_FAILED, aiM("ai_llmHistoryFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
+      return err(
+        HaiAIError.LLM_HISTORY_FAILED,
+        aiM("ai_llmHistoryFailed", {
+          params: {
+            error: error instanceof Error ? error.message : String(error)
+          }
+        }),
+        error
+      );
     }
   }
   const llm = {
     chat: chatWithRecord,
     chatStream: chatStreamWithRecord,
-    listModels: () => provider.listModels(),
+    listModels: async () => {
+      try {
+        return await (await currentProvider()).listModels();
+      } catch {
+        return err(
+          HaiAIError.RESOURCE_OPERATION_FAILED,
+          aiM("ai_resourceOperationFailed")
+        );
+      }
+    },
     getHistory,
     listSessions,
     async ask(question, options) {
@@ -6334,7 +9177,15 @@ function createAILLMFunctions(config, deps) {
       const maxRepairs = request.maxRepairs ?? 1;
       let lastError = "";
       for (let attempt = 0; attempt <= maxRepairs; attempt++) {
-        const messages = attempt === 0 ? baseMessages : [...baseMessages, { role: "user", content: aiM("ai_generateObjectRepair", { params: { error: lastError } }) }];
+        const messages = attempt === 0 ? baseMessages : [
+          ...baseMessages,
+          {
+            role: "user",
+            content: aiM("ai_generateObjectRepair", {
+              params: { error: lastError }
+            })
+          }
+        ];
         const result = await chatWithRecord({
           messages,
           model: request.model,
@@ -6342,7 +9193,10 @@ function createAILLMFunctions(config, deps) {
           tempModel: request.tempModel,
           enablePersist: false,
           signal: request.signal,
-          response_format: { type: "json_schema", json_schema: { name: schemaName, schema: jsonSchema, strict: true } }
+          response_format: {
+            type: "json_schema",
+            json_schema: { name: schemaName, schema: jsonSchema, strict: true }
+          }
         });
         if (!result.success)
           return result;
@@ -6360,7 +9214,12 @@ function createAILLMFunctions(config, deps) {
           return ok(validated.data);
         lastError = validated.error.message;
       }
-      return err(HaiAIError.INVALID_REQUEST, aiM("ai_generateObjectFailed", { params: { error: lastError || "unknown" } }));
+      return err(
+        HaiAIError.INVALID_REQUEST,
+        aiM("ai_generateObjectFailed", {
+          params: { error: lastError || "unknown" }
+        })
+      );
     }
   };
   const tools = {
@@ -6498,25 +9357,25 @@ function createAIMCPFunctions() {
     }
   };
 }
-function createScopedMemory(core33, binding) {
+function createScopedMemory(core32, binding) {
   const { objectId, scope } = binding;
   const accessScope = { objectId, scope };
   return {
-    extract: (messages, options) => core33.extract(messages, { ...options, objectId, scope }),
-    recall: (query, options) => core33.recall(query, { ...options, objectId, scope }),
-    injectMemories: (messages, options) => core33.injectMemories(messages, { ...options, objectId, scope }),
-    add: (entry) => core33.add({ ...entry, objectId, scope }),
-    update: (memoryId, updates) => core33.update(memoryId, updates, accessScope),
-    get: (memoryId) => core33.get(memoryId, accessScope),
-    remove: (memoryId) => core33.remove(memoryId, accessScope),
-    list: (options) => core33.list({ ...options, objectId, scope }),
-    listPage: (options) => core33.listPage({ ...options, objectId, scope }),
-    clear: (options) => core33.clear({ ...options, objectId, scope })
+    extract: (messages, options) => core32.extract(messages, { ...options, objectId, scope }),
+    recall: (query, options) => core32.recall(query, { ...options, objectId, scope }),
+    injectMemories: (messages, options) => core32.injectMemories(messages, { ...options, objectId, scope }),
+    add: (entry) => core32.add({ ...entry, objectId, scope }),
+    update: (memoryId, updates) => core32.update(memoryId, updates, accessScope),
+    get: (memoryId) => core32.get(memoryId, accessScope),
+    remove: (memoryId) => core32.remove(memoryId, accessScope),
+    list: (options) => core32.list({ ...options, objectId, scope }),
+    listPage: (options) => core32.listPage({ ...options, objectId, scope }),
+    clear: (options) => core32.clear({ ...options, objectId, scope })
   };
 }
-function createMemoryOperations(core33) {
+function createMemoryOperations(core32) {
   return {
-    ...core33,
+    ...core32,
     /**
      * 清空记忆（空过滤保护）。
      *
@@ -6528,15 +9387,15 @@ function createMemoryOperations(core33) {
       if (!hasFilter) {
         return err(HaiAIError.MEMORY_STORE_FAILED, aiM("ai_memoryClearRequiresFilter"));
       }
-      return core33.clear(options);
+      return core32.clear(options);
     },
-    scoped: (binding) => createScopedMemory(core33, binding),
+    scoped: (binding) => createScopedMemory(core32, binding),
     admin: {
       async clearAll(options) {
         if (options?.confirm !== true) {
           return err(HaiAIError.MEMORY_STORE_FAILED, aiM("ai_memoryClearAllUnconfirmed"));
         }
-        return core33.clear();
+        return core32.clear();
       }
     }
   };
@@ -6887,7 +9746,7 @@ function buildMem0Config(deps) {
   const vectorResolved = buildVectorStoreConfig(deps);
   if (!vectorResolved.success)
     return vectorResolved;
-  if (core.module.requiresSharedState(process.env) && !vectorResolved.data.persistent)
+  if (core.module.requiresSharedState(process2.env) && !vectorResolved.data.persistent)
     return err(HaiAIError.CONFIGURATION_ERROR, aiM("ai_memorySharedBackendRequired"));
   return ok({
     vectorProvider: vectorResolved.data.provider,
@@ -7099,16 +9958,16 @@ async function createMem0OssMemoryOperations(deps) {
     const sdk = await import('@qdrant/js-client-rest').catch(() => void 0);
     if (sdk && typeof sdk.QdrantClient?.prototype?.search === "function") {
       const url = deps.vectorBackend?.url ?? "";
-      const client = new sdk.QdrantClient({
+      const client2 = new sdk.QdrantClient({
         url,
         port: Number(new URL(url).port) || 6333,
         apiKey: deps.vectorBackend?.apiKey
       });
-      const upsert = client.upsert.bind(client);
-      const remove = client.delete.bind(client);
-      client.upsert = (collection, options) => upsert(collection, { ...options, wait: true });
-      client.delete = (collection, options) => remove(collection, { ...options, wait: true });
-      configResult.data.config.vectorStore.config.client = client;
+      const upsert = client2.upsert.bind(client2);
+      const remove = client2.delete.bind(client2);
+      client2.upsert = (collection, options) => upsert(collection, { ...options, wait: true });
+      client2.delete = (collection, options) => remove(collection, { ...options, wait: true });
+      configResult.data.config.vectorStore.config.client = client2;
     } else {
       const failure = err(HaiAIError.CONFIGURATION_ERROR, aiM("ai_memoryBackendSdkIncompatible"));
       if (!failure.success)
@@ -8451,7 +11310,7 @@ function createRerankOperations(config) {
   };
 }
 var logger28 = core.logger.child({ module: "ai", scope: "retrieval" });
-function createRetrievalOperations(embeddingOps, storeProvider, sourceStore, rerankOps) {
+function createRetrievalOperations(embeddingOps, storeProvider, sourceStore, rerankOps, registry) {
   const vectorStoreCache = /* @__PURE__ */ new Map();
   function getVectorStore(collection) {
     let store = vectorStoreCache.get(collection);
@@ -8472,6 +11331,10 @@ function createRetrievalOperations(embeddingOps, storeProvider, sourceStore, rer
      * @returns `ok(undefined)` 注册成功；`err` 含错误码 `RETRIEVAL_FAILED`（重复注册）
      */
     async addSource(source) {
+      if (registry) {
+        const result = await registry.operations.register(source);
+        return result.success ? ok(void 0) : result;
+      }
       const existing = await sourceStore.get(source.id);
       if (existing) {
         return err(HaiAIError.RETRIEVAL_FAILED, aiM("ai_internalError", { params: { error: `Source '${source.id}' already exists` } }));
@@ -8489,6 +11352,8 @@ function createRetrievalOperations(embeddingOps, storeProvider, sourceStore, rer
      * @returns `ok(undefined)` 删除成功；`err` 含错误码 `RETRIEVAL_SOURCE_NOT_FOUND`
      */
     async removeSource(sourceId) {
+      if (registry)
+        return registry.operations.remove(sourceId);
       const existing = await sourceStore.get(sourceId);
       if (!existing) {
         return err(HaiAIError.RETRIEVAL_SOURCE_NOT_FOUND, aiM("ai_internalError", { params: { error: `Source '${sourceId}' not found` } }));
@@ -8503,7 +11368,7 @@ function createRetrievalOperations(embeddingOps, storeProvider, sourceStore, rer
      * @returns 全部检索源数组（无源时返回空数组）
      */
     async listSources() {
-      return sourceStore.query({});
+      return registry ? registry.values() : sourceStore.query({});
     },
     /**
      * 执行向量检索
@@ -8518,13 +11383,13 @@ function createRetrievalOperations(embeddingOps, storeProvider, sourceStore, rer
      */
     async retrieve(request) {
       const startTime = Date.now();
-      const targetSources = await sourceStore.query(
-        request.sources?.length ? { where: { id: { $in: request.sources } } } : {}
-      );
-      if (targetSources.length === 0) {
-        return err(HaiAIError.RETRIEVAL_SOURCE_NOT_FOUND, aiM("ai_internalError", { params: { error: "No retrieval sources configured" } }));
-      }
       try {
+        const targetSources = registry ? (await registry.values()).filter((source) => !request.sources?.length || request.sources.includes(source.id)) : await sourceStore.query(
+          request.sources?.length ? { where: { id: { $in: request.sources } } } : {}
+        );
+        if (targetSources.length === 0) {
+          return err(HaiAIError.RETRIEVAL_SOURCE_NOT_FOUND, aiM("ai_internalError", { params: { error: "No retrieval sources configured" } }));
+        }
         const embedResult = await embeddingOps.embedText(request.query);
         if (!embedResult.success) {
           return err(HaiAIError.RETRIEVAL_FAILED, aiM("ai_internalError", { params: { error: "Failed to embed query" } }), embedResult.error);
@@ -8703,38 +11568,207 @@ function createTokenOperations(config) {
 }
 
 // src/ai-functions.ts
-var logger30 = core.logger.child({ module: "ai", scope: "functions" });
 async function createAISubsystems(config, deps) {
   const { storeProvider, datapipe: datapipeDep } = deps;
   const memoryParsed = MemoryConfigSchema.parse(config.memory ?? {});
   const useMem0Oss = memoryParsed.provider === "mem0";
-  const chatRecordStore = storeProvider.createRelStore("hai_ai_chat_records", { hasObjectId: true, hasSessionId: true });
-  const sessionStore = storeProvider.createRelStore("hai_ai_sessions", { hasObjectId: true });
-  const sourceStore = storeProvider.createRelStore("hai_ai_retrieval_sources");
-  const memoryStore = useMem0Oss ? null : storeProvider.createRelStore("hai_ai_memory", { hasObjectId: true, hasScopeIndex: true });
-  const contextStore = storeProvider.createRelStore("hai_ai_context", { hasObjectId: true, hasSessionId: true });
-  const personaStore = storeProvider.createRelStore("hai_ai_persona", { hasObjectId: true });
+  const chatRecordStore = storeProvider.createRelStore(
+    "hai_ai_chat_records",
+    { hasObjectId: true, hasSessionId: true }
+  );
+  const sessionStore = storeProvider.createRelStore(
+    "hai_ai_sessions",
+    { hasObjectId: true }
+  );
+  const sourceStore = storeProvider.createRelStore(
+    "hai_ai_retrieval_sources"
+  );
+  const memoryStore = useMem0Oss ? null : storeProvider.createRelStore("hai_ai_memory", {
+    hasObjectId: true,
+    hasScopeIndex: true
+  });
+  const contextStore = storeProvider.createRelStore(
+    "hai_ai_context",
+    { hasObjectId: true, hasSessionId: true }
+  );
+  const personaStore = storeProvider.createRelStore(
+    "hai_ai_persona",
+    { hasObjectId: true }
+  );
   const a2aStores = config.a2a ? createA2AStores(storeProvider) : null;
   const memoryVectorStore = useMem0Oss ? null : storeProvider.createVectorStore("hai_ai_memory_vectors");
+  let registriesOpen = true;
+  const isOpen = () => registriesOpen;
+  const llmModels = createResourceRegistry(
+    storeProvider.createRelStore("hai_ai_llm_models"),
+    ModelEntrySchema,
+    config.llm.models ?? [],
+    isOpen
+  );
+  const audioModels = createResourceRegistry(
+    storeProvider.createRelStore("hai_ai_audio_models"),
+    AudioModelEntrySchema,
+    config.audio?.models ?? [],
+    isOpen
+  );
+  const imageModels = createResourceRegistry(
+    storeProvider.createRelStore("hai_ai_image_models"),
+    ImageModelEntrySchema,
+    config.image?.models ?? [],
+    isOpen
+  );
+  const mcpServers = createResourceRegistry(
+    storeProvider.createRelStore("hai_ai_mcp_servers"),
+    MCPExternalServerSchema,
+    config.mcp?.servers ?? [],
+    isOpen
+  );
+  const retrievalSources = createResourceRegistry(
+    sourceStore,
+    RetrievalSourceSchema,
+    config.retrieval?.sources ?? [],
+    isOpen
+  );
+  async function llmConfig() {
+    return {
+      ...config,
+      llm: { ...config.llm, models: await llmModels.values() }
+    };
+  }
+  async function audioConfig() {
+    return {
+      ...config,
+      audio: AudioConfigSchema.parse({
+        ...config.audio,
+        models: await audioModels.values()
+      })
+    };
+  }
+  async function imageConfig() {
+    return {
+      ...config,
+      image: ImageConfigSchema.parse({
+        ...config.image,
+        models: await imageModels.values()
+      })
+    };
+  }
+  async function mcpLookup(ids) {
+    const servers = [];
+    for (const id of ids) {
+      const entry = await mcpServers.read(id);
+      if (!entry)
+        throw new Error("MCP resource missing");
+      const server = entry.value;
+      if (server.transport === "stdio") {
+        servers.push({
+          name: server.name,
+          command: server.command,
+          args: server.args,
+          env: Object.entries(resolveEnvironment(server.environmentRefs)).map(
+            ([name, value]) => ({ name, value })
+          )
+        });
+      } else {
+        servers.push({
+          type: server.transport,
+          name: server.name,
+          url: server.url,
+          headers: Object.entries(resolveEnvironment(server.headerEnv)).map(
+            ([name, value]) => ({ name, value })
+          )
+        });
+      }
+    }
+    return servers;
+  }
+  const acp = createACPOperations(
+    storeProvider,
+    config,
+    deps.acpAdapters,
+    llmConfig,
+    mcpLookup
+  );
   await storeProvider.initialize();
-  const llmFunctions = createAILLMFunctions(config, { recordStore: chatRecordStore, sessionStore });
-  const llm = llmFunctions.llm;
-  const mcp = createAIMCPFunctions();
-  const embedding = createEmbeddingOperations(config);
-  const reasoning = createReasoningOperations(config, llm);
-  const rerank = createRerankOperations(config);
-  const retrieval = createRetrievalOperations(embedding, storeProvider, sourceStore, rerank);
-  if (config.retrieval?.sources?.length) {
-    const configSources = RetrievalConfigSchema.parse(config.retrieval).sources ?? [];
-    sourceStore.saveMany(configSources.map((s) => ({ id: s.id, data: s }))).catch((e) => logger30.warn("Failed to pre-register retrieval sources", { error: e }));
+  const llmFunctions = createAILLMFunctions(config, {
+    recordStore: chatRecordStore,
+    sessionStore,
+    resolveConfig: llmConfig
+  });
+  const llm = Object.assign(llmFunctions.llm, {
+    models: llmModels.operations
+  });
+  const mcp = Object.assign(createAIMCPFunctions(), {
+    servers: mcpServers.operations
+  });
+  async function resourceCall(operation) {
+    try {
+      return await operation();
+    } catch {
+      return err(
+        HaiAIError.RESOURCE_OPERATION_FAILED,
+        aiM("ai_resourceOperationFailed")
+      );
+    }
   }
+  const embedding = {
+    embed: (request) => resourceCall(
+      async () => createEmbeddingOperations(await llmConfig()).embed(request)
+    ),
+    embedText: (text) => resourceCall(
+      async () => createEmbeddingOperations(await llmConfig()).embedText(text)
+    ),
+    embedBatch: (texts) => resourceCall(
+      async () => createEmbeddingOperations(await llmConfig()).embedBatch(texts)
+    )
+  };
+  const reasoning = {
+    run: (query, options) => resourceCall(async () => createReasoningOperations(await llmConfig(), llm).run(query, options)),
+    async *runStream(query, options) {
+      yield* createReasoningOperations(await llmConfig(), llm).runStream(query, options);
+    }
+  };
+  const rerank = {
+    rerank: (request) => resourceCall(
+      async () => createRerankOperations(await llmConfig()).rerank(request)
+    ),
+    rerankTexts: (query, texts, topN) => resourceCall(
+      async () => createRerankOperations(await llmConfig()).rerankTexts(
+        query,
+        texts,
+        topN
+      )
+    )
+  };
+  const retrieval = Object.assign(
+    createRetrievalOperations(
+      embedding,
+      storeProvider,
+      sourceStore,
+      rerank,
+      retrievalSources
+    ),
+    { sources: retrievalSources.operations }
+  );
   const rag = createRagOperations(llm, retrieval);
   const knowledgeParsed = KnowledgeConfigSchema.parse(config.knowledge ?? {});
   const knowledgeStore = storeProvider.createKnowledgeStore?.();
-  const knowledge = createKnowledgeOperations(knowledgeParsed, llm, embedding, datapipeDep, knowledgeStore);
-  const memoryCore = memoryStore && memoryVectorStore ? createNativeMemoryOperations(memoryParsed, llm, embedding, memoryStore, memoryVectorStore) : await createMem0OssMemoryOperations({
+  const knowledge = createKnowledgeOperations(
+    knowledgeParsed,
+    llm,
+    embedding,
+    datapipeDep,
+    knowledgeStore
+  );
+  const memoryCore = memoryStore && memoryVectorStore ? createNativeMemoryOperations(
+    memoryParsed,
+    llm,
+    embedding,
+    memoryStore,
+    memoryVectorStore
+  ) : await createMem0OssMemoryOperations({
     config: memoryParsed,
-    aiConfig: config,
+    aiConfig: await llmConfig(),
     llm,
     collectionName: "hai_ai_memory",
     embeddingDims: config.embedding?.dimensions,
@@ -8745,20 +11779,109 @@ async function createAISubsystems(config, deps) {
   const summaryParsed = SummaryConfigSchema.parse(config.summary ?? {});
   const compressParsed = CompressConfigSchema.parse(config.compress ?? {});
   const token = createTokenOperations(tokenParsed);
-  const summary = createSummaryOperations(config.llm, llm, token, summaryParsed);
-  const compress = createCompressOperations(compressParsed, token, summary, config.llm.maxTokens ?? 4096);
-  const context = createContextOperations(compressParsed, token, compress, contextStore, sessionStore, {
-    llm,
-    memory: memory ?? void 0,
-    rag: rag ?? void 0,
-    reasoning: reasoning ?? void 0,
-    summary
-  });
+  const summary = {
+    generate: (messages, options) => resourceCall(async () => createSummaryOperations((await llmConfig()).llm, llm, token, summaryParsed).generate(messages, options)),
+    summarize: (messages, options) => resourceCall(async () => createSummaryOperations((await llmConfig()).llm, llm, token, summaryParsed).summarize(messages, options))
+  };
+  const compress = createCompressOperations(
+    compressParsed,
+    token,
+    summary,
+    config.llm.maxTokens ?? 4096
+  );
+  const context = createContextOperations(
+    compressParsed,
+    token,
+    compress,
+    contextStore,
+    sessionStore,
+    {
+      llm,
+      memory: memory ?? void 0,
+      rag: rag ?? void 0,
+      reasoning: reasoning ?? void 0,
+      summary
+    }
+  );
   const persona = createPersonaOperations(personaStore);
-  const file = createFileOperations(config, llm);
-  const audio = createAudioOperations(config);
-  const image = createImageOperations(config);
-  return { a2aStores, llm, mcp, embedding, reasoning, rerank, retrieval, rag, knowledge, memory, persona, token, summary, compress, context, file, audio, image };
+  const file = {
+    parse: (request) => resourceCall(async () => createFileOperations(await llmConfig(), llm).parse(request)),
+    parseText: (content, filename) => resourceCall(async () => createFileOperations(await llmConfig(), llm).parseText(content, filename))
+  };
+  let audioSnapshot = createAudioOperations(await audioConfig());
+  async function currentAudio2() {
+    audioSnapshot = createAudioOperations(await audioConfig());
+    return audioSnapshot;
+  }
+  const audio = {
+    models: {
+      list: () => resourceCall(async () => {
+        await currentAudio2();
+        return audioModels.operations.list();
+      }),
+      get: (id) => resourceCall(async () => {
+        await currentAudio2();
+        return audioModels.operations.get(id);
+      }),
+      register: (input) => resourceCall(async () => {
+        const result = await audioModels.operations.register(input);
+        if (result.success)
+          await currentAudio2();
+        return result;
+      }),
+      update: (input, version) => resourceCall(async () => {
+        const result = await audioModels.operations.update(input, version);
+        if (result.success)
+          await currentAudio2();
+        return result;
+      }),
+      remove: (id, version) => resourceCall(async () => {
+        const result = await audioModels.operations.remove(id, version);
+        if (result.success)
+          await currentAudio2();
+        return result;
+      })
+    },
+    transcribe: (request) => resourceCall(async () => (await currentAudio2()).transcribe(request)),
+    synthesize: (request) => resourceCall(async () => (await currentAudio2()).synthesize(request)),
+    async *transcribeStream(request) {
+      yield* (await currentAudio2()).transcribeStream(request);
+    },
+    async *synthesizeStream(request) {
+      yield* (await currentAudio2()).synthesizeStream(request);
+    },
+    getCapabilities: (request) => audioSnapshot.getCapabilities(request)
+  };
+  const image = {
+    models: imageModels.operations,
+    generate: (request) => resourceCall(
+      async () => createImageOperations(await imageConfig()).generate(request)
+    )
+  };
+  return {
+    closeRegistries: () => {
+      registriesOpen = false;
+    },
+    a2aStores,
+    llm,
+    acp,
+    mcp,
+    embedding,
+    reasoning,
+    rerank,
+    retrieval,
+    rag,
+    knowledge,
+    memory,
+    persona,
+    token,
+    summary,
+    compress,
+    context,
+    file,
+    audio,
+    image
+  };
 }
 var WRITE_LEASE_MS = 3e5;
 var CAS_ATTEMPTS = 12;
@@ -9077,7 +12200,7 @@ function documentInfo(document) {
 }
 
 // src/store/providers/ai-store-provider-db.ts
-var logger31 = core.logger.child({ module: "ai", scope: "store-provider-db" });
+var logger30 = core.logger.child({ module: "ai", scope: "store-provider-db" });
 function requireSqlSuccess(result) {
   if (!result.success)
     throw new Error(result.error.message, { cause: result.error });
@@ -9596,7 +12719,7 @@ function createDbStoreProvider(deps) {
           if (result.status === "rejected")
             throw result.reason;
         }
-        logger31.debug("DB store provider initialized", { tableCount: relStores.size });
+        logger30.debug("DB store provider initialized", { tableCount: relStores.size });
       }
     },
     async close() {
@@ -9827,10 +12950,11 @@ function createMemoryStoreProvider() {
 }
 
 // src/ai-main.ts
-var logger32 = core.logger.child({ module: "ai", scope: "main" });
+var logger31 = core.logger.child({ module: "ai", scope: "main" });
 var initInProgress = false;
 var currentConfig = null;
 var currentLLM = null;
+var currentACP = null;
 var currentMCP = null;
 var currentEmbedding = null;
 var currentReasoning = null;
@@ -9850,12 +12974,14 @@ var currentImage = null;
 var currentA2AConfig;
 var currentA2AImpl = null;
 var currentA2AStores = null;
+var currentRegistriesClose = null;
 var currentStoreProvider = null;
 var notInitialized = core.module.createNotInitializedKit(
   HaiAIError.NOT_INITIALIZED,
   () => aiM("ai_notInitialized")
 );
 var notInitializedLLM = {
+  models: notInitialized.proxy(),
   chat: () => Promise.resolve(notInitialized.result()),
   async *chatStream() {
     throw notInitialized.error();
@@ -9869,7 +12995,16 @@ var notInitializedLLM = {
   },
   generateObject: () => Promise.resolve(notInitialized.result())
 };
+var notInitializedACP = {
+  agents: notInitialized.proxy(),
+  sessions: notInitialized.proxy(),
+  workspaces: notInitialized.proxy(),
+  connect: () => Promise.resolve(notInitialized.result()),
+  close: async () => {
+  }
+};
 var notInitializedMCP = {
+  servers: notInitialized.proxy(),
   registerTool: () => notInitialized.result(),
   registerResource: () => notInitialized.result(),
   registerPrompt: () => notInitialized.result(),
@@ -9885,6 +13020,7 @@ var notInitializedReasoning = {
   }
 };
 var notInitializedRetrieval = {
+  sources: notInitialized.proxy(),
   addSource: () => Promise.resolve(notInitialized.result()),
   removeSource: () => Promise.resolve(notInitialized.result()),
   listSources: () => Promise.resolve([]),
@@ -9919,6 +13055,7 @@ var notInitializedContext = {
 var notInitializedRerank = notInitialized.proxy();
 var notInitializedFile = notInitialized.proxy();
 var notInitializedAudio = {
+  models: notInitialized.proxy(),
   transcribe: () => Promise.resolve(notInitialized.result()),
   async *transcribeStream() {
     throw notInitialized.error();
@@ -9930,6 +13067,7 @@ var notInitializedAudio = {
   getCapabilities: () => notInitialized.result()
 };
 var notInitializedImage = {
+  models: notInitialized.proxy(),
   generate: () => Promise.resolve(notInitialized.result())
 };
 var a2aLazyOperations = createA2ALazyProxy({
@@ -9945,7 +13083,11 @@ var a2aLazyOperations = createA2ALazyProxy({
 async function resetAllState() {
   const storeProvider = currentStoreProvider;
   await currentA2AImpl?.close();
+  await currentACP?.close();
   currentLLM = null;
+  currentRegistriesClose?.();
+  currentRegistriesClose = null;
+  currentACP = null;
   currentMCP = null;
   currentEmbedding = null;
   currentReasoning = null;
@@ -9971,7 +13113,7 @@ async function resetAllState() {
     try {
       await storeProvider.close();
     } catch (error) {
-      logger32.error("AI store provider close failed", { error });
+      logger31.error("AI store provider close failed", { error });
     }
   }
 }
@@ -9987,22 +13129,25 @@ var streamOperations = {
 };
 var ai = {
   async init(config, options) {
-    if (Object.keys(process.env).some((name) => /^HAI_AI_LLM_(?:MODELS_\d+_)?API$/.test(name)))
+    if (Object.keys(process2.env).some((name) => /^HAI_AI_LLM_(?:MODELS_\d+_)?API$/.test(name)))
       return err(HaiAIError.CONFIGURATION_ERROR, aiM("ai_llmProtocolRenamed"));
     if (initInProgress) {
-      logger32.warn("AI init already in progress, skipping concurrent call");
+      logger31.warn("AI init already in progress, skipping concurrent call");
       return err(HaiAIError.INIT_IN_PROGRESS, aiM("ai_initInProgress"));
     }
     initInProgress = true;
+    let closingPrevious = false;
     try {
       if (currentConfig) {
-        logger32.warn("AI module is already initialized, reinitializing");
+        logger31.warn("AI module is already initialized, reinitializing");
+        closingPrevious = true;
         await ai.close();
+        closingPrevious = false;
       }
-      logger32.info("Initializing AI module");
+      logger31.info("Initializing AI module");
       const parseResult = AIConfigSchema.safeParse(config ?? {});
       if (!parseResult.success) {
-        logger32.error("AI config validation failed", { error: parseResult.error.message });
+        logger31.error("AI config validation failed", { error: parseResult.error.message });
         return err(
           HaiAIError.CONFIGURATION_ERROR,
           aiM("ai_configError", { params: { error: parseResult.error.message } }),
@@ -10017,16 +13162,19 @@ var ai = {
         storeProvider = createDbStoreProviderFromModules();
       } else {
         storeProvider = createMemoryStoreProvider();
-        logger32.warn("AI is using the ephemeral in-memory store; initialize reldb and vecdb before ai.init() for persistent data");
+        logger31.warn("AI is using the ephemeral in-memory store; initialize reldb and vecdb before ai.init() for persistent data");
       }
-      if (core.module.requiresSharedState(process.env) && storeProvider.stateScope !== "shared")
+      if (core.module.requiresSharedState(process2.env) && storeProvider.stateScope !== "shared")
         return err(HaiAIError.CONFIGURATION_ERROR, aiM("ai_sharedBackendRequired"));
       currentStoreProvider = storeProvider;
       const subs = await createAISubsystems(parsed, {
         storeProvider,
-        datapipe
+        datapipe,
+        acpAdapters: options?.acpAdapters
       });
+      currentRegistriesClose = subs.closeRegistries;
       currentLLM = subs.llm;
+      currentACP = subs.acp;
       currentMCP = subs.mcp;
       currentEmbedding = subs.embedding;
       currentReasoning = subs.reasoning;
@@ -10046,11 +13194,17 @@ var ai = {
       currentA2AConfig = parsed.a2a;
       currentA2AStores = subs.a2aStores;
       currentConfig = parsed;
-      logger32.info("AI module initialized", { model: parsed.llm?.model });
+      logger31.info("AI module initialized", { model: parsed.llm?.model });
       return ok(void 0);
     } catch (error) {
-      await resetAllState();
-      logger32.error("AI module initialization failed", { error });
+      if (!closingPrevious) {
+        try {
+          await resetAllState();
+        } catch (cleanupError) {
+          logger31.error("AI initialization cleanup failed", { error: cleanupError });
+        }
+      }
+      logger31.error("AI module initialization failed", { error });
       return err(
         HaiAIError.CONFIGURATION_ERROR,
         aiM("ai_initFailed", {
@@ -10065,6 +13219,9 @@ var ai = {
   get llm() {
     return currentLLM ?? notInitializedLLM;
   },
+  get acp() {
+    return currentACP ?? notInitializedACP;
+  },
   get mcp() {
     return currentMCP ?? notInitializedMCP;
   },
@@ -10130,12 +13287,12 @@ var ai = {
   },
   async close() {
     if (!currentConfig) {
-      logger32.info("AI module already closed, skipping");
+      logger31.info("AI module already closed, skipping");
       return;
     }
-    logger32.info("Closing AI module");
+    logger31.info("Closing AI module");
     await resetAllState();
-    logger32.info("AI module closed");
+    logger31.info("AI module closed");
   }
 };
 function createMcpServer(options) {