@termhub/agent 0.4.4 → 0.5.0

package/dist/cli.js

@@ -39,12 +39,19 @@ var sessionName = z.string().min(1).max(128).regex(SESSION_RE);
 var machinePath = z.string().min(1).max(4096).refine((p) => (p === "~" || p.startsWith("~/") || p.startsWith("/")) && !/[\0\n\r]/.test(p), "invalid path");
 var pasteName = z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+$/);
 var aiProvider = z.enum(["claude", "chatgpt", "gemini", "antigravity"]);
+var UDID_RE = /^[A-Fa-f0-9-]{8,64}$/;
+var udid = z.string().regex(UDID_RE);
+function isWdaPort(port) {
+  return Number.isInteger(port) && (port >= 8100 && port <= 8199 || port >= 9100 && port <= 9199);
+}
+var wdaPort = z.number().int().refine(isWdaPort, "port outside the WDA ranges");
 var TMUX_KEYS = ["Enter", "Escape", "C-c", "Up", "Down", "Tab", "y", "n", "1", "2", "3", "4", "5", "6", "7", "8", "9"];
 var tmuxKey = z.enum(TMUX_KEYS);
 var TEXT_MAX_CHARS = 4e3;
 var rpcErrorSchema = z.object({
-  /** `failed`: the operation ran on the machine and `message` says why it failed, in words meant for the user. */
-  code: z.enum(["eperm", "notfound", "no_tmux", "timeout", "invalid", "internal", "failed"]),
+  /** `failed`: the operation ran on the machine and `message` says why it failed, in words meant for the user.
+   *  `refused`: a `tcp` open found nothing listening on the port (ECONNREFUSED). */
+  code: z.enum(["eperm", "notfound", "no_tmux", "timeout", "invalid", "internal", "failed", "refused"]),
   message: z.string().max(2e3),
   path: z.string().max(4096).optional()
 });
@@ -90,7 +97,19 @@ var RPC = {
   }), 15e3),
   "hooks.uninstall": def(z.object({ claude_dirs: z.array(machinePath).max(16).optional() }), z.object({ removed: z.boolean() }), 15e3),
   /** Installs `version` of @termhub/agent with npm; when the agent runs as a service it then exits so the service relaunches the new code (since agent 0.2.1). */
-  "agent.update": def(z.object({ version: z.string().regex(/^\d+\.\d+\.\d+$/) }), z.object({ installed_version: z.string(), restart: z.enum(["service", "manual"]) }), 18e4)
+  "agent.update": def(z.object({ version: z.string().regex(/^\d+\.\d+\.\d+$/) }), z.object({ installed_version: z.string(), restart: z.enum(["service", "manual"]) }), 18e4),
+  /** iOS simulator over the agent (spec 2026-09-24): raw `xcrun simctl list devices -j`; the server parses it. */
+  "sim.list": def(z.object({}), z.object({ stdout: z.string() }), 15e3),
+  /** `xcrun simctl boot`; combined output, "already booted" included — the server decides what is a failure. */
+  "sim.boot": def(z.object({ udid }), z.object({ stdout: z.string() }), 6e4),
+  /** Starts the WDA runner in its tmux session; `started: false` when the session already existed. */
+  "wda.runner.start": def(z.object({ udid, wda_port: wdaPort, mjpeg_port: wdaPort }), z.object({ started: z.boolean() }), 1e4),
+  "wda.runner.alive": def(z.object({ udid }), z.object({ alive: z.boolean() })),
+  "wda.runner.tail": def(z.object({ udid, lines: z.number().int().min(1).max(200) }), z.object({ lines: z.array(z.string()) })),
+  /** Writes ~/.termhub/wda-setup.sh and runs it in tmux `termhub-wda-setup`; `started: false` when already running. */
+  "wda.setup.start": def(z.object({}), z.object({ started: z.boolean() }), 1e4),
+  /** Raw `STATE:/VERSION:/TAIL:` text; `parseSetupOutput` on the server reads it. */
+  "wda.setup.state": def(z.object({}), z.object({ stdout: z.string() }))
 };
 var RPC_METHODS = Object.keys(RPC);
 var rpcMethod = z.enum(RPC_METHODS);
@@ -100,9 +119,10 @@ var PROTOCOL_VERSION = 1;
 var CLOSE = { UNAUTHORIZED: 4401, CONFLICT: 4409, VIOLATION: 1008 };
 var channel = z2.number().int().min(1).max(4294967295);
 var rpcId = z2.string().min(1).max(64);
-var closedReason = z2.enum(["cli_missing", "run_failed", "killed", "missing_session", "cli_rejected"]);
+var closedReason = z2.enum(["cli_missing", "run_failed", "killed", "missing_session", "cli_rejected", "reset"]);
 var CAPABILITY_CLAUDE = "claude";
 var CAPABILITY_CLAUDE_SYSTEM_PROMPT = "claude.system_prompt";
+var CAPABILITY_SIM = "sim";
 var helloMessage = z2.object({
   type: z2.literal("hello"),
   protocol: z2.number().int().min(1),
@@ -150,17 +170,21 @@ var claudeOpenParams = z2.object({
   // `CAPABILITY_CLAUDE_SYSTEM_PROMPT`). Absent for the account-wide chat, whose argv must not change.
   append_system_prompt: z2.string().max(4e3).nullable().optional()
 });
+var tcpOpenParams = z2.object({ port: wdaPort }).strict();
 var openPty = z2.object({ type: z2.literal("open"), ch: channel, kind: z2.literal("pty"), params: ptyOpenParams });
 var openClaude = z2.object({ type: z2.literal("open"), ch: channel, kind: z2.literal("claude"), params: claudeOpenParams });
+var openTcp = z2.object({ type: z2.literal("open"), ch: channel, kind: z2.literal("tcp"), params: tcpOpenParams });
 var serverMessage = z2.union([
   z2.object({ type: z2.literal("rpc"), id: rpcId, method: rpcMethod, params: z2.unknown() }),
   openPty,
   openClaude,
+  openTcp,
   z2.object({ type: z2.literal("resize"), ch: channel, cols: z2.number().int().min(2).max(500), rows: z2.number().int().min(2).max(200) }),
   z2.object({ type: z2.literal("close"), ch: channel })
 ]);
 
 // src/client.ts
+var MAX_STREAM_PAYLOAD = MAX_FRAME - HEADER_BYTES;
 var RevokedError = class extends Error {
 };
 var ProtocolMismatchError = class extends Error {
@@ -249,7 +273,14 @@ function connectOnce(opts, signal) {
       }, opts.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS);
       socket = {
         sendControl: (msg) => ws.send(encodeFrame(CONTROL_CHANNEL, JSON.stringify(msg))),
-        sendStream: (ch, data) => ws.send(encodeFrame(ch, data))
+        sendStream: (ch, data) => {
+          if (data.length <= MAX_STREAM_PAYLOAD) {
+            ws.send(encodeFrame(ch, data));
+            return;
+          }
+          for (let off = 0; off < data.length; off += MAX_STREAM_PAYLOAD) ws.send(encodeFrame(ch, data.subarray(off, off + MAX_STREAM_PAYLOAD)));
+        },
+        bufferedAmount: () => ws.bufferedAmount
       };
       const hello = { type: "hello", protocol: PROTOCOL_VERSION, ...opts.hello };
       socket.sendControl(hello);
@@ -719,8 +750,8 @@ function mergeClaudeSettings(current, scriptPath, shown = "~/.claude/settings.js
     throw new Error(`${shown}: o campo "hooks" n\xE3o \xE9 um objeto`);
   const next = hooks ?? {};
   for (const event of CLAUDE_HOOK_EVENTS) {
-    const list3 = Array.isArray(next[event]) ? next[event] : [];
-    const others = list3.filter((e) => !isOurs(e));
+    const list4 = Array.isArray(next[event]) ? next[event] : [];
+    const others = list4.filter((e) => !isOurs(e));
     const entry = { hooks: [{ type: "command", command: `${scriptPath} claude`, timeout: 10 }] };
     if (event === "PreToolUse")
       entry.matcher = "*";
@@ -860,6 +891,47 @@ function configDirsFromRc(text) {
   return out;
 }
 
+// ../../packages/machine-ops/dist/simulator.js
+var WDA_DIR = "$HOME/.termhub/WebDriverAgent";
+var WDA_SETUP_SESSION = "termhub-wda-setup";
+var UDID_RE2 = /^[A-Fa-f0-9-]{8,64}$/;
+function runnerSessionName(udid2) {
+  return `termhub-wda-${udid2.slice(0, 8).toLowerCase()}`;
+}
+var SIMCTL_LIST_SCRIPT = "xcrun simctl list devices -j";
+var SIMCTL_BOOT_SCRIPT = 'xcrun simctl boot "$UDID" 2>&1 || true';
+var WDA_RUNNER_START_SCRIPT = `tmux new-session -d -s "$SESSION" "cd ${WDA_DIR} && xcodebuild test-without-building -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination id=$UDID -derivedDataPath DerivedData USE_PORT=$WDA_PORT MJPEG_SERVER_PORT=$MJPEG_PORT"`;
+var WDA_RUNNER_ALIVE_SCRIPT = `tmux has-session -t "=$SESSION" 2>/dev/null && echo yes || echo no`;
+var WDA_RUNNER_TAIL_SCRIPT = `tmux capture-pane -p -t "=$SESSION" 2>/dev/null | grep -v '^$' | tail -n "$LINES"`;
+var WDA_SETUP_SH = [
+  "#!/bin/sh",
+  'export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"',
+  'mkdir -p "$HOME/.termhub"',
+  'rm -f "$HOME/.termhub/wda-setup.status"',
+  "{",
+  `  if [ -d "${WDA_DIR}/.git" ]; then git -C "${WDA_DIR}" pull --ff-only; else git clone --depth 1 https://github.com/appium/WebDriverAgent "${WDA_DIR}"; fi &&`,
+  `  cd "${WDA_DIR}" &&`,
+  "  xcodebuild build-for-testing -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'generic/platform=iOS Simulator' -derivedDataPath DerivedData CODE_SIGNING_ALLOWED=NO",
+  '} > "$HOME/.termhub/wda-setup.log" 2>&1',
+  'echo $? > "$HOME/.termhub/wda-setup.status"',
+  ""
+].join("\n");
+var WDA_SETUP_START_SCRIPT = [
+  `if tmux has-session -t '=${WDA_SETUP_SESSION}' 2>/dev/null; then echo STARTED:no; exit 0; fi`,
+  `mkdir -p "$HOME/.termhub" && cat > "$HOME/.termhub/wda-setup.sh" <<'TERMHUB_EOF'`,
+  WDA_SETUP_SH + "TERMHUB_EOF",
+  `chmod +x "$HOME/.termhub/wda-setup.sh" && tmux new-session -d -s ${WDA_SETUP_SESSION} 'sh "$HOME/.termhub/wda-setup.sh"' && echo STARTED:yes`
+].join("\n");
+var WDA_SETUP_STATE_SCRIPT = `
+if tmux has-session -t '=${WDA_SETUP_SESSION}' 2>/dev/null; then echo STATE:running;
+elif [ -f "$HOME/.termhub/wda-setup.status" ]; then
+  if [ "$(cat "$HOME/.termhub/wda-setup.status")" = 0 ]; then echo STATE:ok; else echo STATE:failed; fi;
+else echo STATE:idle; fi
+echo VERSION:$(sed -n 's/.*"version": *"\\([^"]*\\)".*/\\1/p' "${WDA_DIR}/package.json" 2>/dev/null | head -1)
+echo TAIL:
+tail -n 40 "$HOME/.termhub/wda-setup.log" 2>/dev/null
+exit 0`;
+
 // src/claude-dirs.ts
 import { readdir, readFile, stat } from "fs/promises";
 import path2 from "path";
@@ -887,8 +959,8 @@ async function fileNames(dir) {
 }
 async function candidateNames(home) {
   try {
-    const list3 = await readdir(home, { withFileTypes: true });
-    return list3.filter((d) => d.isDirectory() && d.name.startsWith(".claude")).map((d) => d.name);
+    const list4 = await readdir(home, { withFileTypes: true });
+    return list4.filter((d) => d.isDirectory() && d.name.startsWith(".claude")).map((d) => d.name);
   } catch {
     return [];
   }
@@ -933,12 +1005,12 @@ function tmuxPath() {
   return process.env.TMUX_PATH || "tmux";
 }
 function run(file, args, opts = {}) {
-  const { timeoutMs = DEFAULT_TIMEOUT_MS, input, env = agentEnv() } = opts;
+  const { timeoutMs = DEFAULT_TIMEOUT_MS, input, env: env2 = agentEnv() } = opts;
   return new Promise((resolve) => {
     const child = execFile(
       file,
       args,
-      { timeout: timeoutMs, env, maxBuffer: 8 * 1024 * 1024, encoding: "utf8" },
+      { timeout: timeoutMs, env: env2, maxBuffer: 8 * 1024 * 1024, encoding: "utf8" },
       (err, stdout, stderr) => {
         const e = err;
         resolve({
@@ -1060,9 +1132,9 @@ async function install(params, home = os3.homedir()) {
 }
 async function heal(home = os3.homedir()) {
   const scriptPath = path3.join(home, HOOK_SCRIPT_REL);
-  const env = await readOrEmpty2(path3.join(home, HOOK_ENV_REL));
+  const env2 = await readOrEmpty2(path3.join(home, HOOK_ENV_REL));
   const script = await readOrEmpty2(scriptPath);
-  if (!env.trim() || !script) return [];
+  if (!env2.trim() || !script) return [];
   if (script !== HOOK_SCRIPT) await writeAtomic(scriptPath, HOOK_SCRIPT, 493);
   const steps = [healClaudeDirs, healCursor, healCodex];
   const healed = [];
@@ -1252,9 +1324,9 @@ function createClaudeManager(deps) {
       const runDir = dir;
       socket.sendControl({ type: "opened", ch });
       deps.log("claude run starting", { ch, resume: params.resume, model: params.model ?? null });
-      const env = { ...deps.env ?? agentEnv() };
-      if (params.config_dir === null) delete env.CLAUDE_CONFIG_DIR;
-      else env.CLAUDE_CONFIG_DIR = params.config_dir;
+      const env2 = { ...deps.env ?? agentEnv() };
+      if (params.config_dir === null) delete env2.CLAUDE_CONFIG_DIR;
+      else env2.CLAUDE_CONFIG_DIR = params.config_dir;
       const args = buildClaudeArgs({
         session_id: params.session_id,
         resume: params.resume,
@@ -1264,7 +1336,7 @@ function createClaudeManager(deps) {
       });
       let child;
       try {
-        child = spawn(CLI, args, { env, stdio: ["pipe", "pipe", "pipe"], detached: true });
+        child = spawn(CLI, args, { env: env2, stdio: ["pipe", "pipe", "pipe"], detached: true });
       } catch (err) {
         deps.log("claude run could not be started", { ch, cli: CLI, error: message(err) });
         rmSync(runDir, { recursive: true, force: true });
@@ -1463,7 +1535,7 @@ function createDispatcher(deps) {
         void handleRpc(msg, socket, deps.handlers, deps.log);
         break;
       case "open": {
-        const opened = msg.kind === "claude" ? deps.claude.open(msg.ch, msg.params, socket) : deps.pty.open(msg.ch, msg.params, socket);
+        const opened = msg.kind === "claude" ? deps.claude.open(msg.ch, msg.params, socket) : msg.kind === "tcp" ? deps.tcp.open(msg.ch, msg.params, socket) : deps.pty.open(msg.ch, msg.params, socket);
         opened.catch((err) => {
           deps.log(`${msg.kind}.open rejected unexpectedly`, { ch: msg.ch, error: err instanceof Error ? err.message : String(err) });
         });
@@ -1475,6 +1547,7 @@ function createDispatcher(deps) {
       case "close":
         deps.pty.close(msg.ch);
         deps.claude.close(msg.ch);
+        deps.tcp.close(msg.ch);
         break;
     }
   };
@@ -1566,13 +1639,13 @@ function createPtyManager(deps) {
       try {
         ({ cols, rows } = clampSize(params));
         const cwd = resolveCwd(params.cwd);
-        const env = {
+        const env2 = {
           ...ptyEnv(agentEnv(), process.env.SHELL ?? "/bin/sh"),
           TERMHUB_TAB_ID: params.session,
           TERMHUB_SESSION: params.session
         };
         const spawn2 = await resolveSpawn();
-        const spawnTmux = () => spawn2(tmux, ["-u", "new-session", "-A", "-s", params.session, "-c", cwd], { name: "xterm-256color", cols, rows, cwd, env });
+        const spawnTmux = () => spawn2(tmux, ["-u", "new-session", "-A", "-s", params.session, "-c", cwd], { name: "xterm-256color", cols, rows, cwd, env: env2 });
         try {
           proc = spawnTmux();
         } catch (err) {
@@ -1665,6 +1738,141 @@ function createPtyManager(deps) {
   };
 }
 
+// src/tcp.ts
+import net from "net";
+var DEFAULT_HIGH_WATER = 4 * 1024 * 1024;
+var DEFAULT_LOW_WATER = 1024 * 1024;
+var DEFAULT_RESUME_POLL_MS = 50;
+function isRefused(err) {
+  return err?.code === "ECONNREFUSED";
+}
+function createTcpManager(deps) {
+  const channels = /* @__PURE__ */ new Map();
+  const allowPort = deps.allowPort ?? isWdaPort;
+  const highWater = deps.highWater ?? DEFAULT_HIGH_WATER;
+  const lowWater = deps.lowWater ?? DEFAULT_LOW_WATER;
+  const resumePollMs = deps.resumePollMs ?? DEFAULT_RESUME_POLL_MS;
+  const control = (socket, msg) => {
+    try {
+      socket.sendControl(msg);
+    } catch (err) {
+      deps.log("tcp control send failed", { type: msg.type, error: err instanceof Error ? err.message : String(err) });
+    }
+  };
+  const stopResumeTimer = (entry) => {
+    if (entry.resumeTimer) clearInterval(entry.resumeTimer);
+    entry.resumeTimer = null;
+  };
+  const drop = (ch, entry) => {
+    entry.closed = true;
+    stopResumeTimer(entry);
+    if (channels.get(ch) === entry) channels.delete(ch);
+    entry.sock.destroy();
+  };
+  return {
+    async open(ch, params, socket) {
+      if (channels.has(ch)) {
+        control(socket, { type: "open_error", ch, error: { code: "invalid", message: "channel in use" } });
+        return;
+      }
+      if (!allowPort(params.port)) {
+        deps.log("tcp open refused: port not allowed", { ch, port: params.port });
+        control(socket, { type: "open_error", ch, error: { code: "invalid", message: "port not allowed" } });
+        return;
+      }
+      const sock = net.connect({ host: "127.0.0.1", port: params.port });
+      let opened = false;
+      let closedSent = false;
+      const entry = {
+        sock,
+        paused: false,
+        resumeTimer: null,
+        closed: false,
+        sendClosed: (reason) => {
+          if (closedSent) return;
+          closedSent = true;
+          control(socket, reason ? { type: "closed", ch, code: null, reason } : { type: "closed", ch, code: null });
+        }
+      };
+      channels.set(ch, entry);
+      await new Promise((resolve) => {
+        sock.once("connect", () => {
+          opened = true;
+          deps.log("tcp opened", { ch, port: params.port });
+          control(socket, { type: "opened", ch });
+          resolve();
+        });
+        sock.once("error", (err) => {
+          if (!opened) {
+            channels.delete(ch);
+            stopResumeTimer(entry);
+            deps.log("tcp open failed", { ch, port: params.port, code: err.code ?? "unknown" });
+            control(socket, { type: "open_error", ch, error: isRefused(err) ? { code: "refused", message: "connection refused" } : { code: "internal", message: "connect failed" } });
+            resolve();
+            return;
+          }
+          deps.log("tcp socket error", { ch, port: params.port, code: err.code ?? "unknown" });
+          entry.sock.destroy();
+        });
+      });
+      if (!channels.has(ch)) return;
+      sock.on("data", (chunk) => {
+        if (entry.closed) return;
+        try {
+          socket.sendStream(ch, chunk);
+        } catch (err) {
+          deps.log("tcp stream send failed", { ch, error: err instanceof Error ? err.message : String(err) });
+          return;
+        }
+        const queued = socket.bufferedAmount?.() ?? 0;
+        if (queued > highWater && !entry.paused) {
+          entry.paused = true;
+          sock.pause();
+          deps.log("tcp paused", { ch, queued });
+          entry.resumeTimer = setInterval(() => {
+            if (entry.closed) {
+              stopResumeTimer(entry);
+              return;
+            }
+            if ((socket.bufferedAmount?.() ?? 0) <= lowWater) {
+              stopResumeTimer(entry);
+              entry.paused = false;
+              sock.resume();
+              deps.log("tcp resumed", { ch });
+            }
+          }, resumePollMs);
+        }
+      });
+      sock.on("close", (hadError) => {
+        if (!opened) return;
+        stopResumeTimer(entry);
+        if (channels.get(ch) === entry) channels.delete(ch);
+        if (entry.closed) return;
+        deps.log("tcp closed", { ch, port: params.port, hadError });
+        entry.sendClosed(hadError ? "reset" : void 0);
+      });
+    },
+    write(ch, data) {
+      const entry = channels.get(ch);
+      if (!entry || entry.closed) return false;
+      entry.sock.write(data);
+      return true;
+    },
+    close(ch) {
+      const entry = channels.get(ch);
+      if (!entry) return;
+      drop(ch, entry);
+      entry.sendClosed();
+    },
+    closeAll() {
+      for (const [ch, entry] of channels) drop(ch, entry);
+    },
+    isPaused(ch) {
+      return channels.get(ch)?.paused ?? false;
+    }
+  };
+}
+
 // src/rpc/ai.ts
 async function credential(params) {
   let prefix;
@@ -1720,6 +1928,33 @@ async function pasteFile(params) {
   return { path: path12 };
 }
 
+// src/rpc/sim.ts
+function checkUdid(udid2) {
+  if (!UDID_RE2.test(udid2)) throw new RpcFailure("invalid", "invalid udid");
+}
+function scriptFailure(r, what) {
+  if (r.timedOut) return new RpcFailure("timeout", `${what} timed out`);
+  if (r.error === "enoent") return new RpcFailure("internal", "/bin/sh not found");
+  if (r.code !== 0) {
+    const why2 = r.stderr.trim().split("\n")[0] || r.stdout.trim().split("\n")[0] || `${what} exited with code ${r.code}`;
+    return /tmux: (command )?not found/.test(r.stderr) ? new RpcFailure("no_tmux", "tmux not found") : new RpcFailure("failed", why2);
+  }
+  return null;
+}
+async function list2(_params) {
+  const r = await sh(SIMCTL_LIST_SCRIPT, { timeoutMs: 14e3 });
+  const failure = scriptFailure(r, "sim.list");
+  if (failure) throw failure;
+  return { stdout: r.stdout };
+}
+async function boot(params) {
+  checkUdid(params.udid);
+  const r = await sh(SIMCTL_BOOT_SCRIPT, { timeoutMs: 59e3, env: { ...agentEnv(), UDID: params.udid } });
+  const failure = scriptFailure(r, "sim.boot");
+  if (failure) throw failure;
+  return { stdout: r.stdout + r.stderr };
+}
+
 // src/rpc/tmux.ts
 import { randomUUID } from "crypto";
 var ENTER_PAUSE_MS = 300;
@@ -1729,7 +1964,7 @@ function processFailure2(r) {
   if (r.error === "maxbuffer") return new RpcFailure("internal", "output too large");
   return null;
 }
-async function list2(_params) {
+async function list3(_params) {
   const r = await run(tmuxPath(), ["list-sessions", "-F", "#{session_name}"]);
   const failure = processFailure2(r);
   if (failure) throw failure;
@@ -2036,7 +2271,7 @@ async function status3() {
 }
 
 // src/version.ts
-var AGENT_VERSION = "0.4.4";
+var AGENT_VERSION = "0.5.0";
 
 // src/rpc/update.ts
 var PACKAGE = "@termhub/agent";
@@ -2100,9 +2335,52 @@ async function doUpdate(version, deps) {
 }
 var update = (params) => updateAgent(params);
 
+// src/rpc/wda.ts
+function env(vars) {
+  return { ...agentEnv(), ...vars };
+}
+async function runnerStart(params) {
+  checkUdid(params.udid);
+  if (!isWdaPort(params.wda_port) || !isWdaPort(params.mjpeg_port)) throw new RpcFailure("invalid", "port outside the WDA ranges");
+  const vars = { SESSION: runnerSessionName(params.udid), UDID: params.udid, WDA_PORT: String(params.wda_port), MJPEG_PORT: String(params.mjpeg_port) };
+  const r = await sh(WDA_RUNNER_START_SCRIPT, { timeoutMs: 9e3, env: env(vars) });
+  if (r.code !== 0 && r.stderr.includes("duplicate session")) return { started: false };
+  const failure = scriptFailure(r, "wda.runner.start");
+  if (failure) throw failure;
+  return { started: true };
+}
+async function runnerAlive(params) {
+  checkUdid(params.udid);
+  const r = await sh(WDA_RUNNER_ALIVE_SCRIPT, { env: env({ SESSION: runnerSessionName(params.udid) }) });
+  const failure = scriptFailure(r, "wda.runner.alive");
+  if (failure) throw failure;
+  return { alive: r.stdout.includes("yes") };
+}
+async function runnerTail(params) {
+  checkUdid(params.udid);
+  const r = await sh(WDA_RUNNER_TAIL_SCRIPT, { env: env({ SESSION: runnerSessionName(params.udid), LINES: String(params.lines) }) });
+  const failure = scriptFailure(r, "wda.runner.tail");
+  if (failure) throw failure;
+  return { lines: r.stdout.split("\n").filter((l) => l.trim()) };
+}
+async function setupStart(_params) {
+  const r = await sh(WDA_SETUP_START_SCRIPT, { timeoutMs: 9e3 });
+  const failure = scriptFailure(r, "wda.setup.start");
+  if (failure) throw failure;
+  if (r.stdout.includes("STARTED:no")) return { started: false };
+  if (r.stdout.includes("STARTED:yes")) return { started: true };
+  throw new RpcFailure("failed", r.stderr.trim().split("\n")[0] || "setup did not start");
+}
+async function setupState(_params) {
+  const r = await sh(WDA_SETUP_STATE_SCRIPT);
+  const failure = scriptFailure(r, "wda.setup.state");
+  if (failure) throw failure;
+  return { stdout: r.stdout };
+}
+
 // src/rpc/index.ts
 var handlers = {
-  "tmux.list": list2,
+  "tmux.list": list3,
   "tmux.kill": kill,
   "tmux.capture": capture,
   "tmux.ensure": ensure,
@@ -2116,7 +2394,14 @@ var handlers = {
   "file.paste": pasteFile,
   "hooks.install": install,
   "hooks.uninstall": uninstall,
-  "agent.update": update
+  "agent.update": update,
+  "sim.list": list2,
+  "sim.boot": boot,
+  "wda.runner.start": runnerStart,
+  "wda.runner.alive": runnerAlive,
+  "wda.runner.tail": runnerTail,
+  "wda.setup.start": setupStart,
+  "wda.setup.state": setupState
 };
 
 // src/run.ts
@@ -2126,6 +2411,9 @@ function detectOs(platform = process.platform) {
   return null;
 }
 var CAPABILITIES = [CAPABILITY_CLAUDE, CAPABILITY_CLAUDE_SYSTEM_PROMPT];
+function capabilitiesFor(osName) {
+  return osName === "macos" ? [...CAPABILITIES, CAPABILITY_SIM] : [...CAPABILITIES];
+}
 async function buildHello(osName) {
   let tools = [];
   try {
@@ -2141,7 +2429,7 @@ async function buildHello(osName) {
     hostname: os6.hostname(),
     tmux: tools.includes("tmux"),
     tools,
-    capabilities: CAPABILITIES
+    capabilities: capabilitiesFor(osName)
   };
 }
 var REVOKED_MESSAGE = "Token inv\xE1lido ou revogado";
@@ -2159,7 +2447,7 @@ async function checkServerConnection(config, timeoutMs = 5e3) {
       {
         url: config.url,
         token: config.token,
-        hello: { agent_version: AGENT_VERSION, os: osName, arch: process.arch, hostname: os6.hostname(), tmux: false, tools: [], capabilities: CAPABILITIES, probe: true },
+        hello: { agent_version: AGENT_VERSION, os: osName, arch: process.arch, hostname: os6.hostname(), tmux: false, tools: [], capabilities: capabilitiesFor(osName), probe: true },
         onServerMessage: () => {
         },
         onStream: () => {
@@ -2202,7 +2490,8 @@ async function runAgent(config, opts) {
   else if (!helper.executable) opts.log("spawn-helper is not executable and could not be fixed", { path: helper.path, error: helper.error });
   const pty = createPtyManager({ log: opts.log });
   const claude = createClaudeManager({ log: opts.log });
-  const dispatch = createDispatcher({ handlers, pty, claude, log: opts.log });
+  const tcp = createTcpManager({ log: opts.log });
+  const dispatch = createDispatcher({ handlers, pty, claude, tcp, log: opts.log });
   const healHooks = () => {
     heal().then((dirs) => {
       if (dirs.length) opts.log("monitor hooks repaired", { dirs: dirs.length });
@@ -2219,12 +2508,13 @@ async function runAgent(config, opts) {
         // A frame belongs to whichever manager holds that channel: the claude one says so, and
         // anything it does not own is a terminal's.
         onStream: (ch, data) => {
-          if (!claude.write(ch, data)) pty.write(ch, data);
+          if (!claude.write(ch, data) && !tcp.write(ch, data)) pty.write(ch, data);
         },
         onConnect: healHooks,
         onDisconnect: () => {
           pty.closeAll();
           claude.closeAll();
+          tcp.closeAll();
         },
         log: opts.log
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termhub/agent",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Agente do termhub: conecta esta máquina ao servidor por WebSocket de saída (sem SSH) e expõe os terminais tmux no navegador.",
   "license": "MIT",
   "private": false,