# 运行时与能力协商

使用默认 nxs 或接入第三方异构运行时，通过能力协商确认支持范围。

## 使用默认运行时 nxs

Bridge 默认选择 nxs，文档中的任务、工具和会话示例也使用 nxs。独立程序通过 `WithCLIPath` 或 `NEXUS_NXS_COMMAND_PATH` 提供可信可执行文件。Bridge 不会从 PATH 中自动寻找 nxs。

```go
options := client.NewOptions().WithRuntime(client.RuntimeNXS).
    WithCLIPath("/opt/nexus/bin/nxs").WithCWD("/srv/agent-work")
```

可省略 WithRuntime，保留默认选择。路径只是示例，请换成部署机上的实际文件。可执行文件、工作目录、运行身份和环境变量共同决定运行环境。程序能被找到，不代表模型访问已经配置。

## 接入第三方异构 Agent 运行时

Claude Code 是 bridge 当前支持的一种第三方异构 Agent 运行时。它有自己的安装、认证、模型配置与执行行为，需要显式选择。下面的代码只展示这一适配入口，通用教程仍以 nxs 为默认。

```go
options := client.NewOptions().WithRuntime(client.RuntimeClaude).
    WithCLIPath("/usr/local/bin/claude").WithCWD("/srv/agent-work")
```

也可通过 `NEXUS_CLAUDE_COMMAND_PATH` 指定 Claude Code 路径。接入第三方运行时之前，先在相同运行身份下完成它自己的安装和模型配置。

运行时接入不限定为这两个实现。后续扩展其他异构 Agent 运行时，需要相应适配与契约验证；不能仅替换可执行文件路径就视为兼容。宿主应按能力判断可用功能，避免把业务逻辑写成 nxs 与 Claude Code 的二选一。

## 能力检查与实际调用

公开方法存在不代表当前运行时一定支持。`Session.Supports` 是宿主判断能力的入口，其中一部分能力由 bridge 适配，一部分按运行时区分，另一部分来自初始化协议协商。

```go
if !session.Supports(client.CapabilityMessageExecutionPolicy) {
    return fmt.Errorf("当前运行时不支持单条消息执行限制")
}
stream, err := session.SendWithOptions(ctx, "只根据现有上下文回答。",
    protocol.OutboundMessageOptions{ToolAccess: "none", MaxOutputTokens: 512})
if err != nil { return err }
result, err := stream.Result(ctx)
if err != nil { return err }
if result.IsError { return fmt.Errorf("受限任务失败：%s", result.Subtype) }
```

这里遇到不支持时停止发送，不能退回普通 Send。否则“禁止工具”会在兼容分支中失效。`MaxOutputTokens` 是这条消息的输出限制，不是整个会话的费用上限。

## 运行时差异

| 能力 | 公开能力常量 | 接入时的判断 |
| --- | --- | --- |
| 下一轮内部上下文 | `CapabilityInternalContext` | nxs 与 Claude 的注入机制不同，宿主调用统一入口 |
| 精确会话分叉 | `CapabilitySessionFork` | 保留完成消息 ID，并处理恢复文件缺失 |
| Go 进程内 MCP | `CapabilityInProcessMCP` | 工具代码由宿主执行 |
| 停止后台任务 | `CapabilityStopTask` | 使用运行时提供的 task ID |
| 后台任务续聊 | `CapabilitySendTaskMessage` | 当前为 nxs 能力 |
| 环境热更新 | `CapabilityUpdateEnvironment` | 当前为 nxs 能力 |
| AutoDream | `CapabilityAutoDream` | 当前为 nxs 能力；宿主唤醒不等于必然执行 |
| 子任务控制 | `CapabilitySubagentControl` | 必须协商 `subagent_control_v1` |
| 单条消息执行策略 | `CapabilityMessageExecutionPolicy` | 必须协商 `message_execution_policy_v1` |
| Hook 应用回执 | `CapabilityHookResponseAck` | 必须协商 `hook_response_ack_v1` |
| 自动审核 | `CapabilityAutoReview` | nxs 需要扩展协商；Claude 还需确认原生模式启用 |

Supports 为 true 也不保证账号、模型或策略可用，最终以控制调用和运行结果为准。能力来源见 [capability.go](https://github.com/nexus-research-lab/nexus-agent-sdk-bridge/blob/main/client/capability.go)。

## 控制已建立的会话

用 `session.Control()` 获取模型、设置和任务控制，用 `session.MCP()` 管理 MCP 服务。控制请求有自己的 context，应设置超时。长时控制的取消会沿同一 request ID 传给运行时，不应在超时后立即重复发送同一副作用操作。

初始化信息可通过 `InitializationResult` 获取；模型列表使用 `SupportedModels`。这些信息适合生成你自己的配置界面，但展示给用户前应筛选字段，不要暴露账号快照或完整进程环境。

## 自定义连接

`WithDirectConnect` 用于宿主管理远端运行时，`WithTransport` 用于宿主提供完整传输实现，二者不能同时设置。这些入口不提供应用级用户认证、负载均衡或租户隔离。只有在进程托管确实由其他服务负责时才使用它们；一般接入从本地子进程开始即可。