clawmatrix 0.1.22 → 0.2.0

package/src/audit.ts

@@ -0,0 +1,42 @@
+/** Structured audit logger for security events. */
+
+export type AuditEvent =
+  | "conn_open"        // New inbound WS connection
+  | "conn_rate_limited" // Connection rejected by rate limiter
+  | "auth_success"     // HMAC authentication succeeded
+  | "auth_failure"     // HMAC authentication failed
+  | "auth_timeout"     // Authentication timed out
+  | "peer_join"        // Peer joined the mesh
+  | "peer_leave"       // Peer left / disconnected
+  | "conn_close";      // Connection closed
+
+export interface AuditEntry {
+  ts: string;        // ISO timestamp
+  event: AuditEvent;
+  ip?: string;       // Remote IP (if available)
+  nodeId?: string;   // Remote nodeId (if known)
+  detail?: string;   // Extra context
+}
+
+export type AuditSink = (entry: AuditEntry) => void;
+
+/** Default sink: structured JSON to stderr via console.warn (won't mix with stdout output). */
+const defaultSink: AuditSink = (entry) => {
+  console.warn(`[clawmatrix:audit] ${JSON.stringify(entry)}`);
+};
+
+let sink: AuditSink = defaultSink;
+
+/** Replace the audit sink (e.g. to write to a file or external service). */
+export function setAuditSink(s: AuditSink) {
+  sink = s;
+}
+
+/** Emit an audit event. */
+export function audit(event: AuditEvent, fields?: Omit<AuditEntry, "ts" | "event">) {
+  sink({
+    ts: new Date().toISOString(),
+    event,
+    ...fields,
+  });
+}

package/src/auth.ts

@@ -1,3 +1,5 @@
+import { createHash, timingSafeEqual as nodeTimingSafeEqual } from "node:crypto";
+
 export function generateNonce(): string {
   const bytes = crypto.getRandomValues(new Uint8Array(32));
   return Buffer.from(bytes).toString("hex");
@@ -8,7 +10,6 @@ const KEY_CACHE_MAX = 8;
 const keyCache = new Map<string, CryptoKey>();
 
 function cacheKeyFor(secret: string): string {
-  const { createHash } = require("node:crypto");
   return createHash("sha256").update(secret).digest("hex");
 }
 
@@ -48,13 +49,11 @@ export async function computeHmac(
 /** Constant-time string comparison. Uses native crypto.timingSafeEqual with
  *  SHA-256 pre-hash to normalize lengths (avoids length-leak from early return). */
 export function timingSafeEqual(a: string, b: string): boolean {
-  const nodeTimingSafeEqual = require("node:crypto").timingSafeEqual;
   const encoder = new TextEncoder();
   const bufA = encoder.encode(a);
   const bufB = encoder.encode(b);
   if (bufA.byteLength !== bufB.byteLength) {
     // Hash both to fixed length so we still compare in constant time
-    const { createHash } = require("node:crypto");
     const hashA = createHash("sha256").update(bufA).digest();
     const hashB = createHash("sha256").update(bufB).digest();
     return nodeTimingSafeEqual(hashA, hashB);

package/src/cli.ts

@@ -1,8 +1,12 @@
 import type { Command } from "commander";
 import { spawnProcess } from "./compat.ts";
 
-async function callGateway(method: string): Promise<unknown> {
-  const proc = spawnProcess(["openclaw", "gateway", "call", method, "--json"], {
+async function callGateway(method: string, params?: Record<string, unknown>): Promise<unknown> {
+  const args = ["openclaw", "gateway", "call", method, "--json"];
+  if (params) {
+    args.push("--params", JSON.stringify(params));
+  }
+  const proc = spawnProcess(args, {
     stdout: "pipe",
     stderr: "pipe",
   });
@@ -161,4 +165,74 @@ export const registerClusterCli = ({ program }: { program: Command }) => {
       }
       console.log(JSON.stringify(peers, null, 2));
     });
+
+  // ── Peer approval commands ──────────────────────────────────────
+
+  cmd
+    .command("approve <approvalId>")
+    .description("Approve a pending peer join request")
+    .action(async (approvalId: string) => {
+      try {
+        const result = await callGateway("clawmatrix.approval.resolve", {
+          approvalId,
+          decision: "approve",
+        }) as Record<string, unknown>;
+        if (result.ok) {
+          console.log(`Approved: ${approvalId}`);
+        } else {
+          console.log(`Approval not found or already resolved: ${approvalId}`);
+        }
+      } catch {
+        console.log("Could not reach gateway. Is it running?");
+      }
+    });
+
+  cmd
+    .command("deny <approvalId>")
+    .description("Deny a pending peer join request")
+    .action(async (approvalId: string) => {
+      try {
+        const result = await callGateway("clawmatrix.approval.resolve", {
+          approvalId,
+          decision: "deny",
+        }) as Record<string, unknown>;
+        if (result.ok) {
+          console.log(`Denied: ${approvalId}`);
+        } else {
+          console.log(`Approval not found or already resolved: ${approvalId}`);
+        }
+      } catch {
+        console.log("Could not reach gateway. Is it running?");
+      }
+    });
+
+  const approval = cmd.command("approval").description("Manage peer approvals");
+
+  approval
+    .command("list")
+    .description("List approved and pending peers")
+    .action(async () => {
+      try {
+        const data = await callGateway("clawmatrix.approval.list") as Record<string, unknown>;
+        console.log(JSON.stringify(data, null, 2));
+      } catch {
+        console.log("Could not reach gateway. Is it running?");
+      }
+    });
+
+  approval
+    .command("revoke <nodeId>")
+    .description("Revoke an approved peer")
+    .action(async (nodeId: string) => {
+      try {
+        const result = await callGateway("clawmatrix.approval.revoke", { nodeId }) as Record<string, unknown>;
+        if (result.ok) {
+          console.log(`Revoked: ${nodeId}`);
+        } else {
+          console.log(`Node not found in approved list: ${nodeId}`);
+        }
+      } catch {
+        console.log("Could not reach gateway. Is it running?");
+      }
+    });
 };

package/src/cluster-service.ts

@@ -12,8 +12,11 @@ import { PeerManager } from "./peer-manager.ts";
 import { HandoffManager } from "./handoff.ts";
 import { ModelProxy } from "./model-proxy.ts";
 import { ToolProxy, type GatewayInfo } from "./tool-proxy.ts";
+import { AcpProxy, readAllSessionStoresFromDisk } from "./acp-proxy.ts";
+import { TerminalManager } from "./terminal.ts";
 import { WebHandler } from "./web.ts";
 import { KnowledgeSync } from "./knowledge-sync.ts";
+import { SentinelManager } from "./sentinel-manager.ts";
 import type {
   AnyClusterFrame,
   HandoffRequest,
@@ -31,6 +34,33 @@ import type {
   SendMessage,
   ToolProxyRequest,
   ToolProxyResponse,
+  ToolBatchRequest,
+  ToolBatchResponse,
+  DiagnosticExecResponse,
+  DiagnosticStatusResponse,
+  AcpTaskRequest,
+  AcpTaskResponse,
+  AcpStreamChunk,
+  AcpCloseRequest,
+  AcpCloseResponse,
+  AcpListRequest,
+  AcpListResponse,
+  AcpResumeRequest,
+  AcpResumeResponse,
+  AcpCancelRequest,
+  AcpCancelResponse,
+  AcpSetModeRequest,
+  AcpSetModeResponse,
+  AcpGetModesRequest,
+  AcpGetModesResponse,
+  ChatHistoryRequest,
+  ChatHistoryResponse,
+  TerminalOpenRequest,
+  TerminalOpenResponse,
+  TerminalData,
+  TerminalResize,
+  TerminalCloseRequest,
+  TerminalCloseResponse,
 } from "./types.ts";
 
 function resolveGatewayInfo(openclawConfig: OpenClawConfig): GatewayInfo {
@@ -52,10 +82,14 @@ export class ClusterRuntime {
   readonly handoffManager: HandoffManager;
   readonly modelProxy: ModelProxy;
   readonly toolProxy: ToolProxy;
+  readonly acpProxy: AcpProxy | null;
+  readonly terminalManager: TerminalManager;
   knowledgeSync: KnowledgeSync | null = null;
   webHandler: WebHandler | null = null;
+  private sentinelManager: SentinelManager | null = null;
   private logger: PluginLogger;
   private openclawConfig: OpenClawConfig;
+  private exitHandler: (() => void) | null = null;
 
   constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig, openclawVersion?: string) {
     this.config = config;
@@ -63,9 +97,13 @@ export class ClusterRuntime {
     this.openclawConfig = openclawConfig;
     const gatewayInfo = resolveGatewayInfo(openclawConfig);
     this.peerManager = new PeerManager(config, openclawVersion);
-    this.handoffManager = new HandoffManager(config, this.peerManager);
+    this.handoffManager = new HandoffManager(config, this.peerManager, gatewayInfo);
     this.modelProxy = new ModelProxy(config, this.peerManager, gatewayInfo, openclawConfig);
     this.toolProxy = new ToolProxy(config, this.peerManager, gatewayInfo, logger);
+    // Enable ACP proxy if either ClawMatrix config or OpenClaw config has ACP enabled
+    const acpEnabled = config.acp?.enabled || (openclawConfig as Record<string, any>).acp?.enabled;
+    this.acpProxy = acpEnabled ? new AcpProxy(config, this.peerManager, openclawConfig as Record<string, unknown>, gatewayInfo) : null;
+    this.terminalManager = new TerminalManager(config, this.peerManager);
   }
 
   start() {
@@ -76,10 +114,16 @@ export class ClusterRuntime {
 
     this.peerManager.on("peerConnected", (nodeId) => {
       this.logger.info(`[clawmatrix] Peer connected: ${nodeId}`);
+      this.refreshDiscoveredModels();
     });
 
     this.peerManager.on("peerDisconnected", (nodeId) => {
       this.logger.info(`[clawmatrix] Peer disconnected: ${nodeId}`);
+      this.refreshDiscoveredModels();
+    });
+
+    this.peerManager.on("peerCapabilitiesChanged", () => {
+      this.refreshDiscoveredModels();
     });
 
     // Web dashboard (must be set before peerManager.start() creates the HTTP server)
@@ -98,8 +142,9 @@ export class ClusterRuntime {
         const stateDir = path.join(workspacePath, ".clawmatrix");
         this.knowledgeSync = new KnowledgeSync({
           workspacePath,
-          storePath: path.join(stateDir, "knowledge.automerge"),
+          stateDir,
           nodeId: this.config.nodeId,
+          paths: this.config.knowledge.paths ?? [],
           debounce: this.config.knowledge.debounce ?? 5000,
           maxFileSize: this.config.knowledge.maxFileSize ?? 512 * 1024,
           peerManager: this.peerManager,
@@ -124,6 +169,22 @@ export class ClusterRuntime {
     this.peerManager.start();
     this.modelProxy.start();
 
+    // Sentinel: detached subprocess for diagnostics when gateway dies.
+    // Default on; starts when not explicitly disabled AND (has outbound peers OR gateway is a listener for port takeover)
+    if ((this.config.sentinel?.enabled ?? true) && (this.config.peers.length > 0 || this.config.listen)) {
+      this.sentinelManager = new SentinelManager(this.config);
+      this.sentinelManager.start();
+      this.logger.info(`[clawmatrix] Sentinel started for node "${this.config.nodeId}"`);
+    }
+
+    // Register process exit handlers for emergency cleanup (kill spawned ACP processes, close WS)
+    this.exitHandler = () => {
+      this.acpProxy?.destroy();
+      this.terminalManager.destroy();
+      this.handoffManager.destroy();
+    };
+    process.on("exit", this.exitHandler);
+
     this.logger.info(
       `[clawmatrix] Node "${this.config.nodeId}" started` +
         (this.config.listen ? ` (listening on port ${this.config.listenPort})` : "") +
@@ -132,15 +193,30 @@ export class ClusterRuntime {
   }
 
   async stop() {
+    // Unregister exit handler since we're doing a clean shutdown
+    if (this.exitHandler) {
+      process.removeListener("exit", this.exitHandler);
+      this.exitHandler = null;
+    }
+    // NOTE: intentionally do NOT stop sentinel here.
+    // Sentinel must survive gateway shutdown — that's its entire purpose.
+    // It will be replaced by killOldSentinel() on next gateway start.
     await this.knowledgeSync?.stop();
     this.webHandler?.destroy();
     this.handoffManager.destroy();
+    this.acpProxy?.destroy();
+    this.terminalManager.destroy();
     this.modelProxy.stop();
     this.toolProxy.destroy();
     await this.peerManager.stop();
     this.logger.info(`[clawmatrix] Node "${this.config.nodeId}" stopped`);
   }
 
+  private refreshDiscoveredModels() {
+    const peers = this.peerManager.router.getAllPeers();
+    this.modelProxy.updateDiscoveredModels(peers);
+  }
+
   private resolveWorkspacePath(): string | null {
     // Read workspace from OpenClaw agent config (first agent or default agent)
     const agents = (this.openclawConfig as Record<string, unknown>).agents as
@@ -160,7 +236,7 @@ export class ClusterRuntime {
   }
 
   private dispatchFrame(frame: AnyClusterFrame) {
-    if (frame.type.startsWith("model_")) {
+    if (frame.type.startsWith("model_") || frame.type.startsWith("acp_")) {
       debug("dispatch", `${frame.type} id=${frame.id} from=${frame.from}`);
     }
     switch (frame.type) {
@@ -212,6 +288,14 @@ export class ClusterRuntime {
       case "tool_res":
         this.toolProxy.handleResponse(frame as ToolProxyResponse);
         break;
+      case "tool_batch_req":
+        this.toolProxy.handleBatchRequest(frame as ToolBatchRequest).catch((err) => {
+          this.logger.error(`[clawmatrix] Tool batch request error: ${err}`);
+        });
+        break;
+      case "tool_batch_res":
+        this.toolProxy.handleBatchResponse(frame as ToolBatchResponse);
+        break;
       case "send":
         this.handleSendMessage(frame as SendMessage);
         break;
@@ -220,6 +304,162 @@ export class ClusterRuntime {
           this.logger.error(`[clawmatrix] Knowledge sync error: ${err}`);
         });
         break;
+      case "acp_req":
+        if (this.acpProxy) {
+          this.acpProxy.handleRequest(frame as AcpTaskRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP request error: ${err}`);
+          });
+        } else {
+          const af = frame as AcpTaskRequest;
+          this.peerManager.sendTo(af.from, {
+            type: "acp_res", id: af.id, from: this.config.nodeId, to: af.from,
+            timestamp: Date.now(), payload: { success: false, error: "ACP not enabled on this node" },
+          } as AcpTaskResponse);
+        }
+        break;
+      case "acp_stream":
+        this.acpProxy?.handleStream(frame as AcpStreamChunk);
+        break;
+      case "acp_res":
+        this.acpProxy?.handleResponse(frame as AcpTaskResponse);
+        break;
+      case "acp_close":
+        if (this.acpProxy) {
+          this.acpProxy.handleClose(frame as AcpCloseRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP close error: ${err}`);
+          });
+        } else {
+          const cf = frame as AcpCloseRequest;
+          this.peerManager.sendTo(cf.from, {
+            type: "acp_close_res", id: cf.id, from: this.config.nodeId, to: cf.from,
+            timestamp: Date.now(), payload: { success: false, error: "ACP not enabled on this node" },
+          } as AcpCloseResponse);
+        }
+        break;
+      case "acp_close_res":
+        this.acpProxy?.handleCloseResponse(frame as AcpCloseResponse);
+        break;
+      case "acp_list_req":
+        if (this.acpProxy) {
+          this.acpProxy.handleListRequest(frame as AcpListRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP list error: ${err}`);
+          });
+        } else {
+          // ACP not enabled — still read session stores from disk (read-only discovery)
+          const lf = frame as AcpListRequest;
+          readAllSessionStoresFromDisk().then((allSessions) => {
+            const filtered = lf.payload.agent
+              ? allSessions.filter((s) => s.agent === lf.payload.agent)
+              : allSessions;
+            this.peerManager.sendTo(lf.from, {
+              type: "acp_list_res", id: lf.id, from: this.config.nodeId, to: lf.from,
+              timestamp: Date.now(), payload: { success: true, sessions: filtered },
+            } as AcpListResponse);
+          }).catch(() => {
+            this.peerManager.sendTo(lf.from, {
+              type: "acp_list_res", id: lf.id, from: this.config.nodeId, to: lf.from,
+              timestamp: Date.now(), payload: { success: true, sessions: [] },
+            } as AcpListResponse);
+          });
+        }
+        break;
+      case "acp_list_res":
+        this.acpProxy?.handleListResponse(frame as AcpListResponse);
+        break;
+      case "acp_resume_req":
+        if (this.acpProxy) {
+          this.acpProxy.handleResumeRequest(frame as AcpResumeRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP resume error: ${err}`);
+          });
+        } else {
+          const rf = frame as AcpResumeRequest;
+          this.peerManager.sendTo(rf.from, {
+            type: "acp_resume_res", id: rf.id, from: this.config.nodeId, to: rf.from,
+            timestamp: Date.now(), payload: { success: false, error: "ACP not enabled on this node" },
+          } as AcpResumeResponse);
+        }
+        break;
+      case "acp_resume_res":
+        this.acpProxy?.handleResumeResponse(frame as AcpResumeResponse);
+        break;
+      case "acp_cancel":
+        if (this.acpProxy) {
+          this.acpProxy.handleCancelRequest(frame as AcpCancelRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP cancel error: ${err}`);
+          });
+        } else {
+          const cf = frame as AcpCancelRequest;
+          this.peerManager.sendTo(cf.from, {
+            type: "acp_cancel_res", id: cf.id, from: this.config.nodeId, to: cf.from,
+            timestamp: Date.now(), payload: { success: false, error: "ACP not enabled" },
+          } as AcpCancelResponse);
+        }
+        break;
+      case "acp_cancel_res":
+        this.acpProxy?.handleCancelResponse(frame as AcpCancelResponse);
+        break;
+      case "acp_set_mode":
+        if (this.acpProxy) {
+          this.acpProxy.handleSetModeRequest(frame as AcpSetModeRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP set mode error: ${err}`);
+          });
+        } else {
+          const mf = frame as AcpSetModeRequest;
+          this.peerManager.sendTo(mf.from, {
+            type: "acp_set_mode_res", id: mf.id, from: this.config.nodeId, to: mf.from,
+            timestamp: Date.now(), payload: { success: false, error: "ACP not enabled" },
+          } as AcpSetModeResponse);
+        }
+        break;
+      case "acp_set_mode_res":
+        this.acpProxy?.handleSetModeResponse(frame as AcpSetModeResponse);
+        break;
+      case "acp_get_modes":
+        if (this.acpProxy) {
+          this.acpProxy.handleGetModesRequest(frame as AcpGetModesRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP get modes error: ${err}`);
+          });
+        } else {
+          const gf = frame as AcpGetModesRequest;
+          this.peerManager.sendTo(gf.from, {
+            type: "acp_get_modes_res", id: gf.id, from: this.config.nodeId, to: gf.from,
+            timestamp: Date.now(), payload: { success: false, error: "ACP not enabled" },
+          } as AcpGetModesResponse);
+        }
+        break;
+      case "acp_get_modes_res":
+        this.acpProxy?.handleGetModesResponse(frame as AcpGetModesResponse);
+        break;
+      case "chat_history_req":
+        if (this.acpProxy) {
+          this.acpProxy.handleChatHistoryRequest(frame as ChatHistoryRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] Chat history request error: ${err}`);
+          });
+        } else {
+          const hf = frame as ChatHistoryRequest;
+          this.peerManager.sendTo(hf.from, {
+            type: "chat_history_res", id: hf.id, from: this.config.nodeId, to: hf.from,
+            timestamp: Date.now(), payload: { success: true, messages: [] },
+          } as ChatHistoryResponse);
+        }
+        break;
+      case "chat_history_res":
+        this.acpProxy?.handleChatHistoryResponse(frame as ChatHistoryResponse);
+        break;
+      case "task_activity":
+        // Task activity is a notification consumed by mobile clients directly.
+        // No server-side handling needed — relay is handled by PeerManager.
+        break;
+      case "terminal_open":
+      case "terminal_open_res":
+      case "terminal_data":
+      case "terminal_resize":
+      case "terminal_close":
+      case "terminal_close_res":
+        this.terminalManager.dispatchFrame(
+          frame as TerminalOpenRequest | TerminalOpenResponse | TerminalData | TerminalResize | TerminalCloseRequest | TerminalCloseResponse,
+        );
+        break;
     }
   }
 

package/src/compat.ts

@@ -16,12 +16,12 @@ export interface SpawnResult {
 /** Spawn a subprocess and collect stdout/stderr. */
 export function spawnProcess(
   cmd: string[],
-  opts?: { cwd?: string; stdout?: "pipe" | "ignore"; stderr?: "pipe" | "ignore" },
-): { exited: Promise<number>; stdout: ReadableStream | null; stderr: ReadableStream | null; kill: () => void } {
+  opts?: { cwd?: string; stdout?: "pipe" | "ignore"; stderr?: "pipe" | "ignore"; stdin?: "pipe" | "ignore" },
+): { exited: Promise<number>; stdout: ReadableStream | null; stderr: ReadableStream | null; stdin: WritableStream | null; kill: () => void; pid: number | undefined } {
   const child = cpSpawn(cmd[0]!, cmd.slice(1), {
     cwd: opts?.cwd,
     stdio: [
-      "ignore",
+      opts?.stdin === "pipe" ? "pipe" : "ignore",
       opts?.stdout === "ignore" ? "ignore" : "pipe",
       opts?.stderr === "ignore" ? "ignore" : "pipe",
     ],
@@ -46,11 +46,92 @@ export function spawnProcess(
     });
   }
 
+  function nodeWritableToWeb(stream: import("node:stream").Writable | null): WritableStream | null {
+    if (!stream) return null;
+    return new WritableStream({
+      write(chunk: Uint8Array) {
+        return new Promise((resolve, reject) => {
+          stream.write(chunk, (err) => (err ? reject(err) : resolve()));
+        });
+      },
+      close() {
+        return new Promise((resolve) => {
+          stream.end(resolve);
+        });
+      },
+      abort() {
+        stream.destroy();
+      },
+    });
+  }
+
   return {
     exited,
     stdout: nodeStreamToWeb(child.stdout),
     stderr: nodeStreamToWeb(child.stderr),
+    stdin: nodeWritableToWeb(child.stdin),
     kill: () => child.kill(),
+    pid: child.pid,
+  };
+}
+
+// ── PTY support (optional, requires node-pty) ────────────────────
+
+export interface PtyHandle {
+  onData(cb: (data: string) => void): void;
+  onExit(cb: (info: { exitCode: number; signal?: number }) => void): void;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(): void;
+  pid: number;
+}
+
+let ptyModule: {
+  spawn(
+    file: string,
+    args: string[],
+    opts: { name?: string; cols?: number; rows?: number; cwd?: string; env?: Record<string, string> },
+  ): { onData: (cb: (data: string) => void) => { dispose: () => void }; onExit: (cb: (info: { exitCode: number; signal?: number }) => void) => { dispose: () => void }; write: (data: string) => void; resize: (cols: number, rows: number) => void; kill: () => void; pid: number };
+} | null | undefined;
+
+function loadPty() {
+  if (ptyModule !== undefined) return ptyModule;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ptyModule = require("node-pty");
+  } catch {
+    ptyModule = null;
+  }
+  return ptyModule;
+}
+
+export function isPtyAvailable(): boolean {
+  return loadPty() !== null;
+}
+
+export function spawnPty(
+  shell: string,
+  args: string[],
+  opts: { cols?: number; rows?: number; cwd?: string; env?: Record<string, string> },
+): PtyHandle {
+  const pty = loadPty();
+  if (!pty) throw new Error("node-pty is not available — install it with: npm install node-pty");
+
+  const proc = pty.spawn(shell, args, {
+    name: "xterm-256color",
+    cols: opts.cols ?? 80,
+    rows: opts.rows ?? 24,
+    cwd: opts.cwd,
+    env: opts.env ? { ...process.env, ...opts.env } as Record<string, string> : process.env as Record<string, string>,
+  });
+
+  return {
+    onData(cb) { proc.onData(cb); },
+    onExit(cb) { proc.onExit(cb); },
+    write(data) { proc.write(data); },
+    resize(cols, rows) { proc.resize(cols, rows); },
+    kill() { proc.kill(); },
+    pid: proc.pid,
   };
 }