@lengmoxxl/sdk 0.1.3 → 0.1.5

package/README.md

@@ -1,54 +1,152 @@
-# @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.
+# @lengmoxxl/sdk：接口参考
 
-A WangCai plugin compiles against this package for the types it uses; the machines belong to the app, which keeps
-one connection per machine and hands it to every plugin that asks for one.
+本参考对应 SDK `0.1.5`：连接本机或 SSH 机器上的旺财后台进程，提供终端、文件与子进程
+操作。插件入口与生命周期见 [插件开发手册](../docs/plugins.md)，进程关系见
+[架构说明](../docs/architecture.md)。
 
-## Install
+## 插件上下文
 
-```
-npm install @lengmoxxl/sdk
-```
+| 成员 | 说明 |
+| --- | --- |
+| `global` | 公共 `Bus`，跨插件与前后端通信 |
+| `ui.handle<T>(method, handler)` | 后端注册方法，返回取消注册的 `Dispose` |
+| `ui.publish(topic, data)` | 后端向本插件 UI 发事件，对应前端 `ui.subscribe` |
+| `ui.subscribe<T>(topic, callback)` | 前端订阅本插件后端事件，返回取消订阅的函数 |
+| `ui.request<T>(method, params?)` | 前端调用本插件后端方法，返回 `Promise<T>` |
+| `connect(machine, signal?)` | 后端借用机器连接：`{ host?: string }`，可带 `AbortSignal` |
+| `host.dataDirectory` / `host.config` | 插件私有数据目录 / 本插件设置 |
+| `host.tabs(options)` / `host.open(url)` | 前端开侧栏标签页 / 用系统浏览器打开 http、https |
+| `host.preview` | `{ url, message }`，HTML 预览 frame 的地址与握手消息 |
 
-`ws` is the only runtime dependency. The bundled `dist/index.cjs` reads it at require time.
+请求与事件传可结构化克隆的数据，不传函数、DOM、Pty 或连接实例。
 
-## Use
+`ui.handle` 注册的方法名不能含 `:`；`ui.publish` 与 `ui.subscribe` 的主题由宿主加插件 id 前缀，
+`global` 用原始主题，自定义主题要自己加命名空间（如 `directory-demo:opened`）。
 
-```ts
-import { openMachine } from '@lengmoxxl/sdk';
+`connect({})` 连接本机，`connect({ host })` 连接 SSH。
 
-const connection = await openMachine({ type: 'local', binary: '/path/to/wangcai' });
+宿主为相同机器复用连接并计数，每次取得连接对应一次 `disconnect()`。
 
-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');
+`Dispose = () => void | Promise<void>`，卸载时清理资源，不要关闭用户仍要保留的 PTY。
 
-const { stdout } = await connection.subprocess.exec('git', ['status'], { cwd: '/repo' });
-connection.disconnect();
-```
+`Bus`：`publish(topic, data): Promise<void>`、`subscribe<T>(topic, callback): () => void`。
 
-`openMachine` returns a `MachineConnection`; every call opens its own. Sharing one belongs to the caller: a
-connection is reference counted, so callers that hand the same one around keep it alive until the last
-`disconnect()`. `openMachine({ type: 'ssh', host, agent })` installs the carrier agent on the host first when
-`agent` is given.
+`host.dataDirectory` 默认 `~/.local/share/wangcai/data/<plugin-id>`。
 
-- `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
+`host.config` 是浅合并，避免把自定义字段命名为 `theme`，配色键见
+[README 主题参数](../README.md#主题参数)。
 
-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
+`host.tabs({ id, title, tooltip?, workspaceId?, onClose?, mount })`：`id`、`title` 必填，
+`tooltip?` 是标签上的悬停提示（缺省用 `title`），`workspaceId` 缺省用当前工作区；
+`mount(container)` 返回的 `TabContent.dispose` 必填，`onSelect?` 在选中、工作区刷新或侧栏重新显示时
+都可能调用，`onClose?` 在移除标签页时先于 `dispose` 调用。
 
+相同插件 id、工作区 id、标签 id 再次调用 `host.tabs` 会复用并选中；尚无工作区时打开的标签页
+会在第一个工作区激活时绑定到它。
+
+`TabRecord = { plugin, id, workspaceId? }` 只保存身份，插件的 `open(context, record)` 据此恢复
+内容，资源必须仍在。
+
+## 预览
+
+用 `host.preview.url` 建 iframe，设 `sandbox="allow-scripts"`，不要加
+`allow-same-origin`；收到来源为该 frame、`event.data === host.preview.message` 的消息后
+`postMessage(html, '*')`。预览会执行其中脚本。
+
+## 插件配置
+
+插件 `config` 是嵌套对象，叶子声明 `type` 与可选 `default`；宿主只保留 schema 声明的键，
+缺失或类型不符时取 default，`array` 内部条目由插件自己验证。
+
+## 工作区协议
+
+放入 init.ts `workspaces` 的插件用 `ui.handle` 提供：`workspaces()`（`WorkspaceRow[]`，
+按显示顺序）、`workspace-menu()`（`WorkspaceMenuItem[]`）、`workspace-create({ key })`
+（返回 `{ id }`）、`workspace-select({ id })`、`workspace-close({ id })`、
+`workspace-move({ id, before? })`（`before` 是目标工作区 id，不是索引；省略为末尾，且只
+允许同一 provider 内拖动）。
+
+provider 要保证工作区 id 在所有 provider 的行中唯一识别；`error` 由 provider 给出并在重试成功后清除，
+宿主不禁用带 `error` 的菜单项。
+
+约定的公共主题：`workspaces`（行变化，App 重新请求列表）、`workspace:active`
+（`WorkspaceActive | null`，provider 发布）、`workspace:query`（视图请求 provider 再发布
+当前工作区）、`onclick`（`FileClick`）。
+
+字段类型见 SDK 导出的 `WorkspaceRow`、`WorkspaceMenuItem`、`Machine`、`WorkspaceActive`
+与 `FileClick`，定义在 `sdk/types.ts`。
+
+## 机器、终端与子进程
+
+`MachineConnection`：`ready`（首次连接就绪）、`state`、`port`（本地 loopback 端口，SSH 时
+为转发端口）、`onState(callback)`、`retain()`（连接层使用）、`disconnect()`，以及 `pty`、`fs`、
+`subprocess`。
+
+`MachineState` 含 `status`、`error?`、`sessions`、`generation`。
+
+断线会自动重连并重新 attach 已挂载的终端与进程，失败的请求与输入不自动重放，后台进程重启时旧 Pty 与进程失效。
+
+`connection.pty`：`list()`、`cwd(id)`、`create(size?, cwd?)`（默认 24 行 80 列；cwd 用绝对目录，
+省略时在后台进程的 HOME 下启动）、`attach(id)`（复用句柄）、`close(id)`（结束 shell 与后台子孙进程）。
+
+`Size` 用整数：rows 2–300，cols 2–500。
+
+`Session` 有 `id, title`、`pid, rows, cols`、`exit_code: number | null`。
+
+`Pty`：`id`、`onSnapshot(callback)`、`onData(callback)`、`write(data)`、`resize(size)`、
+`detach()`（停止挂载，不关闭 shell）。
+
+`Output = { data: Uint8Array; seq: number }`，`Snapshot` 额外有 `rows, cols`。
+
+字节含终端控制序列，交给终端模拟器，不要把快照当键盘输入重发。
+
+`receive` 与 `release(error?)` 由连接层使用。
+
+`connection.fs`：`stat(path)` 返回 `{ isDirectory: boolean } | null`、`readDirectory(path)` 返回
+`DirectoryEntry[]`（`{ name, isDirectory }`）、`readFile(path)` 返回原始字节。
+
+路径为绝对路径，`readFile` 上限 16 MiB；SDK 不提供写入、删除或上传接口。
+
+`connection.subprocess.exec(program, args, options)`：`args` 是独立 argv（不经 shell 展开），
+`options.cwd` 是绝对工作目录，`options.env` 覆盖继承的环境变量；返回
+`{ stdout: Uint8Array; stderr: Uint8Array; code: number }`。非零退出码仍返回结果，无法启动、
+超时、输出超限或被信号终止时 reject；stdin 关闭，长时间或交互用 `subprocess.spawn` 或 PTY。
+
+执行上限 15 秒，SDK 等待响应上限 20 秒，stdout 与 stderr 各最多 8 MiB，断线取消未完成的 exec。
+
+`connection.subprocess.spawn(program, args, options)`（`options` 同 `exec`）启动一个
+长期存活的进程，stdin、stdout、stderr 都是管道，返回 `ProcessInfo = { id, pid, exit_code }`；
+`attach(id)` 复用句柄（未 attach 前不接收输出），`close(id)` 结束进程及其进程组；进程归后台进程所有，不 `close` 就一直留着。
+
+`Process`：`id`、`onData(callback)`、`onExit(callback)`、`write(data)`。
+
+`ProcessOutput = { data: Uint8Array; seq: number; stream: 'stdout' | 'stderr' }`，两路输出各自按序到达，
+`seq` 单调递增，跨两路的先后以 `seq` 为准。
+
+`onExit` 给出退出码（被信号结束时按 shell 的 128+signal），节点来不及投递时给出 `undefined`，此时
+输出流已不可信，进程可能仍在运行，请重新 `spawn`。
+
+`write` 按 32 KiB 分片、按序应用，进程退出后 reject；先 `attach` 再写。
+
+`receive` 与 `release(error?)` 由连接层使用。
+
+## 独立 Node 客户端
+
+App 插件用 `context.connect`；插件之外才调用 `openMachine`：
+
+```ts
+import { openMachine } from '@lengmoxxl/sdk';
+
+const connection = await openMachine({ type: 'local', binary: '/path/to/wangcai' });
+await connection.fs.readDirectory('/');
+connection.disconnect();
 ```
-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.
+`openMachine` 返回 `Promise<MachineConnection>`。`type` 为 `'local'` 或 `'ssh'`；local 可给
+`binary`，ssh 必须给 `host`（系统 ssh 目标或别名）与可选 `agent`（`InstallAgent`），两者
+都可给 `signal`。不传 `agent` 时 SDK 不下载二进制；连接用 BatchMode SSH。
+
+`agentCommand(command)` 返回拼接后的 shell 命令：在 PATH 前加入远端 `$HOME/.local/bin`，
+并携带当前进程的 WANGCAI_HOME（会转义；command 本身不转义，只传可信命令）。

package/dist/agent.d.ts

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

package/dist/connection.d.ts

@@ -1,9 +1,12 @@
-import type { ConnectionOptions, MachineState, Session, Size, DirectoryEntry, ExecOptions, ExecResult } from './types';
+import type { ConnectionOptions, MachineState, Session, Size, DirectoryEntry, ExecOptions, ExecResult, ProcessInfo } from './types';
+import { Process } from './process';
 import { Pty } from './pty';
 export declare class MachineConnection {
     private options;
     private listeners;
     private terminals;
+    private processes;
+    port?: number;
     private instance?;
     readonly ready: Promise<void>;
     private resolveReady;
@@ -41,6 +44,9 @@ export declare class MachineConnection {
     };
     subprocess: {
         exec: (program: string, args: string[], options: ExecOptions) => Promise<ExecResult>;
+        spawn: (program: string, args: string[], options: ExecOptions) => Promise<ProcessInfo>;
+        attach: (id: string) => Promise<Process>;
+        close: (id: string) => Promise<void>;
     };
     private cleanup;
     private fail;

package/dist/index.cjs

@@ -30,16 +30,79 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // index.ts
 var index_exports = {};
 __export(index_exports, {
+  agentCommand: () => agentCommand,
   openMachine: () => openMachine
 });
 module.exports = __toCommonJS(index_exports);
 
 // connection.ts
-var import_node_child_process2 = require("node:child_process");
+var import_node_child_process = require("node:child_process");
 var import_node_net = require("node:net");
-var import_node_util2 = require("node:util");
+var import_node_util = require("node:util");
 var import_ws = __toESM(require("ws"));
 
+// process.ts
+var CHUNK = 32 * 1024;
+var Process = class {
+  constructor(id, request) {
+    this.id = id;
+    this.request = request;
+  }
+  sequence = -1;
+  error;
+  ended = false;
+  code;
+  buffered = [];
+  outputs = /* @__PURE__ */ new Set();
+  exits = /* @__PURE__ */ new Set();
+  receive(event) {
+    if (this.error) return;
+    if (event.event === "exit" || event.event === "lost") {
+      this.ended = true;
+      this.code = event.event === "exit" ? event.code : void 0;
+      for (const callback of this.exits) callback(this.code);
+      this.exits.clear();
+      return;
+    }
+    if (event.seq <= this.sequence) return;
+    this.sequence = event.seq;
+    const output = { data: event.data, seq: event.seq, stream: event.event };
+    if (!this.outputs.size) this.buffered.push(output);
+    for (const callback of this.outputs) callback(output);
+  }
+  onData(callback) {
+    this.outputs.add(callback);
+    for (const event of this.buffered) callback(event);
+    this.buffered = [];
+    return () => {
+      this.outputs.delete(callback);
+    };
+  }
+  /** Its exit code, or nothing when the node lost the stream and the process may still be running. */
+  onExit(callback) {
+    this.exits.add(callback);
+    if (this.ended) callback(this.code);
+    return () => {
+      this.exits.delete(callback);
+    };
+  }
+  async write(data) {
+    if (this.error) throw this.error;
+    const requests = [];
+    for (let offset = 0; offset < data.length; offset += CHUNK) {
+      const chunk = Buffer.from(data.subarray(offset, offset + CHUNK)).toString("base64");
+      requests.push(this.request("process_write", { session_id: this.id, data: chunk }));
+    }
+    await Promise.all(requests);
+  }
+  release(error = new Error("Process detached")) {
+    this.error = error;
+    this.outputs.clear();
+    this.exits.clear();
+    this.buffered = [];
+  }
+};
+
 // pty.ts
 var Pty = class {
   constructor(id, request, remove) {
@@ -111,61 +174,14 @@ var Pty = class {
 };
 
 // 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);
-var DOWNLOAD_TIMEOUT = 3e4;
 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, prefixes, 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 failures = [];
-  for (const prefix of prefixes) {
-    signal?.throwIfAborted();
-    const url = `${prefix}/v${version}/wangcai-${target}`;
-    const deadline = AbortSignal.timeout(DOWNLOAD_TIMEOUT);
-    let binary;
-    try {
-      const response = await fetch(url, { signal: signal ? AbortSignal.any([signal, deadline]) : deadline });
-      if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-      binary = Buffer.from(await response.arrayBuffer());
-    } catch (error) {
-      failures.push(`${url}
-${error instanceof Error ? error.message : String(error)}`);
-      continue;
-    }
-    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);
-    });
-    return;
-  }
-  throw new Error(`\u4E0B\u8F7D agent \u5931\u8D25\uFF1A
-${failures.join("\n\n")}`);
-}
 
 // connection.ts
-var exec2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
+var exec = (0, import_node_util.promisify)(import_node_child_process.execFile);
 var MachineConnection = class {
   constructor(options) {
     this.options = options;
@@ -178,6 +194,9 @@ var MachineConnection = class {
   }
   listeners = /* @__PURE__ */ new Set();
   terminals = /* @__PURE__ */ new Map();
+  processes = /* @__PURE__ */ new Map();
+  // Where the daemon listens: the window reaches it with this.
+  port;
   instance;
   ready;
   resolveReady;
@@ -218,6 +237,8 @@ var MachineConnection = class {
     this.rejectReady(new Error("Connection cancelled"));
     for (const terminal of this.terminals.values()) terminal.release();
     this.terminals.clear();
+    for (const process2 of this.processes.values()) process2.release();
+    this.processes.clear();
     this.state.status = "disconnected";
     this.state.error = void 0;
     this.publish();
@@ -261,6 +282,26 @@ var MachineConnection = class {
     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 };
+    },
+    spawn: (program, args, options) => this.request("spawn", { program, args, ...options }),
+    attach: async (id) => {
+      const existing = this.processes.get(id);
+      if (existing) return existing;
+      const process2 = new Process(id, (op, params) => this.request(op, params));
+      this.processes.set(id, process2);
+      try {
+        await this.request("process_attach", { session_id: id });
+      } catch (error) {
+        this.processes.delete(id);
+        process2.release();
+        throw error;
+      }
+      return process2;
+    },
+    close: async (id) => {
+      await this.request("process_close", { session_id: id });
+      this.processes.get(id)?.release();
+      this.processes.delete(id);
     }
   };
   cleanup() {
@@ -300,12 +341,12 @@ var MachineConnection = class {
       let info;
       let port;
       if (this.options.type === "local") {
-        const { stdout } = await exec2(this.options.binary ?? "wangcai", ["server", "start", "--json"], { timeout: 15e3 });
+        const { stdout } = await exec(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", [
+        if (this.options.agent) await this.options.agent(this.options.host, this.options.signal);
+        const { stdout } = await exec("ssh", [
           "-T",
           "-o",
           "BatchMode=yes",
@@ -319,6 +360,7 @@ var MachineConnection = class {
         if (!current()) return;
         port = await this.forward(info.port, current);
       }
+      this.port = port;
       if (!current()) return;
       const socket = new import_ws.default(`ws://127.0.0.1:${port}`, { handshakeTimeout: 5e3, maxPayload: 64 * 1024 * 1024 });
       this.ws = socket;
@@ -328,9 +370,12 @@ var MachineConnection = class {
           if (binary) {
             const bytes = data;
             const length = bytes.readUInt32BE(0);
-            if (length > bytes.length - 4) throw new Error("Invalid terminal packet");
+            if (length > bytes.length - 4) throw new Error("Invalid packet");
             const header = JSON.parse(bytes.subarray(4, 4 + length).toString());
-            this.terminals.get(header.session_id)?.receive({ ...header, data: bytes.subarray(4 + length) });
+            const event = { ...header, data: bytes.subarray(4 + length) };
+            const terminal = this.terminals.get(header.session_id);
+            if (terminal) terminal.receive(event);
+            else this.processes.get(header.session_id)?.receive(event);
           } else {
             const message = JSON.parse(data.toString());
             if (message.id) {
@@ -369,6 +414,8 @@ var MachineConnection = class {
       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();
+        for (const process2 of this.processes.values()) process2.release(new Error("Node restarted; process no longer exists"));
+        this.processes.clear();
       }
       this.instance = actual.instance_id;
       for (const [id, terminal] of this.terminals) {
@@ -380,6 +427,15 @@ var MachineConnection = class {
           this.terminals.delete(id);
         }
       }
+      for (const [id, process2] of this.processes) {
+        try {
+          await this.request("process_attach", { session_id: id });
+        } catch (error) {
+          if (!current()) return;
+          process2.release(error);
+          this.processes.delete(id);
+        }
+      }
       if (!current()) return;
       this.state.status = "connected";
       this.state.error = void 0;
@@ -415,7 +471,7 @@ var MachineConnection = class {
       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", [
+      const tunnel = (0, import_node_child_process.spawn)("ssh", [
         "-N",
         "-T",
         "-o",
@@ -521,5 +577,6 @@ async function openMachine(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  agentCommand,
   openMachine
 });

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 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 { agentCommand } from './agent';
+export type { ConnectionOptions, FileClick, Machine, MachineState, Session, Size, Output, Snapshot, TerminalEvent, DirectoryEntry, ExecOptions, ExecResult, ProcessEvent, ProcessInfo, ProcessOutput, InstallAgent, Profile, Theme, WorkspaceActive, WorkspaceRow, WorkspaceMenuItem } from './types';
 export type { MachineConnection } from './connection';
+export type { Process } from './process';
 export type { Pty } from './pty';
 /** Opens one connection to a machine and waits for it to be ready. */
 export declare function openMachine(options: ConnectionOptions): Promise<MachineConnection>;

package/dist/process.d.ts

@@ -0,0 +1,19 @@
+import type { ProcessEvent, ProcessOutput } from './types';
+export declare class Process {
+    readonly id: string;
+    private request;
+    private sequence;
+    private error?;
+    private ended;
+    private code?;
+    private buffered;
+    private outputs;
+    private exits;
+    constructor(id: string, request: (op: string, params: Record<string, unknown>) => Promise<unknown>);
+    receive(event: ProcessEvent): void;
+    onData(callback: (event: ProcessOutput) => void): () => void;
+    /** Its exit code, or nothing when the node lost the stream and the process may still be running. */
+    onExit(callback: (code?: number) => void): () => void;
+    write(data: Uint8Array): Promise<void>;
+    release(error?: Error): void;
+}

package/dist/types.d.ts

@@ -1,14 +1,12 @@
-export interface AgentInfo {
-    version: string;
-    prefixes: string[];
-}
+/** What puts the agent on an ssh machine, which the SDK calls before it connects to it. */
+export type InstallAgent = (host: string, signal?: AbortSignal) => Promise<void>;
 /**
  * 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
+ *                                                      an error stays listed with its reason, and a click retries it
  *   workspace-create({ key }) -> { id: string }        the id of the workspace it made
  *   workspace-select({ id })
  *   workspace-close({ id })
@@ -58,7 +56,7 @@ export type ConnectionOptions = {
 } | {
     type: 'ssh';
     host: string;
-    agent?: AgentInfo;
+    agent?: InstallAgent;
     signal?: AbortSignal;
 };
 export interface Size {
@@ -90,6 +88,26 @@ export type TerminalEvent = ({
 } & Output) & {
     session_id: string;
 };
+export interface ProcessInfo {
+    id: string;
+    pid: number;
+    exit_code: number | null;
+}
+/** `stream` names the pipe the bytes came from. */
+export interface ProcessOutput extends Output {
+    stream: 'stdout' | 'stderr';
+}
+export type ProcessEvent = ({
+    event: 'stdout' | 'stderr';
+} & Output | {
+    event: 'exit';
+    seq: number;
+    code: number;
+} | {
+    event: 'lost';
+}) & {
+    session_id: string;
+};
 export interface DirectoryEntry {
     name: string;
     isDirectory: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lengmoxxl/sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Client SDK for WangCai: connect to a local or remote machine and drive its pty, files and git",
   "license": "MIT",
   "repository": {