feat(selfhosted): add client-side MCP tools

[ark-hand]

Hand-written change from the internal SDK repository — not produced by make vendor.

• source subject: feat(selfhosted): add client-side MCP tools
• reason: No Ark-APIs provenance marker; treated as a hand-written source commit.

简述

为 Go self-hosted worker 增加 client-side MCP tools，并适配当前 Managed Agents Custom Tool 契约。核心模块保持 Go 1.20，可选官方 MCP adapter 使用独立 Go 1.23 module；同时修复通用 HTTP retry 的等待时间、服务端提示与重试标记。

改动

• core 增加协议无关 MCP Client、ToolDefinition、结果模型和 Custom Tool 转换。
• 可选 github.com/volcengine/ark-runtime-go/mcp 接入官方 MCP Go SDK。
• 支持 text、image、embedded resource、PDF 与 structured content。
• type/properties/required 结构化传递，property 内本地引用内联，其余有效顶层约束以紧凑 JSON 写入 tool description。
• 增加根版本发布时自动创建匹配 mcp/vMAJOR.MINOR.0 tag 的 workflow；adapter 从 v0.6.0 开始与 core 同版本安装。
• MCP 凭证和连接仅保留在 worker 侧。

SDK retry 修复

• 默认最大重试次数保持 2 次；首次等待改为 0.5 秒基数，之后指数增长并封顶 8 秒，每次减去 0–25% jitter。
• 直接按 time.Duration 的纳秒精度计算退避，避免先转整数秒导致首次重试接近 0 秒。
• 优先读取 Retry-After-Ms，其次读取 Retry-After；支持小数数值以及 HTTP-date。
• 首次请求和后续重试分别携带 X-Stainless-Retry-Count: 0/1/2，调用方显式设置该 header 时保留调用方值。
• 支持 X-Should-Retry 显式控制，并将 408、409、429、5xx 统一视为可重试状态。
• 错误响应保留 response header 供退避决策使用；流式握手失败时关闭响应体，避免连接占用。

其他行为修复

• 文本 content block 即使内容为空也保留 MA 契约必需的 text 字段。
• MCP 返回 isError=true 且没有内容时，生成 tool returned an error，避免空错误结果。
• embedded resource 转换失败时不再把 URI 写入 tool result，避免 signed URL 或查询凭证进入 MA、模型和日志。
• property 内已成功内联的 $defs/definitions 不再重复写入 description；仍被其他约束引用时继续保留。
• 不修改 MA 或 Agent Loop，仍适配现网 type/properties/required 三字段 Custom Tool 契约。

测试

• go test ./...、go vet ./...
• golangci-lint v1.64.8
• MCP module: go test ./...、go vet ./...
• retry 新增亚秒退避、8 秒上限、服务端等待提示、状态码/显式控制及 retry-count 集成测试。
• GitHub Actions actionlint
• 本地模拟 v0.6.0 + mcp/v0.6.0 后，从干净 consumer 执行 go get .../mcp@v0.6.0 成功。
• STG 真实链路：MCP tools/list -> Agent custom tool -> worker CallTool -> user.custom_tool_result -> 模型继续推理 通过，并完成 Python/Java 版本工具调用。

示例

• 新增 examples/self_hosted_mcp_worker，以最小粒度展示 tools/list -> Custom Tool 定义 -> MCP Tool 执行 -> EnvironmentWorker.Run。
• 示例通过独立 module 引入可选 MCP adapter，不提高 core module 的 Go 版本或基础依赖。
• 内置最小 stdio mcp_echo server，便于本地直接验证；示例不负责创建 Agent、Session 或消费 SSE。

See merge request: !89

Sync-Source-Commit: d8736eda4005b445901dca9c6e85b4e99f1d675d
Hand-Written-Reason: No Ark-APIs provenance marker; treated as a hand-written source commit.
Release-Version: 0.6.0

Created by ark-hand.