feat: 实现 SSH Remote — 本地 REPL + 远端工具执行

SSH Remote 允许在本地运行交互式 REPL，同时将工具调用（Bash、文件读写等）
通过 SSH 隧道转发到远程主机执行。

核心模块：
- SSHSessionManager: NDJSON 双向通信、权限转发、指数退避重连
- SSHAuthProxy: 本地认证代理 + SSH -R 反向端口转发，nonce 验证
- SSHProbe: 远端主机平台/架构/已有二进制探测
- SSHDeploy: 远端二进制部署（scp）
- createSSHSession: 会话编排（probe → deploy → spawn → attach）

新增选项：
- --remote-bin: 跳过 probe/deploy，使用自定义远端二进制
- ANTHROPIC_AUTH_NONCE: API 请求认证 nonce header

包含 17 个单元测试和完整文档。

Author: unraid

docs/features/ssh-remote.md

@@ -72,4 +72,6 @@ export const DEFAULT_BUILD_FEATURES = [
     'POOR',                        // 穷鬼模式，跳过 extract_memories/prompt_suggestion 减少消耗
     // Team Memory
     'TEAMMEM',                     // 团队记忆，代理队友间共享记忆文件
+    // SSH Remote
+    'SSH_REMOTE',                  // SSH 远程连接，本地 REPL + 远端工具执行
 ]as const;

scripts/defines.ts

@@ -869,6 +869,7 @@ type PendingSSH = {
 	local: boolean;
 	/** Extra CLI args to forward to the remote CLI on initial spawn (--resume, -c). */
 	extraCliArgs: string[];
+	remoteBin: string | undefined;
 };
 const _pendingSSH: PendingSSH | undefined = feature("SSH_REMOTE")
 	? {
@@ -878,6 +879,7 @@ const _pendingSSH: PendingSSH | undefined = feature("SSH_REMOTE")
 			dangerouslySkipPermissions: false,
 			local: false,
 			extraCliArgs: [],
+			remoteBin: undefined,
 		}
 	: undefined;
 
@@ -1084,6 +1086,17 @@ export async function main() {
 					rawCliArgs.splice(eqI, 1);
 				}
 			};
+			const rbIdx = rawCliArgs.indexOf('--remote-bin');
+			if (rbIdx !== -1 && rawCliArgs[rbIdx + 1] && !rawCliArgs[rbIdx + 1]!.startsWith('-')) {
+				_pendingSSH.remoteBin = rawCliArgs[rbIdx + 1];
+				rawCliArgs.splice(rbIdx, 2);
+			}
+			const rbEqIdx = rawCliArgs.findIndex(a => a.startsWith('--remote-bin='));
+			if (rbEqIdx !== -1) {
+				_pendingSSH.remoteBin = rawCliArgs[rbEqIdx]!.split('=').slice(1).join('=');
+				rawCliArgs.splice(rbEqIdx, 1);
+			}
+
 			extractFlag("-c", { as: "--continue" });
 			extractFlag("--continue");
 			extractFlag("--resume", { hasValue: true });
@@ -4643,6 +4656,7 @@ async function run(): Promise<CommanderCommand> {
 								dangerouslySkipPermissions:
 									_pendingSSH.dangerouslySkipPermissions,
 								extraCliArgs: _pendingSSH.extraCliArgs,
+								remoteBin: _pendingSSH.remoteBin,
 							},
 							isTTY
 								? {
@@ -5980,6 +5994,11 @@ async function run(): Promise<CommanderCommand> {
 				"--dangerously-skip-permissions",
 				"Skip all permission prompts on the remote (dangerous)",
 			)
+			.option(
+				"--remote-bin <command>",
+				"Custom remote binary command (skips probe/deploy). " +
+					"Example: --remote-bin 'bun /path/to/project/dist/cli.js'",
+			)
 			.option(
 				"--local",
 				"e2e test mode — spawn the child CLI locally (skip ssh/deploy). " +

src/main.tsx

@@ -109,6 +109,10 @@ export async function getAnthropicClient({
       : {}),
     // SDK consumers can identify their app/library for backend analytics
     ...(clientApp ? { 'x-client-app': clientApp } : {}),
+    // SSH auth proxy nonce — tunneled API requests must carry this header
+    ...(process.env.ANTHROPIC_AUTH_NONCE
+      ? { 'x-auth-nonce': process.env.ANTHROPIC_AUTH_NONCE }
+      : {}),
   }
 
   // Log API client configuration for HFI debugging

src/services/api/client.ts

@@ -0,0 +1,165 @@
+import { randomUUID } from 'crypto'
+import { unlinkSync } from 'fs'
+import { getClaudeAIOAuthTokens } from 'src/utils/auth.js'
+import { getOauthConfig } from 'src/constants/oauth.js'
+import { logForDebugging } from 'src/utils/debug.js'
+
+export interface SSHAuthProxy {
+  stop(): void
+}
+
+export interface AuthProxyInfo {
+  proxy: SSHAuthProxy
+  /** Unix socket path or 127.0.0.1:<port> */
+  localAddress: string
+  /** Environment variables to inject into the remote/child CLI process */
+  authEnv: Record<string, string>
+}
+
+const isWindows = process.platform === 'win32'
+
+function resolveAuthHeaders(): Record<string, string> {
+  const apiKey = process.env.ANTHROPIC_API_KEY
+  if (apiKey) {
+    return { 'x-api-key': apiKey }
+  }
+
+  const oauthTokens = getClaudeAIOAuthTokens()
+  if (oauthTokens?.accessToken) {
+    return { Authorization: `Bearer ${oauthTokens.accessToken}` }
+  }
+
+  return {}
+}
+
+function resolveUpstreamBaseUrl(): string {
+  return process.env.ANTHROPIC_BASE_URL || getOauthConfig().BASE_API_URL
+}
+
+async function proxyFetch(
+  req: Request,
+  nonce: string | null,
+): Promise<Response> {
+  if (nonce && req.headers.get('x-auth-nonce') !== nonce) {
+    return new Response('Forbidden', { status: 403 })
+  }
+
+  const upstreamBase = resolveUpstreamBaseUrl()
+  const url = new URL(req.url)
+  const upstreamUrl = `${upstreamBase}${url.pathname}${url.search}`
+
+  const authHeaders = resolveAuthHeaders()
+  if (Object.keys(authHeaders).length === 0) {
+    return new Response(
+      JSON.stringify({
+        error: 'No API credentials available on local machine',
+      }),
+      { status: 401, headers: { 'content-type': 'application/json' } },
+    )
+  }
+
+  const forwardHeaders = new Headers(req.headers)
+  for (const [k, v] of Object.entries(authHeaders)) {
+    forwardHeaders.set(k, v)
+  }
+  forwardHeaders.delete('host')
+  forwardHeaders.delete('x-auth-nonce')
+
+  logForDebugging(
+    `[SSHAuthProxy] ${req.method} ${url.pathname} -> ${upstreamUrl}`,
+  )
+
+  try {
+    const upstreamRes = await fetch(upstreamUrl, {
+      method: req.method,
+      headers: forwardHeaders,
+      body: req.body,
+      // @ts-expect-error Bun supports duplex for streaming request bodies
+      duplex: 'half',
+    })
+
+    const responseHeaders = new Headers(upstreamRes.headers)
+    responseHeaders.delete('content-encoding')
+    responseHeaders.delete('content-length')
+
+    return new Response(upstreamRes.body, {
+      status: upstreamRes.status,
+      statusText: upstreamRes.statusText,
+      headers: responseHeaders,
+    })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    logForDebugging(`[SSHAuthProxy] upstream error: ${message}`)
+    return new Response(
+      JSON.stringify({ error: `Proxy upstream error: ${message}` }),
+      { status: 502, headers: { 'content-type': 'application/json' } },
+    )
+  }
+}
+
+export async function createAuthProxy(): Promise<AuthProxyInfo> {
+  const id = randomUUID()
+
+  if (isWindows) {
+    return createTcpAuthProxy(id)
+  }
+  return createUnixSocketAuthProxy(id)
+}
+
+async function createUnixSocketAuthProxy(id: string): Promise<AuthProxyInfo> {
+  const socketPath = `/tmp/claude-ssh-auth-${id}.sock`
+
+  const server = Bun.serve({
+    unix: socketPath,
+    fetch: req => proxyFetch(req, null),
+  })
+
+  logForDebugging(`[SSHAuthProxy] listening on unix:${socketPath}`)
+
+  const proxy: SSHAuthProxy = {
+    stop() {
+      server.stop(true)
+      try {
+        unlinkSync(socketPath)
+      } catch {
+        // Socket file may already be cleaned up
+      }
+    },
+  }
+
+  return {
+    proxy,
+    localAddress: socketPath,
+    authEnv: { ANTHROPIC_AUTH_SOCKET: socketPath },
+  }
+}
+
+async function createTcpAuthProxy(id: string): Promise<AuthProxyInfo> {
+  const nonce = randomUUID()
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+    fetch: req => proxyFetch(req, nonce),
+  })
+
+  const port = server.port
+  logForDebugging(
+    `[SSHAuthProxy] listening on TCP 127.0.0.1:${port} (nonce-protected)`,
+  )
+
+  const proxy: SSHAuthProxy = {
+    stop() {
+      server.stop(true)
+    },
+  }
+
+  return {
+    proxy,
+    localAddress: `127.0.0.1:${port}`,
+    authEnv: {
+      ANTHROPIC_BASE_URL: `http://127.0.0.1:${port}`,
+      ANTHROPIC_AUTH_NONCE: nonce,
+    },
+  }
+}

src/ssh/SSHAuthProxy.ts

@@ -0,0 +1,123 @@
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+import { logForDebugging } from 'src/utils/debug.js'
+
+const SSH_TIMEOUT_MS = 60_000
+const REMOTE_BIN_DIR = '~/.local/bin'
+const REMOTE_CLI_FILE = 'claude-code-cli.js'
+const REMOTE_WRAPPER = 'claude'
+
+export interface DeployOptions {
+  host: string
+  remotePlatform: string
+  remoteArch: string
+  localVersion: string
+  onProgress?: (msg: string) => void
+}
+
+async function runSshCommand(
+  host: string,
+  command: string,
+  timeoutMs = SSH_TIMEOUT_MS,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(['ssh', '-o', 'ConnectTimeout=10', host, command], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+
+  const timer = setTimeout(() => proc.kill(), timeoutMs)
+
+  try {
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    const exitCode = await proc.exited
+    return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function findLocalBinary(): string {
+  const projectRoot = resolve(import.meta.dir, '../..')
+  const distPath = resolve(projectRoot, 'dist/cli.js')
+  if (existsSync(distPath)) return distPath
+
+  const devPath = resolve(projectRoot, 'src/entrypoints/cli.tsx')
+  if (existsSync(devPath)) return devPath
+
+  throw new Error(
+    'Cannot find local CLI binary to deploy. Run `bun run build` first.',
+  )
+}
+
+export async function deployBinary(options: DeployOptions): Promise<string> {
+  const { host, remotePlatform, remoteArch, localVersion, onProgress } = options
+
+  if (remotePlatform !== 'linux' && remotePlatform !== 'darwin') {
+    throw new Error(
+      `Remote platform "${remotePlatform}" is not supported. Only linux and darwin are supported.`,
+    )
+  }
+
+  logForDebugging(
+    `[SSHDeploy] deploying to ${host} (${remotePlatform}/${remoteArch}, v${localVersion})`,
+  )
+
+  const localBinary = findLocalBinary()
+  logForDebugging(`[SSHDeploy] local binary: ${localBinary}`)
+
+  onProgress?.('Creating remote directory...')
+  const mkdirResult = await runSshCommand(host, `mkdir -p ${REMOTE_BIN_DIR}`)
+  if (mkdirResult.exitCode !== 0) {
+    throw new Error(`Failed to create remote directory: ${mkdirResult.stderr}`)
+  }
+
+  onProgress?.('Uploading binary...')
+  const remotePath = `${REMOTE_BIN_DIR}/${REMOTE_CLI_FILE}`
+  const scpProc = Bun.spawn(
+    ['scp', '-o', 'ConnectTimeout=10', localBinary, `${host}:${remotePath}`],
+    { stdout: 'pipe', stderr: 'pipe' },
+  )
+  const scpTimer = setTimeout(() => scpProc.kill(), SSH_TIMEOUT_MS)
+  const scpStderr = await new Response(scpProc.stderr).text()
+  const scpExit = await scpProc.exited
+  clearTimeout(scpTimer)
+
+  if (scpExit !== 0) {
+    throw new Error(`SCP upload failed (exit ${scpExit}): ${scpStderr.trim()}`)
+  }
+
+  onProgress?.('Installing wrapper script...')
+  const wrapperScript = [
+    `cat > ${REMOTE_BIN_DIR}/${REMOTE_WRAPPER} << 'WRAPPER'`,
+    '#!/bin/sh',
+    `exec bun ${REMOTE_BIN_DIR}/${REMOTE_CLI_FILE} "$@"`,
+    'WRAPPER',
+    `chmod +x ${REMOTE_BIN_DIR}/${REMOTE_WRAPPER}`,
+  ].join('\n')
+
+  const wrapperResult = await runSshCommand(host, wrapperScript)
+  if (wrapperResult.exitCode !== 0) {
+    throw new Error(`Failed to install wrapper script: ${wrapperResult.stderr}`)
+  }
+
+  onProgress?.('Verifying installation...')
+  const verifyResult = await runSshCommand(
+    host,
+    `${REMOTE_BIN_DIR}/${REMOTE_WRAPPER} --version`,
+  )
+  if (verifyResult.exitCode !== 0) {
+    throw new Error(
+      `Binary deployed but verification failed (exit ${verifyResult.exitCode}): ${verifyResult.stderr}`,
+    )
+  }
+
+  logForDebugging(
+    `[SSHDeploy] deployed successfully, remote version: ${verifyResult.stdout}`,
+  )
+  onProgress?.(`Deployed v${verifyResult.stdout}`)
+
+  return `${REMOTE_BIN_DIR}/${REMOTE_WRAPPER}`
+}