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

package/README.en.md

@@ -146,17 +146,17 @@ const controller = new AbortController()
 const cancellable = ai.llm.chat({ messages, signal: controller.signal })
 // controller.abort()
 
-// 多协议：模型的 api 决定底层走 Chat Completions / Responses / Anthropic，公共请求响应形状不变
+// 多协议：模型的 protocol 决定底层走 Chat Completions / Responses / Anthropic，公共请求响应形状不变
 // - chat（默认）：OpenAI Chat Completions（兼容绝大多数厂商）
 // - responses：OpenAI Responses API（/v1/responses）
 // - anthropic：Anthropic Messages API（Claude 原生协议，环境变量 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL）
-const claude = await ai.llm.chat({ messages, model: 'claude' }) // 该模型配置 api: anthropic
+const claude = await ai.llm.chat({ messages, model: 'claude' }) // 该模型配置 protocol: anthropic
 
 // 临时模型：单次请求绕过配置注册模型，直接指定端点与凭据（chat/chatStream/ask/askStream 均支持）
 // 临时客户端按 TTL 缓存（llm.tempModelCacheTtl，默认 10 分钟），与常驻模型客户端隔离
 const temp = await ai.llm.chat({
   messages,
-  tempModel: { model: 'claude-3-5-sonnet', api: 'anthropic', apiKey: 'sk-temp' },
+  tempModel: { model: 'claude-3-5-sonnet', protocol: 'anthropic', apiKey: 'sk-temp' },
 })
 ```
 
@@ -194,6 +194,31 @@ const batch = await registry.executeAll(toolCalls)
 const chat = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
 ```
 
+#### ACP agents, workspaces and sessions
+
+`ai.acp` runs on Node: `embedded` starts a local process, `builtin-service` starts a Podman/Docker container (ready Podman first), and `custom-service` connects to a native HTTP/WS ACP service. Codex/dsh use stdio; unsupported transports are not silently bridged.
+
+Podman does not inherit proxy variables from its remote service. Configure proxies explicitly through agent/workspace `environmentRefs`, using addresses reachable from the container.
+
+The Goose 1.57.0 image exposes its native `goose serve` HTTP/WS `/acp` service through custom-service with `X-Secret-Key`. Goose manages its models; deployment owns workspace/state volumes. Real remote E2E verifies native resume when advertised.
+
+- `agents.register/get/list/update/remove/initialize/check` manage definitions. The `codex` and `deepseek-harness` adapters reference `llm.models`; use `generic` or trusted `AIInitOptions.acpAdapters` for other agents. External services own their models.
+- `workspaces.register/prepare/importFiles` manage directories or persistent volumes, multiple Git repositories and plain files. Every repository requires `mainBranch`; prepare preserves dirty directories.
+- `sessions.create/resume/get/list/close` manage native sessions. `newWorktree: true` creates matching branches from each committed local main branch. Prompt, stream, strict structured output, permission callbacks, MCP, configuration and cancellation use native ACP capabilities.
+- `session.updateMain()` fetches and fast-forwards configured main branches. `publish({ mode: 'merge-main' | 'push-branch', message, author })` publishes managed isolated sessions only, with per-repository partial-failure reports and no force push. Both stop execution first; resume explicitly to continue.
+
+Declare verified capacity, modalities and reasoning in `llm.models[].capabilities`. Codex needs native Responses; the existing Hai adapter is not a reverse gateway. Code and state persist after close. CAS ownership is released only after owned processes stop; worktrees are not security sandboxes.
+
+See the [ACP guide](../cli/templates/skills/hai-ai/acp.md) and [agent images](models/agents/README.md). Images include Git/Node/Python, optional Java/Rust/Go, and both codex-acp and codex in the Codex image. Errors use `hai:ai:070`–`084`; ordinary methods return HaiResult, while stream failures throw.
+
+Managed Git rejects submodules and Git LFS attributes with ACP_UNSUPPORTED instead of reporting incomplete checkouts as ready.
+
+#### Configuration and database resource catalogs
+
+`llm.models`, `audio.models`, `image.models`, `mcp.servers`, `retrieval.sources`, and `acp.agents/workspaces` merge configuration and database entries. Configuration wins duplicate IDs and is read-only. Database entries support list/get/register/update/remove with value/source/version metadata and optional version checks. Async calls read current definitions; synchronous audio capability checks use the latest local snapshot. Catalog errors use 090–094. Definitions may contain model credentials; expose only authorized, selected fields.
+
+[Resource catalogs](../cli/templates/skills/hai-ai/resources.md) · [ACP](../cli/templates/skills/hai-ai/acp.md)
+
 #### A2A protocol boundaries
 
 `ai.a2a.getAgentCard()` returns a complete A2A 0.3 Agent Card with `protocolVersion`, MIME, and streaming capabilities. Kit discovery defaults to `/.well-known/agent-card.json`. `handleRequest()` always returns JSON-RPC/SSE results; uninitialized calls return JSON-RPC errors. Trusted HTTP `agentId` maps to executor `context.user.userName`. JSON-RPC/SSE are supported; push notifications, gRPC, and REST are not claimed. Applications remain responsible for business resource authorization.
@@ -516,18 +541,22 @@ const manager = ai.context.createManager({
 
 ### Configuration
 
+Rerank inherits the global LLM timeout with per-model overrides; the deadline covers the request and response body, returning RERANK_API_ERROR on timeout.
+
+The LLM protocol field is now `protocol` in `llm`, `llm.models[]`, and `tempModel`, replacing `api`. Values remain `chat | responses | anthropic`. Use `HAI_AI_LLM_PROTOCOL` and `HAI_AI_LLM_MODELS_0_PROTOCOL` (adjust the index for other entries). Old fields and protocol variables fail with a migration message; `apiKey` and its variables are unchanged.
+
 ```yaml
 llm:
   apiKey: ''
   baseUrl: https://api.openai.com/v1
   model: gpt-4o-mini
-  api: chat # chat（默认）| responses | anthropic —— 底层 API 协议，对使用方透明
+  protocol: chat # chat（默认）| responses | anthropic —— 底层 API 协议，对使用方透明
   timeout: 60000
   tempModelCacheTtl: 600000 # 临时模型客户端缓存 TTL（毫秒，默认 10 分钟）
   models: # 可为每个模型单独指定协议
     - {id: fast, model: gpt-4o-mini}
-    - {id: strong, model: gpt-4.1, api: responses}
-    - {id: claude, model: claude-3-5-sonnet-latest, api: anthropic}
+    - {id: strong, model: gpt-4.1, protocol: responses}
+    - {id: claude, model: claude-3-5-sonnet-latest, protocol: anthropic}
   scenarios:
     chat: fast
     reasoning: strong

package/README.ja.md

@@ -146,17 +146,17 @@ const controller = new AbortController()
 const cancellable = ai.llm.chat({ messages, signal: controller.signal })
 // controller.abort()
 
-// 多协议：模型的 api 决定底层走 Chat Completions / Responses / Anthropic，公共请求响应形状不变
+// 多协议：模型的 protocol 决定底层走 Chat Completions / Responses / Anthropic，公共请求响应形状不变
 // - chat（默认）：OpenAI Chat Completions（兼容绝大多数厂商）
 // - responses：OpenAI Responses API（/v1/responses）
 // - anthropic：Anthropic Messages API（Claude 原生协议，环境变量 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL）
-const claude = await ai.llm.chat({ messages, model: 'claude' }) // 该模型配置 api: anthropic
+const claude = await ai.llm.chat({ messages, model: 'claude' }) // 该模型配置 protocol: anthropic
 
 // 临时模型：单次请求绕过配置注册模型，直接指定端点与凭据（chat/chatStream/ask/askStream 均支持）
 // 临时客户端按 TTL 缓存（llm.tempModelCacheTtl，默认 10 分钟），与常驻模型客户端隔离
 const temp = await ai.llm.chat({
   messages,
-  tempModel: { model: 'claude-3-5-sonnet', api: 'anthropic', apiKey: 'sk-temp' },
+  tempModel: { model: 'claude-3-5-sonnet', protocol: 'anthropic', apiKey: 'sk-temp' },
 })
 ```
 
@@ -194,6 +194,31 @@ const batch = await registry.executeAll(toolCalls)
 const chat = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
 ```
 
+#### ACP エージェント、ワークスペースとセッション
+
+`ai.acp` は Node サーバーで動作します。`embedded` はローカルプロセス、`builtin-service` は Podman/Docker コンテナ（利用可能な Podman を優先）、`custom-service` は既存の HTTP/WS ACP サービスです。Codex/dsh は stdio を使用し、未対応の転送方式を暗黙に変換しません。
+
+Podman はリモートサービスのプロキシ環境変数を自動継承しません。必要なプロキシは Agent/workspace の `environmentRefs` で明示し、コンテナから到達可能なアドレスを使用してください。
+
+Goose 1.57.0 イメージは `goose serve` のネイティブ HTTP/WS `/acp` を提供し、custom-service と `X-Secret-Key` で接続します。モデルは Goose 側で管理し、ワークスペースと状態 volume は配備側がマウントします。実際のリモート E2E では宣言された復元機能を検証します。
+
+- `agents.register/get/list/update/remove/initialize/check` で管理します。`codex`、`deepseek-harness` は `llm.models` を参照し、その他は `generic` または信頼された `AIInitOptions.acpAdapters` を使用します。外部サービスは自身でモデルを管理します。
+- `workspaces.register/prepare/importFiles` は永続ディレクトリ/volume、複数 Git、通常ファイルを管理します。各 Git の `mainBranch` は必須で、prepare は未コミットの変更を上書きしません。
+- `sessions.create/resume/get/list/close` と `newWorktree: true` で各ローカル主ブランチから同名ブランチを作成します。prompt/stream、厳密な構造化結果、権限、MCP、設定、キャンセルは ACP の能力を確認して実行します。
+- `session.updateMain()` は指定主ブランチを fetch/ff-only 更新します。`publish({ mode: 'merge-main' | 'push-branch', message, author })` は管理対象の分離セッションだけを公開し、リポジトリ単位の部分失敗を報告します。強制 push は行いません。実行環境を停止してから操作し、続行には明示的に resume します。
+
+確認済み容量、モダリティ、推論能力は `llm.models[].capabilities` に設定します。Codex は Responses を必要とし、既存 Hai 変換は逆方向ゲートウェイではありません。close 後もコード/状態を保持し、所有プロセス停止を確認後 CAS 占有を解放します。worktree はセキュリティサンドボックスではありません。
+
+[ACP ガイド](../cli/templates/skills/hai-ai/acp.md) と [Agent イメージ](models/agents/README.md) を参照してください。Git/Node/Python を含み Java/Rust/Go は任意、Codex イメージには codex-acp と codex の両方を含みます。エラーは `hai:ai:070`–`084`、通常 API は HaiResult、stream の失敗は例外です。
+
+管理対象 Git でサブモジュールや Git LFS 属性を検出すると ACP_UNSUPPORTED を返し、不完全な内容を準備完了として扱いません。
+
+#### 設定とデータベースのリソース一覧
+
+`llm.models`、`audio.models`、`image.models`、`mcp.servers`、`retrieval.sources`、`acp.agents/workspaces` は設定と DB を統合します。同じ ID は設定を優先し、設定は読み取り専用です。DB は list/get/register/update/remove に対応し、value/source/version と任意のバージョン照合を使用します。非同期呼び出しは最新の定義を読み、同期音声機能照会は直近のローカル情報を使います。エラーは 090–094。定義には認証情報が含まれるため、信頼できるサーバー管理 API として使用します。
+
+[Resource catalogs](../cli/templates/skills/hai-ai/resources.md) · [ACP](../cli/templates/skills/hai-ai/acp.md)
+
 #### A2A プロトコルの境界
 
 `ai.a2a.getAgentCard()` は `protocolVersion`、MIME、streaming 機能を含む完全な A2A 0.3 Agent Card を返します。Kit の既定検出パスは `/.well-known/agent-card.json`。`handleRequest()` は常に JSON-RPC/SSE の結果を返し、未初期化時は JSON-RPC エラーです。信頼された HTTP の `agentId` を executor の `context.user.userName` に対応付けます。JSON-RPC/SSE に対応し、push notifications・gRPC・REST 対応は宣言しません。業務リソースの認可はアプリの責任です。
@@ -516,18 +541,22 @@ const manager = ai.context.createManager({
 
 ### 設定
 
+Rerank は LLM 全体の timeout を継承し、モデル単位で上書きできます。期限は応答本文まで含み、超過時は RERANK_API_ERROR を返します。
+
+LLM の `llm.api`、`llm.models[].api`、`tempModel.api` は `protocol` に統一されました。値は `chat | responses | anthropic` のままです。環境変数は `HAI_AI_LLM_PROTOCOL`、`HAI_AI_LLM_MODELS_0_PROTOCOL`（他の項目は対応する添字）を使います。旧フィールドと旧プロトコル変数は移行案内付きでエラーになります。`apiKey` とその変数は変更ありません。
+
 ```yaml
 llm:
   apiKey: ''
   baseUrl: https://api.openai.com/v1
   model: gpt-4o-mini
-  api: chat # chat（默认）| responses | anthropic —— 底层 API 协议，对使用方透明
+  protocol: chat # chat（默认）| responses | anthropic —— 底层 API 协议，对使用方透明
   timeout: 60000
   tempModelCacheTtl: 600000 # 临时模型客户端缓存 TTL（毫秒，默认 10 分钟）
   models: # 可为每个模型单独指定协议
     - {id: fast, model: gpt-4o-mini}
-    - {id: strong, model: gpt-4.1, api: responses}
-    - {id: claude, model: claude-3-5-sonnet-latest, api: anthropic}
+    - {id: strong, model: gpt-4.1, protocol: responses}
+    - {id: claude, model: claude-3-5-sonnet-latest, protocol: anthropic}
   scenarios:
     chat: fast
     reasoning: strong

package/README.md

@@ -163,17 +163,17 @@ const controller = new AbortController()
 const cancellable = ai.llm.chat({ messages, signal: controller.signal })
 // controller.abort()
 
-// 多协议：模型的 api 决定底层走 Chat Completions / Responses / Anthropic，公共请求响应形状不变
+// 多协议：模型的 protocol 决定底层走 Chat Completions / Responses / Anthropic，公共请求响应形状不变
 // - chat（默认）：OpenAI Chat Completions（兼容绝大多数厂商）
 // - responses：OpenAI Responses API（/v1/responses）
 // - anthropic：Anthropic Messages API（Claude 原生协议，环境变量 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL）
-const claude = await ai.llm.chat({ messages, model: 'claude' }) // 该模型配置 api: anthropic
+const claude = await ai.llm.chat({ messages, model: 'claude' }) // 该模型配置 protocol: anthropic
 
 // 临时模型：单次请求绕过配置注册模型，直接指定端点与凭据（chat/chatStream/ask/askStream 均支持）
 // 临时客户端按 TTL 缓存（llm.tempModelCacheTtl，默认 10 分钟），与常驻模型客户端隔离
 const temp = await ai.llm.chat({
   messages,
-  tempModel: { model: 'claude-3-5-sonnet', api: 'anthropic', apiKey: 'sk-temp' },
+  tempModel: { model: 'claude-3-5-sonnet', protocol: 'anthropic', apiKey: 'sk-temp' },
 })
 ```
 
@@ -211,6 +211,31 @@ const batch = await registry.executeAll(toolCalls)
 const chat = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
 ```
 
+#### ACP 智能体、工作区和会话
+
+`ai.acp` 在 Node 服务端接入原生 ACP 智能体：`embedded` 本机进程、`builtin-service` Podman/Docker 容器（自动选择优先 Podman）、`custom-service` 已有 HTTP/WS 服务。Codex/dsh 当前使用 stdio；不自动转换不支持的传输。
+
+Podman 关闭远程服务代理变量的自动继承；代理通过 Agent/workspace 的 `environmentRefs` 显式配置，并使用容器可达的地址。
+
+Goose 1.57.0 镜像提供原生 `goose serve` HTTP/WS `/acp` 服务，通过 custom-service 和 `X-Secret-Key` 接入。模型由 Goose 服务维护，工作区与状态卷由部署方挂载；真实远程 E2E 按握手能力验收恢复。
+
+- `agents.register/get/list/update/remove/initialize/check` 维护智能体。`codex`、`deepseek-harness` 适配器引用 `llm.models`；其他原生程序用 `generic` 或可信 `AIInitOptions.acpAdapters`。自定义服务自行管理模型。
+- `workspaces.register/prepare/importFiles` 管理目录或持久 volume、多 Git 工程和普通文件；每个 Git 明确 `mainBranch`。prepare 不覆盖脏目录。
+- `sessions.create/resume/get/list/close` 管理会话；`newWorktree: true` 从各本地主分支建同名 worktree。prompt/stream/strict promptStructured、权限回调、MCP、模式配置、取消和能力检查沿用 ACP。
+- `session.updateMain()` 只 fetch/ff-only 更新明确主分支；`publish({ mode: 'merge-main' | 'push-branch', message, author })` 仅发布受管隔离 session，逐仓库报告部分失败，不强推。操作前停止执行环境，继续任务显式 resume。
+
+模型容量、模态和推理能力填 `llm.models[].capabilities`，未知不猜。Codex 要求原生 Responses；Hai 现有转换不是反向服务网关。关闭后保留代码/状态卷，确认拥有的进程停止才释放 CAS 占用；worktree 不是安全沙箱。
+
+接入示例与限制见 [ACP 指南](../cli/templates/skills/hai-ai/acp.md)。[Agent 镜像](models/agents/README.md) 包含 Git/Node/Python，可选 Java/Rust/Go；Codex 镜像同时含 codex-acp 和 codex。错误码为 `hai:ai:070`–`084`。普通 API 返回 HaiResult，stream 失败抛出；Node 以外不启动 Agent。
+
+托管 Git 遇到子模块或 Git LFS 属性时明确返回 ACP_UNSUPPORTED，避免将不完整工程报告为就绪。
+
+#### 配置与数据库资源清单
+
+`llm.models`、`audio.models`、`image.models`、`mcp.servers`、`retrieval.sources`、`acp.agents/workspaces` 合并配置和数据库。配置同 ID 优先且只读，数据库支持 list/get/register/update/remove；条目返回 value/source/version，更新可检查版本。异步调用读取最新定义，音频同步能力查询使用最近刷新快照。资源错误为 090–094。管理定义可能含模型密钥，仅在可信服务端使用。
+
+[Resource catalogs](../cli/templates/skills/hai-ai/resources.md) · [ACP](../cli/templates/skills/hai-ai/acp.md)
+
 #### A2A 协议边界
 
 `ai.a2a.getAgentCard()` 返回完整 A2A 0.3 Agent Card，含 `protocolVersion`、MIME 和 streaming 能力；Kit 默认发现路径为 `/.well-known/agent-card.json`。`handleRequest()` 始终返回 JSON-RPC/SSE 处理结果，未初始化返回 JSON-RPC 错误。可信 HTTP 认证上下文的 `agentId` 映射为 executor 的 `context.user.userName`。当前支持 JSON-RPC/SSE，不声明 push notifications、gRPC 或 REST 支持；业务资源授权仍由应用负责。
@@ -539,18 +564,22 @@ const manager = ai.context.createManager({
 
 ### 配置
 
+Rerank 继承全局 LLM timeout，模型条目可覆盖；同一预算覆盖请求及响应正文，超时返回 RERANK_API_ERROR。
+
+LLM 协议字段已从 `llm.api` / `llm.models[].api` / `tempModel.api` 统一改为 `protocol`，取值仍为 `chat | responses | anthropic`。环境变量改用 `HAI_AI_LLM_PROTOCOL`、`HAI_AI_LLM_MODELS_0_PROTOCOL`（其他项按索引递增）。旧字段和旧协议变量会明确报错并提示迁移；`apiKey` 及其变量不变。
+
 ```yaml
 llm:
   apiKey: ''
   baseUrl: https://api.openai.com/v1
   model: gpt-4o-mini
-  api: chat # chat（默认）| responses | anthropic —— 底层 API 协议，对使用方透明
+  protocol: chat # chat（默认）| responses | anthropic —— 底层 API 协议，对使用方透明
   timeout: 60000
   tempModelCacheTtl: 600000 # 临时模型客户端缓存 TTL（毫秒，默认 10 分钟）
   models: # 可为每个模型单独指定协议
     - {id: fast, model: gpt-4o-mini}
-    - {id: strong, model: gpt-4.1, api: responses}
-    - {id: claude, model: claude-3-5-sonnet-latest, api: anthropic}
+    - {id: strong, model: gpt-4.1, protocol: responses}
+    - {id: claude, model: claude-3-5-sonnet-latest, protocol: anthropic}
   scenarios:
     chat: fast
     reasoning: strong