@termhub/agent 0.4.4 → 0.5.1

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);
@@ -622,7 +653,8 @@ function claudeConfigDirs(accountDirs) {
 function expandHome(dir, home) {
   return dir.startsWith("~/") ? `${home}/${dir.slice(2)}` : dir;
 }
-var CLAUDE_HOOK_EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "Notification", "Stop", "SessionEnd"];
+var CLAUDE_HOOK_EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "Notification", "Stop", "SessionEnd"];
+var CLAUDE_TOOL_EVENTS = /* @__PURE__ */ new Set(["PreToolUse", "PermissionRequest"]);
 var CURSOR_HOOK_EVENTS = ["sessionStart", "beforeSubmitPrompt", "afterAgentResponse", "stop", "sessionEnd"];
 var HOOK_SCRIPT = `#!/bin/sh
 # termhub monitor hook \u2014 installed by termhub; forwards Claude Code / Codex / Cursor CLI hook
@@ -643,9 +675,21 @@ if [ "$TOOL" = codex ]; then EVENT="$2"; else EVENT=$(cat 2>/dev/null); fi
 # screen, and only when the pair changed since the last one for this session \u2014 twenty edits in a row
 # are one request as long as the verb stays the same (a new verb mid-run is a new request). The marker is per tmux
 # session, under TMPDIR, with the session name reduced to filename-safe characters.
+# AskUserQuestion is the one exception (below).
 MARK="\${TMPDIR:-/tmp}/termhub-hook-$(printf '%s' "$SESSION" | tr -c 'A-Za-z0-9_-' '_')"
-case "$EVENT" in
-  *'"hook_event_name":"PreToolUse"'*|*'"hook_event_name": "PreToolUse"'*)
+# The branch below is picked on the event's OWN hook_event_name \u2014 the FIRST "hook_event_name" key of
+# the payload (Claude Code serialises it before tool_input, same reasoning as tool_name below) \u2014
+# never a value a substring search could find nested inside a tool's input (e.g. a PermissionRequest
+# whose tool_input happened to contain the text "hook_event_name":"PreToolUse").
+KIND_REST=\${EVENT#*'"hook_event_name"'}
+if [ "$KIND_REST" != "$EVENT" ]; then
+  KIND_REST=\${KIND_REST#*'"'}
+  KIND=\${KIND_REST%%'"'*}
+else
+  KIND=
+fi
+case "$KIND" in
+  PreToolUse)
     # The event's own tool name is the FIRST "tool_name" of the payload (Claude Code serialises it
     # before tool_input), so the shortest prefix is cut \u2014 a "tool_name" nested in a tool's input
     # must not win. Only letters, digits, "_", "." and "-" are posted (a bare Claude Code tool name,
@@ -657,35 +701,63 @@ case "$EVENT" in
     REST=\${REST#*'"'}
     NAME=\${REST%%'"'*}
     case "$NAME" in '' | *[!A-Za-z0-9_.-]*) exit 0 ;; esac
-    # Claude Code's spinner verb ("\u273B Moonwalking\u2026 (12s \xB7 esc to interrupt)"): the visible pane is
-    # read here, on the machine, and only the verb may leave it \u2014 one word of 2 to 24 ASCII letters
-    # right after a spinner glyph at column 0 and a single space, immediately followed by "\u2026" or
-    # "...", then the end of the line or a space. Column 0 because Claude Code draws its spinner
-    # there, while a draft in the input box or indented tool output can look just like one. The
-    # lowest such line of the last 24 non-blank rows wins (the live spinner sits above the todo list
-    # and the input box; blank rows under a short session are skipped). Both grep and sed run under
-    # LC_ALL=C: bytes the locale calls invalid then neither trip grep's "binary file matches" (which
-    # would also swallow the rest of the screen) nor sed's "illegal byte sequence" on macOS, and
-    # the match works the same on GNU, BSD and busybox. ASCII only on purpose: a customised verb
-    # with accents is dropped rather than half-matched. The case below checks the result again, so
-    # the hand-built JSON only ever gets letters.
-    VERB=$(tmux capture-pane -p -t "$TMUX_PANE" 2>/dev/null | LC_ALL=C grep -v '^[[:space:]]*$' 2>/dev/null | tail -n 24 |
-      LC_ALL=C sed -n -E 's/^(\xB7|\u2722|\u2733|\u2736|\u273B|\u273D|\\*) ([A-Za-z]{2,24})(\u2026|\\.\\.\\.)( .*)?$/\\2/p' | tail -n 1)
-    case "$VERB" in *[!A-Za-z]*) VERB= ;; esac
-    [ "\${#VERB}" -le 24 ] || VERB=
-    KEY="$NAME\${VERB:+ $VERB}"
-    [ "$(cat "$MARK" 2>/dev/null)" = "$KEY" ] && exit 0
-    printf '%s' "$KEY" 2>/dev/null > "$MARK"
-    if [ -n "$VERB" ]; then
-      EVENT=$(printf '{"hook_event_name":"PreToolUse","tool_name":"%s","verb":"%s"}' "$NAME" "$VERB")
-    else
-      EVENT=$(printf '{"hook_event_name":"PreToolUse","tool_name":"%s"}' "$NAME")
+    # AskUserQuestion's input is the question itself, written to be shown to the person (spec
+    # 2026-09-25 \xA74.1): the whole event goes as it came \u2014 the server keeps tool_use_id and
+    # tool_input and drops the rest \u2014 and the marker is neither read nor written, so two questions
+    # in a row are two questions. NAME is real only when $REST (everything from the first "tool_name"
+    # on) holds no SECOND "tool_name": a real question never repeats that key, so a second one means
+    # the first was actually nested inside another tool's tool_input (tool_input serialised before
+    # tool_name) and NAME does not name the real tool \u2014 fall back to the ordinary name-only path below
+    # (which, worst case, mislabels that one event; it never forwards the input).
+    ASK=false
+    if [ "$NAME" = AskUserQuestion ]; then
+      case "$REST" in
+        *'"tool_name"'*) ;;
+        *) ASK=true ;;
+      esac
+    fi
+    if [ "$ASK" != true ]; then
+      # Claude Code's spinner verb ("\u273B Moonwalking\u2026 (12s \xB7 esc to interrupt)"): the visible pane is
+      # read here, on the machine, and only the verb may leave it \u2014 one word of 2 to 24 ASCII letters
+      # right after a spinner glyph at column 0 and a single space, immediately followed by "\u2026" or
+      # "...", then the end of the line or a space. Column 0 because Claude Code draws its spinner
+      # there, while a draft in the input box or indented tool output can look just like one. The
+      # lowest such line of the last 24 non-blank rows wins (the live spinner sits above the todo list
+      # and the input box; blank rows under a short session are skipped). Both grep and sed run under
+      # LC_ALL=C: bytes the locale calls invalid then neither trip grep's "binary file matches" (which
+      # would also swallow the rest of the screen) nor sed's "illegal byte sequence" on macOS, and
+      # the match works the same on GNU, BSD and busybox. ASCII only on purpose: a customised verb
+      # with accents is dropped rather than half-matched. The case below checks the result again, so
+      # the hand-built JSON only ever gets letters.
+      VERB=$(tmux capture-pane -p -t "$TMUX_PANE" 2>/dev/null | LC_ALL=C grep -v '^[[:space:]]*$' 2>/dev/null | tail -n 24 |
+        LC_ALL=C sed -n -E 's/^(\xB7|\u2722|\u2733|\u2736|\u273B|\u273D|\\*) ([A-Za-z]{2,24})(\u2026|\\.\\.\\.)( .*)?$/\\2/p' | tail -n 1)
+      case "$VERB" in *[!A-Za-z]*) VERB= ;; esac
+      [ "\${#VERB}" -le 24 ] || VERB=
+      KEY="$NAME\${VERB:+ $VERB}"
+      [ "$(cat "$MARK" 2>/dev/null)" = "$KEY" ] && exit 0
+      printf '%s' "$KEY" 2>/dev/null > "$MARK"
+      if [ -n "$VERB" ]; then
+        EVENT=$(printf '{"hook_event_name":"PreToolUse","tool_name":"%s","verb":"%s"}' "$NAME" "$VERB")
+      else
+        EVENT=$(printf '{"hook_event_name":"PreToolUse","tool_name":"%s"}' "$NAME")
+      fi
     fi
     ;;
+  PermissionRequest)
+    # A permission prompt: only the tool's name travels, exactly like a tool call (never its input,
+    # never the suggestions). AskUserQuestion's own prompt is dropped \u2014 its PreToolUse already carried
+    # the question. Same first-"tool_name" rule and character set as above.
+    REST=\${EVENT#*'"tool_name"'}
+    [ "$REST" != "$EVENT" ] || exit 0
+    REST=\${REST#*'"'}
+    NAME=\${REST%%'"'*}
+    case "$NAME" in '' | *[!A-Za-z0-9_.-]* | AskUserQuestion) exit 0 ;; esac
+    EVENT=$(printf '{"hook_event_name":"PermissionRequest","tool_name":"%s"}' "$NAME")
+    ;;
   # A new turn starts fresh, and so does an answered notification: a permission prompt takes the tab
   # out of working, and the tool the person approves is the same one that set the marker, so without
   # this reset the retry is suppressed and nothing says the tab is working again.
-  *'"hook_event_name":"SessionStart"'*|*'"hook_event_name": "SessionStart"'*|*'"hook_event_name":"UserPromptSubmit"'*|*'"hook_event_name": "UserPromptSubmit"'*|*'"hook_event_name":"Notification"'*|*'"hook_event_name": "Notification"'*)
+  SessionStart | UserPromptSubmit | Notification)
     rm -f "$MARK"
     ;;
 esac
@@ -719,10 +791,10 @@ 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")
+    if (CLAUDE_TOOL_EVENTS.has(event))
       entry.matcher = "*";
     others.push(entry);
     next[event] = others;
@@ -860,6 +932,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 +1000,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 +1046,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 +1173,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 +1365,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 +1377,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 +1576,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 +1588,7 @@ function createDispatcher(deps) {
       case "close":
         deps.pty.close(msg.ch);
         deps.claude.close(msg.ch);
+        deps.tcp.close(msg.ch);
         break;
     }
   };
@@ -1566,13 +1680,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 +1779,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 +1969,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 +2005,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 +2312,7 @@ async function status3() {
 }
 
 // src/version.ts
-var AGENT_VERSION = "0.4.4";
+var AGENT_VERSION = "0.5.1";
 
 // src/rpc/update.ts
 var PACKAGE = "@termhub/agent";
@@ -2100,9 +2376,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 +2435,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 +2452,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 +2470,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 +2488,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 +2531,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 +2549,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.1",
   "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,