@lengmoxxl/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lengmoXXL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @lengmoxxl/sdk
+The client SDK for [WangCai](https://github.com/lengmoXXL/WangCai), the terminal app. It reaches a machine, the one
+the app runs on or one over SSH, and drives its terminals, files and subprocesses through a single connection.
+
+A WangCai plugin compiles against this package, but at load time the app injects its own copy of this module, so a
+plugin never carries its own connection pool.
+
+## Install
+
+```
+npm install @lengmoxxl/sdk
+```
+
+`ws` is the only runtime dependency. The bundled `dist/index.cjs` reads it at require time.
+
+## Use
+
+```ts
+import { connect } from '@lengmoxxl/sdk';
+
+const connection = await connect({ type: 'local', binary: '/path/to/wangcai' });
+
+const sessions = await connection.pty.list();
+const session = await connection.pty.create({ rows: 24, cols: 80 }, '/repo');
+const terminal = await connection.pty.attach(session.id);
+terminal.onData(({ data }) => process.stdout.write(data));
+await terminal.write('git status\n');
+
+const { stdout } = await connection.subprocess.exec('git', ['status'], { cwd: '/repo' });
+connection.disconnect();
+```
+
+`connect` returns a `MachineConnection`. Connections are shared per target and reference counted, so two callers
+asking for the same SSH host drive one tunnel; the last `disconnect()` tears it down. `connect({ type: 'ssh', host,
+agent })` installs the carrier agent on the host first when `agent` is given.
+
+- `connection.pty` - `list`, `cwd`, `create`, `attach`, `close`
+- `connection.fs` - `stat`, `readDirectory`, `readFile`
+- `connection.subprocess` - `exec`, which returns `{ stdout, stderr, code }` as `Uint8Array`
+- `connection.onState` - connection status and the sessions it can see
+
+The host-side context a plugin is activated with (`MainContext`, `UiContext`, `Bus`, and the workspace protocol
+types) lives in the `@lengmoxxl/sdk/channel` entry. That entry is types only.
+
+## Build
+
+```
+npm run build
+```
+
+From the repository root (the TypeScript and esbuild devDependencies live in the workspace root): esbuild bundles
+`index.ts` into `dist/index.cjs` with `ws` left external, then `tsc` emits the declarations. `npm publish` and
+`npm pack` run it for you.

package/dist/agent.d.ts

@@ -0,0 +1,5 @@
+import type { AgentInfo } from './types';
+export declare function agentCommand(command: string): string;
+export declare function ensureAgent(host: string, { version, prefix, signal }: AgentInfo & {
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/channel.d.ts

@@ -0,0 +1,56 @@
+import type { AgentInfo } from './types';
+export type Dispose = () => void | Promise<void>;
+/** A sidebar tab the window opens for a plugin: what it is called, and what it draws. */
+export interface TabOptions {
+    id: string;
+    title: string;
+    tooltip?: string;
+    workspaceId?: string;
+    onClose?(): void;
+    mount(container: HTMLElement): TabContent;
+}
+export interface TabContent {
+    dispose: Dispose;
+    onSelect?(): void;
+}
+/** A tab the window remembers from the last run, so the plugin can open it again. */
+export interface TabRecord {
+    plugin: string;
+    id: string;
+    workspaceId?: string;
+}
+/** The bus every plugin shares: what one publishes reaches the others, in either realm. */
+export interface Bus {
+    publish(topic: string, data: unknown): Promise<void>;
+    subscribe<T>(topic: string, callback: (data: T) => void | Promise<void>): () => void;
+}
+/** What a main.cjs gets: the methods its own ui.js calls, and the machine it runs on. */
+export interface MainContext {
+    global: Bus;
+    ui: {
+        handle<T = unknown>(method: string, handler: (params: T) => unknown): Dispose;
+        publish(topic: string, data: unknown): void;
+    };
+    host: {
+        dataDirectory: string;
+        resourcesDirectory: string;
+        agent: AgentInfo;
+        config: any;
+    };
+}
+/** What a ui.js gets: its plugin's methods, and the window it is drawn in. */
+export interface UiContext {
+    global: Bus;
+    ui: {
+        request<T = unknown>(method: string, params?: unknown): Promise<T>;
+        subscribe<T>(topic: string, callback: (data: T) => void | Promise<void>): () => void;
+    };
+    host: {
+        config: any;
+        preview: {
+            url: string;
+            message: string;
+        };
+        tabs(options: TabOptions): void;
+    };
+}

package/dist/connection.d.ts

@@ -0,0 +1,51 @@
+import type { ConnectionOptions, MachineState, Session, Size, DirectoryEntry, ExecOptions, ExecResult } from './types';
+import { Pty } from './pty';
+export declare class MachineConnection {
+    private options;
+    private listeners;
+    private terminals;
+    private instance?;
+    readonly ready: Promise<void>;
+    private resolveReady;
+    private rejectReady;
+    state: MachineState;
+    private ws?;
+    private tunnel?;
+    private retry?;
+    private heartbeat?;
+    private pending;
+    private stopped;
+    private attempt;
+    private epoch;
+    private serial;
+    private refs;
+    constructor(options: ConnectionOptions);
+    onState(callback: (state: MachineState) => void): () => void;
+    private publish;
+    retain(): void;
+    disconnect(): void;
+    private teardown;
+    pty: {
+        list: () => Promise<Session[]>;
+        cwd: (id: string) => Promise<string>;
+        create: (size?: Size, cwd?: string) => Promise<Session>;
+        attach: (id: string) => Promise<Pty>;
+        close: (id: string) => Promise<void>;
+    };
+    fs: {
+        stat: (path: string) => Promise<{
+            isDirectory: boolean;
+        } | null>;
+        readDirectory: (path: string) => Promise<DirectoryEntry[]>;
+        readFile: (path: string) => Promise<Uint8Array>;
+    };
+    subprocess: {
+        exec: (program: string, args: string[], options: ExecOptions) => Promise<ExecResult>;
+    };
+    private cleanup;
+    private fail;
+    private open;
+    private forward;
+    private request;
+    private refresh;
+}

package/dist/index.cjs

@@ -0,0 +1,520 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  connect: () => connect,
+  ensureAgent: () => ensureAgent
+});
+module.exports = __toCommonJS(index_exports);
+
+// connection.ts
+var import_node_child_process2 = require("node:child_process");
+var import_node_net = require("node:net");
+var import_node_util2 = require("node:util");
+var import_ws = __toESM(require("ws"));
+
+// pty.ts
+var Pty = class {
+  constructor(id, request, remove) {
+    this.id = id;
+    this.request = request;
+    this.remove = remove;
+  }
+  sequence = -1;
+  error;
+  snapshot;
+  buffered = [];
+  snapshots = /* @__PURE__ */ new Set();
+  outputs = /* @__PURE__ */ new Set();
+  receive(event) {
+    if (this.error) return;
+    if (event.event === "snapshot") {
+      this.sequence = event.seq;
+      this.buffered = [];
+      this.snapshot = event;
+      for (const callback of this.snapshots) callback(event);
+      return;
+    }
+    if (event.seq <= this.sequence) return;
+    this.sequence = event.seq;
+    if (!this.outputs.size) this.buffered.push(event);
+    for (const callback of this.outputs) callback(event);
+  }
+  onSnapshot(callback) {
+    this.snapshots.add(callback);
+    if (this.snapshot) callback(this.snapshot);
+    return () => {
+      this.snapshots.delete(callback);
+    };
+  }
+  onData(callback) {
+    this.outputs.add(callback);
+    for (const event of this.buffered) callback(event);
+    this.buffered = [];
+    return () => {
+      this.outputs.delete(callback);
+    };
+  }
+  async write(data) {
+    if (this.error) throw this.error;
+    const parts = Array.from(data);
+    const requests = [];
+    for (let offset = 0; offset < parts.length; offset += 8e3) {
+      requests.push(this.request("input", { session_id: this.id, data: parts.slice(offset, offset + 8e3).join("") }));
+    }
+    await Promise.all(requests);
+  }
+  async resize(size) {
+    if (this.error) throw this.error;
+    await this.request("resize", { session_id: this.id, ...size });
+  }
+  async detach() {
+    if (this.error) return;
+    this.remove();
+    this.release();
+    await this.request("detach", { session_id: this.id });
+  }
+  release(error = new Error("Terminal detached")) {
+    this.error = error;
+    this.snapshots.clear();
+    this.outputs.clear();
+    this.snapshot = void 0;
+    this.buffered = [];
+  }
+};
+
+// agent.ts
+var import_node_child_process = require("node:child_process");
+var import_node_util = require("node:util");
+var exec = (0, import_node_util.promisify)(import_node_child_process.execFile);
+function agentCommand(command) {
+  const home = process.env.WANGCAI_HOME;
+  const exportHome = home ? `export WANGCAI_HOME='${home.replace(/'/g, String.raw`'\''`)}'; ` : "";
+  return `${exportHome}export PATH="$HOME/.local/bin:$PATH"; ${command}`;
+}
+async function ensureAgent(host, { version, prefix, signal }) {
+  const targets = {
+    "Darwin x86_64": "x86_64-apple-darwin",
+    "Darwin arm64": "aarch64-apple-darwin",
+    "Linux x86_64": "x86_64-unknown-linux-musl"
+  };
+  const remote = (command) => ["-T", "-o", "BatchMode=yes", "-o", "ConnectTimeout=8", host, command];
+  const probe = await exec("ssh", remote(agentCommand("uname -s -m; wangcai --version 2>/dev/null; true")), { timeout: 3e4, signal }).catch(() => void 0);
+  const [platform, installed] = (probe?.stdout ?? "").split("\n").map((line) => line.trim());
+  if (!platform) return;
+  const target = targets[platform];
+  if (!target) throw new Error(`${platform} \u4E0A\u6682\u4E0D\u652F\u6301\u81EA\u52A8\u5B89\u88C5 agent`);
+  if (installed === `wangcai ${version}`) return;
+  const response = await fetch(`${prefix}/v${version}/wangcai-${target}`, { signal });
+  if (!response.ok) throw new Error(`\u4E0B\u8F7D agent \u5931\u8D25\uFF1A${response.status} ${response.statusText}`);
+  const binary = Buffer.from(await response.arrayBuffer());
+  await new Promise((resolve, reject) => {
+    const child = (0, import_node_child_process.spawn)("ssh", remote("mkdir -p ~/.local/bin && cat > ~/.local/bin/.wangcai.tmp && chmod 755 ~/.local/bin/.wangcai.tmp && mv ~/.local/bin/.wangcai.tmp ~/.local/bin/wangcai"), { stdio: ["pipe", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => code === 0 ? resolve() : reject(new Error(stderr.trim() || `\u5199\u5165 agent \u5931\u8D25\uFF08ssh \u9000\u51FA\u7801 ${code}\uFF09`)));
+    child.stdin.end(binary);
+  });
+}
+
+// connection.ts
+var exec2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
+var MachineConnection = class {
+  constructor(options) {
+    this.options = options;
+    this.state = { status: "connecting", sessions: [], generation: 0 };
+    this.ready = new Promise((resolve, reject) => {
+      this.resolveReady = resolve;
+      this.rejectReady = reject;
+    });
+    void this.open();
+  }
+  listeners = /* @__PURE__ */ new Set();
+  terminals = /* @__PURE__ */ new Map();
+  instance;
+  ready;
+  resolveReady;
+  rejectReady;
+  state;
+  ws;
+  tunnel;
+  retry;
+  heartbeat;
+  pending = /* @__PURE__ */ new Map();
+  stopped = false;
+  attempt = 0;
+  epoch = 0;
+  serial = 0;
+  refs = 1;
+  onState(callback) {
+    this.listeners.add(callback);
+    callback({ ...this.state });
+    return () => {
+      this.listeners.delete(callback);
+    };
+  }
+  publish() {
+    for (const callback of this.listeners) callback({ ...this.state });
+  }
+  retain() {
+    this.refs++;
+  }
+  disconnect() {
+    if (this.refs === 0) return;
+    if (--this.refs > 0) return;
+    this.teardown();
+  }
+  teardown() {
+    this.refs = 0;
+    this.stopped = true;
+    this.cleanup();
+    this.rejectReady(new Error("Connection cancelled"));
+    for (const terminal of this.terminals.values()) terminal.release();
+    this.terminals.clear();
+    this.state.status = "disconnected";
+    this.state.error = void 0;
+    this.publish();
+    this.listeners.clear();
+  }
+  pty = {
+    list: () => this.request("list"),
+    cwd: (id) => this.request("cwd", { session_id: id }),
+    create: (size = { rows: 24, cols: 80 }, cwd) => this.request("create", { ...size, cwd }),
+    attach: async (id) => {
+      const existing = this.terminals.get(id);
+      if (existing) return existing;
+      const terminal = new Pty(id, (op, params) => this.request(op, params), () => {
+        this.terminals.delete(id);
+      });
+      this.terminals.set(id, terminal);
+      try {
+        await this.request("attach", { session_id: id });
+      } catch (error) {
+        this.terminals.delete(id);
+        terminal.release();
+        throw error;
+      }
+      return terminal;
+    },
+    close: async (id) => {
+      await this.request("close", { session_id: id });
+      this.terminals.get(id)?.release();
+      this.terminals.delete(id);
+    }
+  };
+  fs = {
+    stat: (path) => this.request("stat", { path }),
+    readDirectory: (path) => this.request("read_directory", { path }),
+    readFile: async (path) => {
+      const result = await this.request("read_file", { path });
+      return Buffer.from(result.data, "base64");
+    }
+  };
+  subprocess = {
+    exec: async (program, args, options) => {
+      const result = await this.request("exec", { program, args, ...options }, 2e4);
+      return { stdout: Buffer.from(result.stdout, "base64"), stderr: Buffer.from(result.stderr, "base64"), code: result.code };
+    }
+  };
+  cleanup() {
+    this.epoch++;
+    clearTimeout(this.retry);
+    clearInterval(this.heartbeat);
+    const socket = this.ws;
+    this.ws = void 0;
+    socket?.terminate();
+    this.tunnel?.kill();
+    this.tunnel = void 0;
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Connection lost; input was not replayed."));
+    }
+    this.pending.clear();
+  }
+  fail(error) {
+    if (this.stopped) return;
+    if (this.state.generation === 0) {
+      this.rejectReady(error instanceof Error ? error : new Error(String(error)));
+      this.teardown();
+      return;
+    }
+    this.cleanup();
+    this.state.status = "connecting";
+    this.state.error = error instanceof Error ? error.message : String(error);
+    this.publish();
+    this.retry = setTimeout(() => void this.open(), Math.min(1e3 * 2 ** this.attempt++, 15e3));
+  }
+  async open() {
+    const epoch = ++this.epoch;
+    const current = () => !this.stopped && this.epoch === epoch;
+    this.state.status = "connecting";
+    this.publish();
+    try {
+      let info;
+      let port;
+      if (this.options.type === "local") {
+        const { stdout } = await exec2(this.options.binary ?? "wangcai", ["server", "start", "--json"], { timeout: 15e3 });
+        info = JSON.parse(stdout);
+        port = info.port;
+      } else {
+        if (this.options.agent) await ensureAgent(this.options.host, { ...this.options.agent, signal: this.options.signal });
+        const { stdout } = await exec2("ssh", [
+          "-T",
+          "-o",
+          "BatchMode=yes",
+          "-o",
+          "ConnectTimeout=8",
+          this.options.host,
+          agentCommand("wangcai server start --json")
+        ], { timeout: 15e3, maxBuffer: 64 * 1024 });
+        info = JSON.parse(stdout);
+        if (!Number.isInteger(info.port) || info.port < 1 || info.port > 65535) throw new Error("Node returned an invalid port.");
+        if (!current()) return;
+        port = await this.forward(info.port, current);
+      }
+      if (!current()) return;
+      const socket = new import_ws.default(`ws://127.0.0.1:${port}`, { handshakeTimeout: 5e3, maxPayload: 64 * 1024 * 1024 });
+      this.ws = socket;
+      socket.on("message", (data, binary) => {
+        if (!current()) return;
+        try {
+          if (binary) {
+            const bytes = data;
+            const length = bytes.readUInt32BE(0);
+            if (length > bytes.length - 4) throw new Error("Invalid terminal packet");
+            const header = JSON.parse(bytes.subarray(4, 4 + length).toString());
+            this.terminals.get(header.session_id)?.receive({ ...header, data: bytes.subarray(4 + length) });
+          } else {
+            const message = JSON.parse(data.toString());
+            if (message.id) {
+              const pending = this.pending.get(message.id);
+              if (!pending) return;
+              clearTimeout(pending.timer);
+              this.pending.delete(message.id);
+              if (message.error) pending.reject(new Error(message.error));
+              else pending.resolve(message.result);
+            } else if (message.event === "sessions_changed") {
+              void this.refresh().catch(() => {
+              });
+            }
+          }
+        } catch (error) {
+          this.fail(error);
+        }
+      });
+      socket.on("error", () => {
+      });
+      await new Promise((resolve, reject) => {
+        socket.once("open", resolve);
+        socket.once("error", reject);
+      });
+      if (!current()) {
+        socket.terminate();
+        return;
+      }
+      socket.on("close", () => {
+        if (current()) this.fail(new Error("Disconnected. Reconnecting\u2026"));
+      });
+      const actual = await this.request("info");
+      if (actual.instance_id !== info.instance_id || actual.protocol !== 1) throw new Error("Node instance or protocol mismatch.");
+      await this.refresh();
+      if (!current()) return;
+      if (this.instance && this.instance !== actual.instance_id) {
+        for (const terminal of this.terminals.values()) terminal.release(new Error("Node restarted; terminal no longer exists"));
+        this.terminals.clear();
+      }
+      this.instance = actual.instance_id;
+      for (const [id, terminal] of this.terminals) {
+        try {
+          await this.request("attach", { session_id: id });
+        } catch (error) {
+          if (!current()) return;
+          terminal.release(error);
+          this.terminals.delete(id);
+        }
+      }
+      if (!current()) return;
+      this.state.status = "connected";
+      this.state.error = void 0;
+      this.state.generation++;
+      this.attempt = 0;
+      this.resolveReady();
+      this.publish();
+      let alive = true;
+      socket.on("pong", () => {
+        alive = true;
+      });
+      this.heartbeat = setInterval(() => {
+        if (!alive) {
+          this.fail(new Error("Node stopped responding. Reconnecting\u2026"));
+          return;
+        }
+        alive = false;
+        socket.ping();
+      }, 1e4);
+    } catch (error) {
+      if (current()) this.fail(error);
+    }
+  }
+  async forward(remotePort, current) {
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (!current()) throw new Error("Connection cancelled");
+      const reservation = (0, import_node_net.createServer)();
+      await new Promise((resolve, reject) => {
+        reservation.once("error", reject);
+        reservation.listen(0, "127.0.0.1", resolve);
+      });
+      const port = reservation.address().port;
+      await new Promise((resolve) => reservation.close(() => resolve()));
+      if (!current()) throw new Error("Connection cancelled");
+      const tunnel = (0, import_node_child_process2.spawn)("ssh", [
+        "-N",
+        "-T",
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        "ExitOnForwardFailure=yes",
+        "-o",
+        "ConnectTimeout=8",
+        "-o",
+        "ServerAliveInterval=10",
+        "-o",
+        "ServerAliveCountMax=2",
+        "-L",
+        `127.0.0.1:${port}:127.0.0.1:${remotePort}`,
+        this.options.host
+      ], { stdio: ["ignore", "ignore", "pipe"] });
+      this.tunnel = tunnel;
+      let stderr = "";
+      tunnel.stderr.on("data", (data) => {
+        stderr = (stderr + data.toString()).slice(-4096);
+      });
+      try {
+        await new Promise((resolve, reject) => {
+          let finished = false;
+          const finish = (error) => {
+            if (finished) return;
+            finished = true;
+            clearInterval(poll);
+            clearTimeout(timeout);
+            tunnel.off("exit", exited);
+            if (error) reject(error);
+            else resolve();
+          };
+          const exited = () => finish(new Error(stderr.trim() || "SSH tunnel exited."));
+          const poll = setInterval(() => {
+            if (!current()) {
+              finish(new Error("Connection cancelled"));
+              return;
+            }
+            const probe = (0, import_node_net.createConnection)({ host: "127.0.0.1", port });
+            probe.once("connect", () => {
+              probe.destroy();
+              finish();
+            });
+            probe.once("error", () => probe.destroy());
+            probe.setTimeout(200, () => probe.destroy());
+          }, 100);
+          const timeout = setTimeout(() => finish(new Error(stderr.trim() || "SSH tunnel timed out.")), 1e4);
+          tunnel.once("exit", exited);
+          tunnel.once("error", finish);
+        });
+        tunnel.on("exit", () => {
+          if (current()) this.fail(new Error(stderr.trim() || "SSH tunnel closed."));
+        });
+        return port;
+      } catch (error) {
+        tunnel.kill();
+        if (this.tunnel === tunnel) this.tunnel = void 0;
+        lastError = error;
+        if (!/address already in use|cannot listen to port|port forwarding failed/i.test(String(error))) throw error;
+      }
+    }
+    throw lastError;
+  }
+  async request(op, params = {}, timeout = 1e4) {
+    const socket = this.ws;
+    if (!socket || socket.readyState !== import_ws.default.OPEN) throw new Error("Machine is not connected.");
+    const id = String(++this.serial);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${op} timed out; it was not retried.`));
+      }, timeout);
+      this.pending.set(id, { resolve, reject, timer });
+      socket.send(JSON.stringify({ ...params, op, id }), (error) => {
+        if (!error) return;
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error);
+      });
+    });
+  }
+  async refresh() {
+    this.state.sessions = await this.request("list");
+    this.publish();
+  }
+};
+
+// index.ts
+var connections = /* @__PURE__ */ new Map();
+async function connect(options) {
+  options.signal?.throwIfAborted();
+  const target = options.type === "ssh" ? `ssh:${options.host}` : `local:${options.binary ?? "wangcai"}`;
+  const shared = connections.get(target);
+  const machine = shared ?? new MachineConnection(options);
+  if (shared) machine.retain();
+  else {
+    connections.set(target, machine);
+    machine.onState((state) => {
+      if (state.status === "disconnected" && connections.get(target) === machine) connections.delete(target);
+    });
+  }
+  const aborted = new Promise((_, reject) => {
+    options.signal?.addEventListener("abort", () => reject(new Error("Connection cancelled")), { once: true });
+  });
+  try {
+    await Promise.race([machine.ready, aborted]);
+    return machine;
+  } catch (error) {
+    machine.disconnect();
+    throw error;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  connect,
+  ensureAgent
+});

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { MachineConnection } from './connection';
+import type { ConnectionOptions } from './types';
+export type { AgentInfo, ConnectionOptions, FileClick, Machine, MachineState, Session, Size, Output, Snapshot, TerminalEvent, DirectoryEntry, ExecOptions, ExecResult, Profile, Theme, WorkspaceActive, WorkspaceRow, WorkspaceMenuItem } from './types';
+export type { MachineConnection } from './connection';
+export type { Pty } from './pty';
+export { ensureAgent } from './agent';
+export declare function connect(options: ConnectionOptions): Promise<MachineConnection>;

package/dist/pty.d.ts

@@ -0,0 +1,20 @@
+import type { Output, Snapshot, TerminalEvent, Size } from './types';
+export declare class Pty {
+    readonly id: string;
+    private request;
+    private remove;
+    private sequence;
+    private error?;
+    private snapshot?;
+    private buffered;
+    private snapshots;
+    private outputs;
+    constructor(id: string, request: (op: string, params: Record<string, unknown>) => Promise<unknown>, remove: () => void);
+    receive(event: TerminalEvent): void;
+    onSnapshot(callback: (event: Snapshot) => void): () => void;
+    onData(callback: (event: Output) => void): () => void;
+    write(data: string): Promise<void>;
+    resize(size: Size): Promise<void>;
+    detach(): Promise<void>;
+    release(error?: Error): void;
+}

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+export interface AgentInfo {
+    version: string;
+    prefix: string;
+}
+/**
+ * The workspace protocol. A plugin that init.ts lists under `workspaces` is a workspace provider, and
+ * the app drives it through these `ui` methods:
+ *
+ *   workspaces()              -> WorkspaceRow[]        one flat row per workspace, in draw order
+ *   workspace-menu()          -> WorkspaceMenuItem[]   what the menu offers to open; an entry that carries
+ *                                                      an error stays listed but is not clickable
+ *   workspace-create({ key }) -> { id: string }        the id of the workspace it made
+ *   workspace-select({ id })
+ *   workspace-close({ id })
+ *   workspace-move({ id, before? })
+ *
+ * Every view that follows the workspace in front shares these channel topics, whatever the provider
+ * behind it is:
+ *
+ *   'workspaces'       a provider published that its rows changed
+ *   'workspace:active' the workspace in front, or null; published by its provider
+ *   'workspace:query'  a view asks for 'workspace:active' again
+ */
+export interface WorkspaceRow {
+    id: string;
+    label: string;
+    machine: string;
+    running: boolean;
+}
+export interface WorkspaceMenuItem {
+    key: string;
+    label: string;
+    hint?: string;
+    error?: string;
+}
+export interface Machine {
+    id: string;
+    name: string;
+    host?: string;
+}
+export interface WorkspaceActive {
+    machine: Machine;
+    sessionId: string;
+    workspaceId: string;
+}
+/** Where a click on a file or a directory points, as the 'onclick' topic carries it. */
+export interface FileClick {
+    type: 'file' | 'directory';
+    machine: Machine;
+    path: string;
+    line?: number;
+    column?: number;
+}
+export type ConnectionOptions = {
+    type: 'local';
+    binary?: string;
+    signal?: AbortSignal;
+} | {
+    type: 'ssh';
+    host: string;
+    agent?: AgentInfo;
+    signal?: AbortSignal;
+};
+export interface Size {
+    rows: number;
+    cols: number;
+}
+export interface Session extends Size {
+    id: string;
+    title: string;
+    pid: number;
+    exit_code: number | null;
+}
+export interface MachineState {
+    status: 'disconnected' | 'connecting' | 'connected';
+    error?: string;
+    sessions: Session[];
+    generation: number;
+}
+export interface Output {
+    data: Uint8Array;
+    seq: number;
+}
+export interface Snapshot extends Output, Size {
+}
+export type TerminalEvent = ({
+    event: 'snapshot';
+} & Snapshot | {
+    event: 'output';
+} & Output) & {
+    session_id: string;
+};
+export interface DirectoryEntry {
+    name: string;
+    isDirectory: boolean;
+}
+export interface ExecOptions {
+    cwd: string;
+    env?: Record<string, string>;
+}
+export interface ExecResult {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    code: number;
+}
+export interface Theme {
+    background: string;
+    foreground: string;
+    cursor: string;
+    selection: string;
+    surface: string;
+    overlay: string;
+    border: string;
+    muted: string;
+    accent: string;
+    black: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    magenta: string;
+    cyan: string;
+    white: string;
+    brightBlack: string;
+    brightRed: string;
+    brightGreen: string;
+    brightYellow: string;
+    brightBlue: string;
+    brightMagenta: string;
+    brightCyan: string;
+    brightWhite: string;
+}
+export interface Profile {
+    theme: Theme;
+    agent: {
+        downloadPrefix: string;
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@lengmoxxl/sdk",
+  "version": "0.1.0",
+  "description": "Client SDK for WangCai: connect to a local or remote machine and drive its pty, files and git",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lengmoXXL/WangCai.git",
+    "directory": "sdk"
+  },
+  "keywords": [
+    "wangcai",
+    "pty",
+    "ssh",
+    "terminal",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "main": "dist/index.cjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.cjs"
+    },
+    "./channel": {
+      "types": "./dist/channel.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "esbuild index.ts --outfile=dist/index.cjs --bundle --platform=node --target=node22 --packages=external && tsc",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.9.0",
+    "esbuild": "^0.25.0"
+  }
+}