# remote-tools

让服务端 Claude Agent SDK agent 安全地操作用户本机：6 个 `client__*` MCP 工具经
WebSocket 隧道转发到用户桌面端（Plan B：remote-tools-desktop）执行。

设计文档：`../docs/remote-tools/2026-09-09-remote-tool-proxy-design.md`

## 宿主集成样例

```ts
import { query } from "@anthropic-ai/claude-agent-sdk";
import { TunnelServer, createServerWriteFence } from "remote-tools";      // 根入口不加载 SDK
import { createClientToolsSdkMcp } from "remote-tools/mcp-bridge/sdk";

const tunnel = new TunnelServer({ token: process.env.REMOTE_TOOLS_TOKEN! });
await tunnel.listen(8787);

const codingSession = query({
  prompt: "按 docs/ 里的 Spec 与 Plan 编码",
  options: {
    mcpServers: { client: createClientToolsSdkMcp(tunnel) },
    canUseTool: createServerWriteFence({ docsRoots: ["/data/docs"] }),
    disallowedTools: ["Bash"],            // 服务器不执行；构建调试走 client__bash
    systemPrompt: {
      type: "preset", preset: "claude_code",
      append: "服务器存放需求与技术文档（docs/ 内可读可写）；用户的所有代码、依赖与运行环境"
        + "都在其本机——编码、构建、调试、执行一律使用 client__* 工具。",
    },
  },
});
```

导出位置：`remote-tools` 根入口是 SDK-free 的（`TunnelServer` / `createToolHandlers` /
`createServerWriteFence`）；依赖 Agent SDK 的两个适配器分别走子路径
`remote-tools/mcp-bridge/sdk`（6 个 `client__*` 工具）与
`remote-tools/phase/switch`（`submit_phase` 阶段切换）。

阶段切换（`submit_phase`）与两阶段 options 的组合见设计文档 §10。

## 重要注意事项

- **bash 默认超时 120s > SDK 默认 60s 流关闭超时**：宿主需设置环境变量
  `CLAUDE_CODE_STREAM_CLOSE_TIMEOUT`（如 `180000`），否则长构建/测试会被 SDK 提前切断。
- 隧道令牌用 32 字节随机值生成：`node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`。
- 客户端桌面端（Tauri）是独立项目 remote-tools-desktop，协议为 `src/protocol/envelope.ts`
  定义的 JSON 信封（TS 与 Rust 仅结构对齐）。
- 集成样例已按当前安装的 Agent SDK 用 `tsc` 校验：该版本的 `Options` 没有 `appendSystemPrompt`
  字段，追加指令走 `systemPrompt: { type: "preset", preset: "claude_code", append }`；
  若你的 SDK 版本提供 `appendSystemPrompt`，两者语义等价。

## 开发

```bash
npm test        # vitest
npm run typecheck
```