feat(acp): support locale injection via ACP initialize for i18n

[Million-mo]

Summary

支持通过 ACP initialize 请求传入 locale 变量，实现 agent 输出的多语言国际化。

客户端在 ACP initialize 时通过 _meta 字段传入 locale，agentpool 将其透传到 session，并作为 callable system prompt 注入到 agent，指导 agent 以指定语言响应。

Background

当前 agentpool 不支持任何 i18n 基础设施。agent 输出语言完全由 YAML 配置中的静态 prompt 文本决定，客户端无法在运行时指定语言偏好。

Changes

服务端（agentpool）

文件	改动
acp_agent.py	initialize() 从 params.field_meta 提取 locale，存储为 self.client_locale；在 new_session/fork_session/load_session/resume_session 中透传
session_manager.py	create_session() 和 resume_session() 接受 client_locale 参数，转发给 ACPSession
session.py	ACPSession 增加 client_locale 字段；__post_init__() 和 switch_active_agent() 中注入 get_locale_prompt() callable prompt
test_acp_session_resume.py	更新断言以包含 client_locale kwarg

客户端支持

ACP 客户端在 initialize 请求中通过 _meta 字段传入 locale：

{
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientInfo": { "name": "xeno-agent", "title": "Xeno Agent", "version": "1.0" },
    "clientCapabilities": { "terminal": true, "fs": { "readTextFile": true, "writeTextFile": true } },
    "_meta": { "locale": "en" }
  }
}

如果使用 agentpool 的 ACP 客户端 SDK（ACPAgentAPI）：

await client.initialize(
    title="Xeno Agent",
    version="1.0",
    name="xeno-agent",
    metadata={"locale": "en"},  # 传入 locale
)

metadata 参数会被序列化为 field_meta，在 JSON-RPC 中映射为 _meta。

How It Works

1. 客户端 initialize 时通过 _meta.locale 传入语言偏好
2. AgentPoolACPAgent.initialize() 提取并存储 self.client_locale
3. new_session/fork_session/load_session/resume_session 将 locale 传递到 ACPSessionManager
4. ACPSession.__post_init__() 将 get_locale_prompt 作为 callable prompt 注册到 agent 的 sys_prompts.prompts
5. pydantic-ai 在每次 model call 时调用该 callable，生成 "Language: You MUST respond in en." 指令
6. agent 按指定语言输出

复用了已有的 callable prompt 机制（与 get_cwd_context 完全同构），在 switch_active_agent 时也会正确清理和重新注入。

Testing

• ruff check ✅
• mypy ✅
• pytest tests/servers/acp_server/ — 315 passed, 4 skipped ✅
• pytest tests/acp/ tests/agents/acp_agent/ — 251 passed ✅

Limitations / Future Work

• 当前 locale 以追加 callable prompt 的方式注入，不直接嵌入 YAML Jinja2 模板。后续可扩展 format_system_prompt() 支持 {{ locale }} 模板变量
• 同一 agentpool 实例可服务不同 locale 的客户端（每个连接独立 AgentPoolACPAgent 实例）
• 可扩展支持 new_session 级别的 locale 覆盖

[gemini-code-assist]

Code Review

This pull request introduces support for client locales within the ACP server by extracting the locale from client metadata and injecting a language directive into the agent's system prompts. Feedback highlights a potential prompt injection vulnerability where the client-provided locale should be validated, and suggests using explicit is not None checks for metadata dictionary presence. Additionally, a potential memory leak and state residue risk was identified, recommending that the locale prompt be cleaned up in ACPSession.close() to ensure proper garbage collection.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Million-mo]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for client locales in the ACP server. It extracts and validates the client's locale from metadata during initialization, propagates it to sessions, and appends a system prompt instructing the agent to respond in the preferred language. The review feedback highlights a security improvement in the locale validation logic, suggesting that the character check be restricted to ASCII alphanumeric characters to prevent potential prompt injection via Unicode characters.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.