fix(runtime): tighten extension boundaries and unsupported surfaces

[liujuanjuan1984]

关联 Issues

• Closes [Priority: Low] [Docs/Runtime] 收口 push notification surface 为明确 unsupported #391
• Closes [Priority: Med] [Architecture] 收敛过界的 workspace/worktree mutation extensions #393
• Closes [Priority: Med] [Architecture] 重构 session extension taxonomy 以修正命名与分组失真 #394
• Related [Priority: High] [Security] 收敛 push notification webhook 的 URL 校验与最小鉴权基线 #371（已关闭；本 PR 延续其“明确 unsupported / 收敛过界 extensions / 修正失真 taxonomy”的收口背景）

变更概览

Push Notification 收口

• 更新 docs/guide.md，明确声明 tasks/pushNotificationConfig/* 当前仍会随 SDK-owned core surface 暴露，但本 runtime 没有配置 push_config_store / push_sender，因此该能力当前是 unsupported。
• 补充 REST 与 JSON-RPC 的实际差异：
  • REST 路由返回 HTTP 501
  • JSON-RPC 方法返回 SDK-owned unsupported error envelope
• 同步修正兼容性矩阵与运行时描述，避免继续把 push notification surface 描述成可用能力。

Workspace / Worktree Extension 收口

• 新增 A2A_ENABLE_WORKSPACE_MUTATIONS，将 opencode.workspaces.create/remove 与 opencode.worktrees.create/remove/reset 收敛为 deployment-conditional methods，且默认关闭。
• 默认情况下：
  • 不再把上述 mutation methods 写入 all_jsonrpc_methods
  • 不再在 Agent Card / wire contract / OpenAPI examples 中默认声明这些方法
  • 调用这些方法时返回明确的 METHOD_NOT_SUPPORTED
• 保留只读 discovery methods：
  • opencode.projects.list
  • opencode.projects.current
  • opencode.workspaces.list
  • opencode.worktrees.list
• 进一步补充 machine-readable stability 语义：
  • project discovery 维持稳定口径
  • workspace/worktree surfaces 明确标注为 upstream experimental 依赖
  • workspace_control extension retention 调整为 mixed
• 新增 runtime profile / compatibility / wire contract 对 workspace_mutations 的声明，避免“实现关了但契约还声称始终可用”。

Session Management Taxonomy 重构

• 将公开 session extension URI 从 opencode-session-query-v1 直接调整为 opencode-session-management-v1。
• 将公开 skill id / skill name 从 opencode.sessions.query / OpenCode Sessions Query 调整为 opencode.sessions.management / OpenCode Session Management。
• 将扩展契约中的 lifecycle_methods 直接拆分为语义更准确的：
  • read_methods
  • mutation_methods
  • control_methods
• 将 OpenAPI x-a2a-extension-contracts 中的键名从 session_query 调整为 session_management。
• 同步更新 Agent Card、OpenAPI 描述与 examples、扩展规范文档、集成说明和回归测试。
• 本次不保留旧 taxonomy 的兼容层，下游消费端应基于新版 contract 一次性迁移。

Interrupt Recovery 契约收口

• 明确 opencode.permissions.list / opencode.questions.list 读取的是 adapter-local interrupt binding registry，而不是上游全局 pending queue。
• 明确这组方法是 identity-scoped recovery surface：
  • 结果仅面向当前 authenticated caller
  • 如果当前请求无法解析 caller identity，则返回空列表
• 在 extension params / compatibility profile 中补充 recovery_scope、implementation_scope、identity_scope 等 machine-readable 语义。

文档与契约

• 更新 docs/extension-specifications.md 与 docs/guide.md，统一当前 runtime 对 unsupported push surface、workspace discovery/mutation 边界、interrupt recovery 来源，以及 session management taxonomy 的对外口径。
• 更新 Agent Card 与 OpenAPI 描述/示例，确保公开 contract 与当前 runtime 行为一致。

测试

• 增加 disabled 状态下的 unsupported-method 回归测试。
• 增加 enabled 状态下的 Agent Card / wire contract / runtime profile 回归测试。
• 调整 OpenAPI / contract consistency / workspace control / session management 测试，使其与新的 capability snapshot 保持一致。
• 调整 gzip 断言，使其按当前响应体大小与中间件阈值判断，而不是硬编码 public agent card 永不压缩。

与相关 Issues 的关系审查

• #391 已由本 PR 完整承接，使用 Closes #391 准确。
• #393 的验收项已经在本 PR 完成，且已继续承接后续 workspace/interrupt extension boundary 收口，使用 Closes #393 准确。
• #394 的 taxonomy 重构已在本 PR 完成，使用 Closes #394 准确。
• #371 已关闭，不应再使用 Closes #371；保留 Related #371 仅用于追溯收口背景更准确。

验证

• ./scripts/doctor.sh
• 530 tests passed
• coverage 91.10%

[liujuanjuan1984]

本次对 PR #392 的独立审查结论如下。

1. 代码变动审查

• 当前版本无阻塞性问题。
• 变更目标与实际实现一致：没有误把 push notification 做成“半支持”，而是把当前真实状态明确收口为 unsupported。
• 文档、Agent Card 描述、服务行为测试三者现在已经对齐，且分别覆盖了 REST 与 JSON-RPC 两条主要入口，回归保护足够直接。

2. 对 issues 目标的贴合度审查

• 本 PR 现在更准确地解决的是 #391，即“把当前 surface 明确收口为 unsupported”。
• 与已关闭的 #371 的关系应保持为 Related，不应写成 Closes，因为本 PR 并未实现 push notification 安全基线，而是确认当前前提不成立并完成收口。

3. 审查过程中发现并已修正的问题

• 初版改动把 push notification 当前行为笼统描述成“返回 501 / unsupported”。
• 复查后确认这只对 REST 路由成立；JSON-RPC 方法实际返回的是 SDK-owned unsupported error envelope。
• 该偏差已在后续 commit 中修正，并补充了对应 JSON-RPC 回归测试。

4. PR 元数据审查

• PR 标题已更新为英文 commit message 风格。
• PR 描述已按模块拆分，并补充 Closes #391 / Related #371 的准确关系说明。

结论：当前 PR 可以作为 Draft 继续等待人工复核，没有额外必须先修的问题。

[liujuanjuan1984]

本轮基于 #393 对 PR 代码变动做了独立复审，结论如下：

1. 方向合理

• 这次改动是在收紧真实能力边界，而不是新增功能，符合当前 runtime 的最佳实践。
• workspace/worktree mutation methods 之前默认常开，但其语义更接近 operator control plane；改为 deployment-conditional 且默认关闭后，契约与风险级别更一致。

2. 实现方式合理

• 通过新增 A2A_ENABLE_WORKSPACE_MUTATIONS 收敛能力面，比直接硬删常量/handler 更稳妥：
  • 默认调用方拿到明确的 METHOD_NOT_SUPPORTED
  • Agent Card / wire contract / OpenAPI examples 同步收窄
  • 未来若确有 trusted operator 场景，仍可通过显式开关启用
• 只读 discovery methods 被保留，没有误伤当前仍合理的 provider-private discovery surface。

3. 契约同步到位

• runtime profile、compatibility profile、wire contract、Agent Card、OpenAPI、guide/spec 文档、回归测试已经一起更新，没有出现“实现变了但对外声明没跟上”的半收口状态。

4. 剩余风险 / 后续项

• 本 PR 没有处理 OpenCode Session Query v1 的命名与分组失真问题；这不是本次实现缺陷，但仍值得后续单独 issue 跟踪。
• 当前 workspace_mutations 的开关粒度是整组 methods 共用一个 toggle；对当前阶段足够，但如果后续出现更细粒度授权需求，可能还需要进一步拆分。

验证结果：

• ./scripts/doctor.sh
• 530 tests passed
• coverage 91.10%

[liujuanjuan1984]

本轮基于最新代码再次独立审查，结论如下：

1. 代码变动审查

• 当前 PR 没有发现新的阻塞性问题。
• push notification 部分的收口是合理的：当前 runtime 事实上未启用 push sender / push config store，把能力明确收束为 unsupported，比继续维持模糊暴露面更准确。
• workspace/worktree mutation extensions 的默认关闭是合理的：只读 discovery methods 保留，mutation methods 改为 deployment-conditional，边界比之前清晰。
• session extension taxonomy 的直接重构也是合理的：既然本次明确不保留旧消费端兼容层，就应一次性把 Query 的失真命名改正，而不是继续在错误 taxonomy 上叠加收口补丁。

2. 语义与实现审查

• opencode-session-query-v1 直接改为 opencode-session-management-v1，与真实方法面一致。
• lifecycle_methods 改为 read_methods / mutation_methods / control_methods，能更准确表达风险和用途。
• OpenAPI contract key、Agent Card skill id/name、文档说明和测试都已同步，没有留下新的“文档已改但 wire contract 未改”的偏差。
• 本次不保留旧 taxonomy 兼容层，与本 PR 的迁移策略一致，下游消费端可以基于一个明确的新 contract 做一次性迁移。

3. PR 与 Issues 关系审查

• Closes #391：准确。
• Closes #393：准确。
• Closes #394：准确。
• Related #371：准确；#371 已关闭，不应再使用 Closes #371。

4. 验证

• ./scripts/doctor.sh
• 530 tests passed
• coverage 91.10%

[liujuanjuan1984]

补充审查结论：

这轮再次审查后发现的两个剩余边界点，已经随当前 PR 一并收口完成：

1. workspace control 不再只停留在“mutation 默认关闭”，现在进一步把 workspace/worktree surfaces 的 upstream experimental 性质显式写进 contract，而不是继续和 project discovery 混成同一稳定性口径。
2. interrupt recovery 不再只被描述成 provider-private OpenCode extension，现在进一步明确成 adapter-local、identity-scoped 的恢复视图，和上游全局 pending queue 做了清晰区分。

因此，按“extensions 是否过界、是否语义一致、是否与 runtime 行为一致”的标准再看，本 PR 当前没有新的阻塞性遗漏。剩余风险主要是命名层面仍保留了 OpenCode Interrupt Recovery / OpenCode Workspace Control 这类历史名称，但 contract 本身已经把关键边界写清楚，不再构成误导性缺口。

验证：

• ./scripts/doctor.sh
• 530 tests passed
• coverage 91.10%

[liujuanjuan1984]

补充说明：当前分支里“默认关闭”的并不是整个 extension，而是两组 deployment-conditional 的 extension methods。

1. OpenCode Session Management 下的 opencode.sessions.shell

• 开关：A2A_ENABLE_SESSION_SHELL
• 默认值：false
• 默认关闭原因：该方法会在 workspace 上下文里执行 shell 命令，属于高风险执行面，不适合作为默认开放能力。
• 运行时保护：即使配置显式开启，只要 deployment 处于 read-only sandbox 或 write_access_scope=none，runtime 也会继续强制关闭。

2. OpenCode Workspace Control 下的 mutation methods

• 开关：A2A_ENABLE_WORKSPACE_MUTATIONS
• 默认值：false
• 默认关闭的方法：
  • opencode.workspaces.create
  • opencode.workspaces.remove
  • opencode.worktrees.create
  • opencode.worktrees.remove
  • opencode.worktrees.reset
• 默认关闭原因：这些方法会直接改动 active deployment project 的 workspace/worktree 状态，属于 operator-only control-plane mutation，不应作为默认开放能力。
• 额外边界：这组 workspace/worktree surfaces 当前还依赖上游 /experimental/workspace / /experimental/worktree endpoints，因此本 PR 也补充了 machine-readable upstream stability 声明。
• 运行时保护：即使配置显式开启，只要 deployment 是 read-only sandbox 或 write_access_scope=none，runtime 也会继续强制关闭。

补充区分：

• tasks/pushNotificationConfig/* 当前也是不可用，但它不属于“默认关闭的 extension methods”。它是 SDK-owned core surface 暴露了路由/方法，而本 runtime 没有配置 push sender / push config store，因此当前语义是 unsupported。

这也是本 PR 收口的核心原则：

• 默认开放只读 discovery、稳定 compatibility surface、低风险 control
• 高风险 execution、operator mutation、experimental-upstream 依赖面必须显式开关或明确 unsupported

[liujuanjuan1984]

本轮收尾审查结论如下。

1. 代码变动审查

• 当前 PR 没有发现新的阻塞性问题。
• #391 对应的 push notification 收口是合理的：当前 runtime 事实上未启用 push sender / push config store，把它明确契约化为 unsupported，比继续保留模糊可用口径更稳妥。
• #393 对应的 workspace/worktree extension 收口是合理的：默认关闭 mutation methods、补充 upstream experimental 稳定性语义、并把 interrupt recovery 明确为 adapter-local / identity-scoped，都属于把公开 contract 拉回到真实 runtime 边界之内。
• #394 对应的 session taxonomy 重构也是合理的：既然本次明确不保留旧消费端兼容层，就应直接修正 Session Query 的失真命名与分组，而不是继续在旧 taxonomy 上叠加补丁。

2. 实现质量审查

• 本 PR 的实现方式整体是收敛型而不是扩张型，方向正确。
• machine-readable contract 与文档/Agent Card/OpenAPI 基本保持一致，没有看到明显“代码已改、文档没改”或“文档已改、wire contract 没改”的偏差。
• 唯一值得注意的连带影响是 public agent card 因描述增量跨过 gzip 阈值，相关测试已按中间件真实行为修正；这属于合理回归修复，不是设计问题。

3. 与相关 Issues 的关系审查

• Closes #391：准确。
• Closes #393：准确。
• Closes #394：准确。
• Related #371：准确；#371 已关闭，不应再使用 Closes #371。

4. 风险与剩余事项

• 当前剩余主要是历史命名包袱，例如 OpenCode Workspace Control / OpenCode Interrupt Recovery 这些名字还带有旧语义，但 contract 已经把关键边界写清楚，不构成当前 PR 的阻塞项。
• 当前分支工作区干净，没有待提交改动；远端分支已同步到最新 commit。

验证：

• ./scripts/doctor.sh
• 530 tests passed
• coverage 91.10%