@tunnelbox/core 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @tunnelbox/core
+
+tunnelbox 共享核心，供各智能体适配器复用：
+
+| 模块 | 说明 |
+|---|---|
+| `types.ts` | 统一协议类型 + `envelope()`（与 relay/web 镜像互通） |
+| `relay.ts` | `RelayClient`：出站 WS + 指数退避**静默**重连 |
+| `state.ts` | 状态持久化（`remote-state[.type].json`，多 agent 隔离）+ 配对文件 |
+| `qr.ts` | `printPairing`：终端二维码 + 配对码打印 |
+
+## 使用
+
+```ts
+import { RelayClient, envelope, loadState, printPairing } from "@tunnelbox/core";
+
+const state = loadState("dsh"); // 多智能体：各适配器独立状态文件
+const ws = new RelayClient();
+ws.connect(`${state.relayUrl}/ws/agent`, { Authorization: `Bearer ${state.agentId}` }, { … });
+ws.send(envelope("agent.info", { name: "host", type: "dsh", version: "0.1.0" }));
+```
+
+消费方（`plugin/opencode` / `plugin/dsh-tunnelbox` / 各适配器）通过 bundler（esbuild/vite）直接打包本包 TS 源码；无需独立构建步骤。

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tunnelbox/core",
+  "version": "0.1.0",
+  "description": "tunnelbox 共享核心：协议类型、中继客户端、状态持久化、二维码配对",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/qrcode": "^1.5.5",
+    "typescript": "^5.4.5"
+  }
+}

package/src/globals.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 共享核心运行环境（Bun/Node）全局类型补充。不引入 DOM lib，仅声明用到的 WebSocket 成员。
+ */
+interface WebSocket {
+  onopen: (() => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onerror: ((err: unknown) => void) | null;
+  onclose: (() => void) | null;
+  send(data: string): void;
+  close(): void;
+}
+
+declare const WebSocket: {
+  new (url: string, protocolsOrOptions?: unknown): WebSocket;
+};

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @tunnelbox/core —— 共享核心。
+ * 供各智能体适配器（opencode 插件 / dsh / claude-code / codex / …）复用：
+ * 统一协议类型、中继客户端（静默重连）、状态持久化、二维码配对。
+ */
+export * from "./types";
+export * from "./relay";
+export * from "./state";
+export * from "./qr";

package/src/qr.ts

@@ -0,0 +1,42 @@
+/**
+ * 终端二维码与配对信息打印。qrcode 为可选依赖，失败时降级为链接。
+ */
+import { writePairingFile } from "./state";
+
+export async function printPairing(
+  relayHttpBase: string,
+  code: string,
+  type?: string,
+  name?: string,
+): Promise<void> {
+  const p = new URLSearchParams({ code });
+  if (type) p.set("type", type);
+  if (name) p.set("name", name);
+  const link = `${relayHttpBase}/app/#/pages/index/index?${p.toString()}`;
+  const file = writePairingFile(link, code, type);
+  const tag = type ? ` ${type}` : "";
+
+  console.log("");
+  console.log("┌──────────────────────────────────────────────────────────┐");
+  console.log(`│                tunnelbox${tag} 手机配对               │`);
+  console.log("├──────────────────────────────────────────────────────────┤");
+  console.log(`│  配对码: ${code.padEnd(42)} │`);
+  console.log(`│  链接  : ${link.padEnd(42)} │`);
+  console.log("└──────────────────────────────────────────────────────────┘");
+  console.log("  手机浏览器打开链接，或打开 App 后手动输入配对码。");
+
+  try {
+    const mod = await import("qrcode");
+    const render = (mod as { default?: unknown }).default ?? mod;
+    const toString = (render as { toString?: (text: string, opts: unknown) => Promise<string> }).toString;
+    if (toString) {
+      const qr = await toString(link, { type: "terminal", small: true });
+      if (qr) console.log(qr);
+    }
+  } catch {
+    console.log("  （未安装 qrcode，请使用上方链接或配对码）");
+  }
+
+  console.log(`  配对信息已写入: ${file}`);
+  console.log("");
+}

package/src/relay.ts

@@ -0,0 +1,106 @@
+/**
+ * 出站 WebSocket 客户端（连接中继 /ws/agent），带指数退避自动重连。
+ * 使用运行时全局 WebSocket（Bun/Node ≥21 均可用）。各智能体适配器共用。
+ */
+import type { Envelope } from "./types";
+
+export interface RelayClientHandlers {
+  onOpen: () => void;
+  onMessage: (env: Envelope) => void;
+  onClose: () => void;
+  onError: (err: unknown) => void;
+}
+
+const BASE_DELAY = 1000;
+const MAX_DELAY = 15000;
+
+export class RelayClient {
+  private ws: WebSocket | null = null;
+  private url = "";
+  private headers: Record<string, string> = {};
+  private handlers: RelayClientHandlers | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private retry = 0;
+  private stopped = false;
+  private connected = false;
+
+  get isConnected(): boolean {
+    return this.connected;
+  }
+
+  connect(url: string, headers: Record<string, string>, handlers: RelayClientHandlers): void {
+    this.url = url;
+    this.headers = headers;
+    this.handlers = handlers;
+    this.stopped = false;
+    this.retry = 0;
+    this.open();
+  }
+
+  send(env: Envelope): boolean {
+    if (this.ws && this.connected) {
+      try {
+        this.ws.send(JSON.stringify(env));
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+
+  close(): void {
+    this.stopped = true;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {
+        /* ignore */
+      }
+    }
+    this.ws = null;
+    this.connected = false;
+  }
+
+  private open(): void {
+    if (this.stopped) return;
+    try {
+      // 部分运行时 WebSocket 不支持 headers 选项；中继同时支持 URL query token 作为兜底。
+      const ws = new WebSocket(this.url, { headers: this.headers }) as WebSocket;
+      this.ws = ws;
+
+      ws.onopen = () => {
+        this.connected = true;
+        this.retry = 0;
+        this.handlers?.onOpen();
+      };
+      ws.onmessage = (ev) => {
+        try {
+          const msg = JSON.parse(String(ev.data)) as Envelope;
+          this.handlers?.onMessage(msg);
+        } catch {
+          /* 忽略非 JSON 帧 */
+        }
+      };
+      ws.onerror = (e) => this.handlers?.onError(e);
+      ws.onclose = () => {
+        this.connected = false;
+        this.ws = null;
+        this.handlers?.onClose();
+        this.scheduleReconnect();
+      };
+    } catch (e) {
+      this.handlers?.onError(e);
+      this.scheduleReconnect();
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.stopped) return;
+    const delay = Math.min(BASE_DELAY * 2 ** this.retry, MAX_DELAY);
+    this.retry++;
+    this.timer = setTimeout(() => this.open(), delay);
+  }
+}

package/src/state.ts

@@ -0,0 +1,105 @@
+/**
+ * 本地状态持久化。默认存于 opencode 全局配置目录；支持按智能体类型隔离文件
+ * （多 agent 同机时各适配器使用独立文件：remote-state.<type>.json）。
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * 默认中继地址（按环境区分，生产部署建议用 opencode.json 或
+ * TUNNELBOX_RELAY_URL 显式配置，优先级最高）：
+ *  - 生产（NODE_ENV=production）：wss://chat.wxngrok.com
+ *  - 开发/其他：ws://127.0.0.1:8080
+ */
+export const DEFAULT_RELAY_URL =
+  process.env.TUNNELBOX_RELAY_URL ||
+  (process.env.NODE_ENV === "production" ? "wss://chat.wxngrok.com" : "ws://127.0.0.1:8080");
+
+export interface State {
+  agentId: string;
+  relayUrl: string;
+  /** 账号体系（Phase 1）：是否已被手机账号认领。认领后不再自动申请配对码。 */
+  claimed?: boolean;
+}
+
+function baseName(): string {
+  return join(homedir(), ".config", "opencode");
+}
+
+function suffix(type?: string): string {
+  return type ? `.${type}` : "";
+}
+
+export function statePath(type?: string): string {
+  return join(baseName(), `remote-state${suffix(type)}.json`);
+}
+
+export function saveState(st: State, type?: string): void {
+  try {
+    const p = statePath(type);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(st, null, 2), "utf8");
+  } catch (e) {
+    console.error("[tunnelbox] 保存状态失败", e);
+  }
+}
+
+/** 读取状态；不存在时生成新 agentID 并持久化。 */
+export function loadState(type?: string): State {
+  const fallback: State = {
+    agentId: randomBytes(16).toString("hex"),
+    relayUrl: DEFAULT_RELAY_URL,
+  };
+  try {
+    if (!existsSync(statePath(type))) {
+      saveState(fallback, type);
+      return fallback;
+    }
+    const parsed = JSON.parse(readFileSync(statePath(type), "utf8")) as Partial<State>;
+    if (parsed.agentId && parsed.agentId.length >= 16) {
+      return {
+        agentId: parsed.agentId,
+        relayUrl: parsed.relayUrl || DEFAULT_RELAY_URL,
+        claimed: parsed.claimed === true,
+      };
+    }
+    saveState(fallback, type);
+    return fallback;
+  } catch {
+    saveState(fallback, type);
+    return fallback;
+  }
+}
+
+/** 把配对信息写入本地文件，作为终端日志被吞时的兜底。 */
+export function writePairingFile(link: string, code: string, type?: string): string {
+  const p = join(baseName(), `remote-pairing${suffix(type)}.txt`);
+  try {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, `配对码: ${code}\n配对链接: ${link}\n`, "utf8");
+  } catch {
+    /* ignore */
+  }
+  return p;
+}
+
+export interface PairingInfo {
+  code: string;
+  link: string;
+  relayUrl: string;
+  at: number;
+}
+
+/** 把最新配对信息写入 JSON（供配套 UI/工具读取）。 */
+export function writePairingJson(info: PairingInfo, type?: string): string {
+  const p = join(baseName(), `remote-pairing${suffix(type)}.json`);
+  try {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(info, null, 2), "utf8");
+  } catch {
+    /* ignore */
+  }
+  return p;
+}

package/src/types.ts

@@ -0,0 +1,127 @@
+/**
+ * tunnelbox 统一协议类型（各智能体适配器共享）。
+ * 与 relay/internal/proto、web/src/protocol 通过 JSON 互通（镜像维护）。
+ */
+
+export interface Envelope<T = unknown> {
+  id?: string;
+  type: string;
+  payload: T;
+  ts: number;
+  /** 中继注入/回填：手机端会话 id，用于回路由 */
+  clientID?: string;
+}
+
+export function envelope<T>(type: string, payload: T, id?: string): Envelope<T> {
+  return { id, type, payload, ts: Date.now() };
+}
+
+export interface AgentInfo {
+  name: string;
+  version: string;
+  platform?: string;
+  directory?: string;
+  /** 智能体类型：opencode | claude-code | codex | dsh | openclaw | hermes | cursor */
+  type?: string;
+  /** IANA 时区名（如 Asia/Shanghai），仅用于"电脑本地时间"展示 */
+  timezone?: string;
+  /** 能力位 */
+  capabilities?: {
+    streaming?: boolean;
+    thinking?: boolean;
+    permission?: boolean;
+    commands?: boolean;
+    abort?: boolean;
+  };
+}
+
+export type SessionStatus = "queued" | "running" | "idle" | "error";
+
+export interface SessionInfo {
+  id: string;
+  title: string;
+  created: number;
+  updated: number;
+  status: SessionStatus;
+  /** 会话所在工作区目录（dsh 按 workspace 分目录持久化） */
+  workspace?: string;
+}
+
+export interface WorkspaceInfo {
+  /** 工作区目录绝对路径 */
+  path: string;
+  /** 展示名（取目录名） */
+  name: string;
+  /** 该工作区内的会话数 */
+  sessionCount: number;
+  /** 最近会话更新时间 */
+  updated: number;
+}
+
+export interface Part {
+  id: string;
+  type: "text" | "tool" | "thinking";
+  text?: string;
+  delta?: string;
+  tool?: string;
+  args?: string;
+  complete?: boolean;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: "user" | "assistant" | "tool" | "system";
+  parts: Part[];
+  created: number;
+}
+
+/** 权限请求的作答方式：approval=允许/拒绝/总是允许；choice=从选项中选择；input=输入文本。 */
+export type PermissionKind = "approval" | "choice" | "input";
+
+export interface PermissionRequest {
+  id: string;
+  sessionID: string;
+  tool: string;
+  args: Record<string, unknown>;
+  prompt?: string;
+  createdAt: number;
+  /** 作答方式（缺省视为 approval） */
+  kind?: PermissionKind;
+  /** choice 类型的可选项（显示为按钮列表） */
+  options?: string[];
+}
+
+/** 结构化提问（opencode question.v2.asked 等）中的单条问题。 */
+export interface QuestionInfo {
+  question: string;
+  header?: string;
+  options: string[];
+  multiple?: boolean;
+  custom?: boolean;
+}
+
+export interface QuestionRequest {
+  id: string;
+  sessionID: string;
+  prompt?: string;
+  questions: QuestionInfo[];
+  createdAt: number;
+}
+
+export interface CommandInfo {
+  name: string;
+  description?: string;
+}
+
+/** 账号体系（Phase 1）：电脑被手机账号认领后 relay 下发。 */
+export interface AgentClaimedMessage {
+  email?: string;
+}
+
+/** 账号体系（Phase 1）：电脑被解绑后 relay 下发，适配器应重置并重新生成 agentID。 */
+export interface AgentRevokedMessage {}
+
+/** agent 断开后中继推送给已连接手机（在线信号为 agent.info 广播）。 */
+export interface AgentOfflineMessage {
+  agentID?: string;
+}