mobile-automator 0.23.8

package/src/device/session-daemon.js

@@ -0,0 +1,526 @@
+'use strict';
+
+// Long-lived device session daemon.
+//
+// Builds ONE mobile-mcp connection (via the injected `createCall`) and serves
+// every connecting one-shot verb over a per-workspace Unix domain socket. The
+// single connection is the whole point of the feature: a 40-step scenario pays
+// the spawn+handshake tax exactly once.
+//
+// Lifecycle:
+//   - clean any stale socket/pidfile before binding,
+//   - listen on the socket, write handle + pidfile once listening,
+//   - route { type:'call', tool, args } frames to the single `call`,
+//   - reset an idle timer on every request; reap the daemon when it expires,
+//   - shut down cleanly on a { type:'shutdown' } control frame and on
+//     SIGTERM/SIGINT, removing the socket/pidfile/handle.
+//
+// Everything that touches a real device is injected, so the full lifecycle is
+// unit-testable with a fake createCall and a mkdtemp project root.
+
+const childProcess = require('child_process');
+const fs = require('fs');
+const net = require('net');
+
+const paths = require('./session-paths');
+const { FrameParser } = require('./session-protocol');
+
+const DEFAULT_IDLE_MS = 5 * 60 * 1000;
+
+// Per-call timeout for the shared mobile-mcp connection. Deliberately BELOW the
+// client's DEFAULT_TIMEOUT_MS (30000) so the daemon's timeout error always wins
+// the race and reaches the client as an honest {kind:'timeout'} reply instead of
+// being dropped by the client's own 30s timeout (which would look like a
+// false-failure and prompt a retry → double-execution on the device). The
+// structural invariant CLIENT_TIMEOUT > DAEMON_CALL_TIMEOUT is pinned by
+// tests/unit/device/timeout-invariant.test.js.
+const DAEMON_CALL_TIMEOUT_MS = 25000;
+
+// Resolves after `ms` without keeping the process alive. Injectable so tests
+// can drive the timeout path without waiting 25s.
+function defaultScheduleTimeout(ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (typeof t.unref === 'function') t.unref();
+  });
+}
+
+function defaultCreateCall(opts) {
+  return require('./mobile-mcp-client').createCall(opts);
+}
+
+// Best-effort unlink — never throws.
+function safeUnlink(p) {
+  try {
+    fs.unlinkSync(p);
+  } catch (_) {
+    /* not present */
+  }
+}
+
+// True when a pid is a live process we own. ESRCH => dead; EPERM => alive.
+// Kept exported for back-compat; cleanStale routes through pidIdentity, which
+// also checks the process's identity (not just liveness).
+function pidAlive(pid) {
+  if (!pid || !Number.isInteger(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+// Classify a pid by liveness AND identity. Liveness alone is not enough: a
+// recycled pid (an unrelated process that inherited the dead daemon's pid) is
+// "alive" but is NOT our daemon, so a stale lock/pidfile pointing at it must be
+// cleaned rather than respected. Returns one of:
+//   'dead'    - no such process (ESRCH or any non-EPERM kill error)
+//   'ours'    - alive AND its command line contains `mauto-session-daemon`
+//   'other'   - alive AND its command line does NOT (recycled pid)
+//   'unknown' - alive but `ps` itself failed (e.g. no `ps` on the host) —
+//               treated as 'ours' by cleanStale: never clean when unsure.
+// `execFile` is injectable for tests; a failure there must never crash the
+// daemon, hence the 'unknown' fallback.
+function pidIdentity(pid, { execFile = childProcess.execFileSync } = {}) {
+  if (!pid || !Number.isInteger(pid)) return 'dead';
+  // Our own pid is the in-process daemon (unit tests run startDaemon in the
+  // test process, so the lock/pidfile carry the test runner's pid). Never clean
+  // files that point at ourselves. In production cleanStale runs before the
+  // daemon writes its own pid/lock, so this branch only fires in-process.
+  if (pid === process.pid) return 'ours';
+  let alive;
+  try {
+    process.kill(pid, 0);
+    alive = true;
+  } catch (err) {
+    if (err.code === 'EPERM') alive = true;
+    else return 'dead';
+  }
+  if (!alive) return 'dead';
+  try {
+    const out = execFile('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' });
+    return /mauto-session-daemon/.test(String(out || '')) ? 'ours' : 'other';
+  } catch (_) {
+    return 'unknown';
+  }
+}
+
+// Read a pid out of a one-line pid/lock file, or null when absent/garbage.
+function readPidFile(file) {
+  try {
+    const pid = parseInt(fs.readFileSync(file, 'utf8').trim(), 10);
+    return Number.isInteger(pid) ? pid : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// Remove stale socket/pidfile/handle/lock left by a crashed daemon so a fresh
+// daemon can bind. Identity is decided from the LOCK file first (acquired before
+// the connection is built, so it covers a daemon still mid-startup) then the
+// pidfile (written once listening). If either points at a LIVE process that is
+// OURS (or unclassifiable — 'unknown') we leave everything alone and signal the
+// caller — the lock's O_EXCL or the listen() EADDRINUSE then surfaces the
+// conflict rather than hijacking a healthy daemon. A pid that is alive but NOT
+// ours ('other') is a RECYCLED pid: the daemon that wrote it is long dead and an
+// unrelated process inherited the number, so the stale files are cleaned instead
+// of wedging every spawn for the lifetime of that unrelated process.
+function cleanStale(projectRoot, { execFile } = {}) {
+  const pidFile = paths.pidFilePath(projectRoot);
+  const lockFile = paths.lockPath(projectRoot);
+  let livePid = null;
+  for (const f of [lockFile, pidFile]) {
+    const pid = readPidFile(f);
+    if (!pid) continue;
+    const id = pidIdentity(pid, { execFile });
+    if (id === 'dead') continue; // keep scanning; ultimately clean
+    if (id === 'ours' || id === 'unknown') {
+      livePid = pid;
+      break;
+    }
+    // id === 'other' → recycled pid → fall through to the safeUnlinks.
+  }
+  if (livePid) return { cleaned: false, livePid };
+
+  safeUnlink(paths.socketPath(projectRoot));
+  safeUnlink(pidFile);
+  safeUnlink(paths.handlePath(projectRoot));
+  safeUnlink(lockFile);
+  return { cleaned: true, livePid: null };
+}
+
+async function startDaemon({
+  projectRoot,
+  device = null,
+  idleMs = DEFAULT_IDLE_MS,
+  createCall = defaultCreateCall,
+  onUndeliverable = null,
+  scheduleTimeout = defaultScheduleTimeout,
+  execFile = childProcess.execFileSync,
+} = {}) {
+  if (!projectRoot) throw new TypeError('startDaemon requires projectRoot');
+
+  const dir = paths.sessionDir(projectRoot);
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Reap a crashed daemon's leftovers before we bind.
+  cleanStale(projectRoot, { execFile });
+
+  // Acquire an EXCLUSIVE per-workspace lock BEFORE building the connection. Two
+  // `mauto` invocations that both saw isAlive=false would otherwise both spawn a
+  // daemon and both call createCall (spawning mobile-mcp + grabbing the device)
+  // before the loser hits EADDRINUSE. With the lock the loser fails here and
+  // exits before it ever spawns a child. O_EXCL ('wx') is the atomicity.
+  const lockFile = paths.lockPath(projectRoot);
+  let lockFd;
+  try {
+    lockFd = fs.openSync(lockFile, 'wx');
+    fs.writeSync(lockFd, String(process.pid) + '\n');
+  } catch (err) {
+    if (err && err.code === 'EEXIST') {
+      const e = new Error('device session daemon already starting for this workspace (lock held)');
+      e.code = 'ELOCKED';
+      throw e;
+    }
+    throw err;
+  }
+
+  let lockReleased = false;
+  function releaseLock() {
+    if (lockReleased) return;
+    lockReleased = true;
+    try {
+      if (lockFd !== undefined) fs.closeSync(lockFd);
+    } catch (_) {
+      /* ignore */
+    }
+    safeUnlink(lockFile);
+  }
+
+  // Build the single shared connection up front. If it rejects, never leak the
+  // lock (and the child it may have started is the connection's own to clean).
+  let call;
+  let close;
+  try {
+    ({ call, close } = await createCall({ device }));
+  } catch (err) {
+    releaseLock();
+    throw err;
+  }
+
+  let idleTimer = null;
+  let stopping = false;
+  let inFlight = 0; // device calls whose reply has not yet been sent
+  const sockets = new Set();
+  const undeliverable = []; // replies we could not deliver (peer gone / unflushable)
+  let onStop = null; // resolves stop()'s promise
+
+  const notifyUndeliverable =
+    typeof onUndeliverable === 'function'
+      ? onUndeliverable
+      : (info) => {
+          try {
+            process.stderr.write(
+              `mauto-session-daemon: undeliverable reply id=${info.id}: ${info.reason}\n`
+            );
+          } catch (_) {
+            /* stderr gone */
+          }
+        };
+
+  function recordUndeliverable(info) {
+    undeliverable.push(info);
+    notifyUndeliverable(info);
+  }
+
+  const server = net.createServer();
+
+  function clearIdle() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+  }
+
+  function armIdle() {
+    clearIdle();
+    if (stopping) return; // never re-arm once we have begun tearing down
+    if (idleMs > 0 && Number.isFinite(idleMs)) {
+      idleTimer = setTimeout(() => {
+        stop().catch(() => {});
+      }, idleMs);
+      if (typeof idleTimer.unref === 'function') idleTimer.unref();
+    }
+  }
+
+  async function stop() {
+    if (stopping) return;
+    stopping = true;
+    clearIdle();
+
+    // Drain-before-teardown: never destroy a socket or tear down the shared
+    // connection while a device call is still in flight. The action already hit
+    // the device — its reply must be allowed to go out first.
+    while (inFlight > 0) {
+      await new Promise((r) => setTimeout(r, 10));
+    }
+
+    for (const s of sockets) {
+      try {
+        s.destroy();
+      } catch (_) {
+        /* ignore */
+      }
+    }
+    sockets.clear();
+
+    await new Promise((resolve) => server.close(() => resolve()));
+
+    try {
+      await close();
+    } catch (_) {
+      /* best-effort */
+    }
+
+    safeUnlink(paths.socketPath(projectRoot));
+    safeUnlink(paths.pidFilePath(projectRoot));
+    safeUnlink(paths.handlePath(projectRoot));
+    releaseLock();
+
+    process.removeListener('SIGTERM', onSignal);
+    process.removeListener('SIGINT', onSignal);
+
+    if (onStop) onStop();
+  }
+
+  function onSignal() {
+    stop().catch(() => {});
+  }
+
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    const parser = new FrameParser();
+
+    socket.setEncoding('utf8');
+
+    // Honest reply: by the time this runs the device action has ALREADY
+    // happened, so a write that fails must never be silently swallowed.
+    //   - a non-serializable result is converted to an explicit ok:false frame
+    //     rather than dropped (a dropped reply hangs the client to a 30s
+    //     false-failure → retry → double tap / re-granted permission);
+    //   - socket backpressure (write() === false) is awaited via 'drain' so
+    //     large payloads (screenshots, element trees) actually reach the client;
+    //   - a destroyed peer / write error is RECORDED as undeliverable, not
+    //     swallowed.
+    // Returns true when the frame was flushed, false when undeliverable.
+    const reply = async (obj) => {
+      const id = obj && obj.id != null ? obj.id : null;
+      let frame;
+      try {
+        frame = FrameParser.encode(obj);
+      } catch (encErr) {
+        // Result could not be serialized — surface it as an explicit failure
+        // frame instead of dropping the reply entirely.
+        frame = FrameParser.encode({
+          id,
+          ok: false,
+          error: { message: `result not serializable: ${encErr.message || encErr}` },
+        });
+      }
+
+      if (socket.destroyed || !socket.writable) {
+        recordUndeliverable({ id, reason: 'socket destroyed before reply' });
+        return false;
+      }
+
+      let flushed;
+      try {
+        flushed = socket.write(frame);
+      } catch (writeErr) {
+        recordUndeliverable({ id, reason: writeErr.message || String(writeErr) });
+        return false;
+      }
+
+      if (flushed === false) {
+        // Backpressure: wait for the kernel buffer to drain before treating the
+        // reply as delivered. Bail honestly if the peer dies first.
+        try {
+          await new Promise((resolve, reject) => {
+            const cleanup = () => {
+              socket.removeListener('drain', onDrain);
+              socket.removeListener('error', onErr);
+              socket.removeListener('close', onClose);
+            };
+            const onDrain = () => {
+              cleanup();
+              resolve();
+            };
+            const onErr = (e) => {
+              cleanup();
+              reject(e);
+            };
+            const onClose = () => {
+              cleanup();
+              reject(new Error('socket closed before drain'));
+            };
+            socket.once('drain', onDrain);
+            socket.once('error', onErr);
+            socket.once('close', onClose);
+          });
+        } catch (drainErr) {
+          recordUndeliverable({ id, reason: drainErr.message || String(drainErr) });
+          return false;
+        }
+      }
+      return true;
+    };
+
+    socket.on('data', async (chunk) => {
+      const frames = parser.push(chunk);
+      for (const f of frames) {
+        // Pause the idle clock while we handle a frame so it can never fire
+        // mid-call; it is re-armed only AFTER the reply has gone out.
+        clearIdle();
+
+        if (f.error) {
+          await reply({ id: null, ok: false, error: { message: `malformed frame: ${f.error.message}` } });
+          armIdle();
+          continue;
+        }
+        const req = f.value;
+
+        if (req.type === 'shutdown') {
+          await reply({ id: req.id, ok: true, result: { stopping: true } });
+          // Reply already flushed (awaited) — now tear down.
+          setImmediate(() => stop().catch(() => {}));
+          continue;
+        }
+        if (req.type === 'ping') {
+          await reply({ id: req.id, ok: true, result: { pong: true, device, in_flight: inFlight } });
+          armIdle();
+          continue;
+        }
+        if (req.type === 'call') {
+          // A call that arrives after stop() began must be rejected up front:
+          // it never started, so it must not block stop()'s drain (inFlight is
+          // only decremented for calls that actually incremented it).
+          if (stopping) {
+            await reply({
+              id: req.id,
+              ok: false,
+              error: { message: 'session daemon is shutting down', kind: 'device' },
+            });
+            armIdle();
+            continue;
+          }
+          inFlight += 1;
+          try {
+            // Bound the shared mobile-mcp call. The daemon's timeout (25s) is
+            // BELOW the client's (30s) so this error always reaches the client
+            // as an honest {kind:'timeout'} reply instead of being dropped by
+            // the client's own timeout — a dropped reply reads as a
+            // false-failure and prompts a retry → double-execution. The
+            // underlying call is NOT cancellable; it keeps running in the
+            // background, which is fine — the point is the agent gets a bounded,
+            // honest error. Swallow the loser's eventual settlement so it can't
+            // surface as an unhandled rejection after the race already settled.
+            const callPromise = call(req.tool, req.args || {});
+            callPromise.catch(() => {});
+            const result = await Promise.race([
+              callPromise,
+              scheduleTimeout(DAEMON_CALL_TIMEOUT_MS).then(() => {
+                const e = new Error(
+                  `${req.tool}: the mobile-mcp call did not respond within ${DAEMON_CALL_TIMEOUT_MS}ms`
+                );
+                e.kind = 'timeout';
+                e.hint = 'the action may have partially executed on the device — verify state before retrying';
+                throw e;
+              }),
+            ]);
+            await reply({ id: req.id, ok: true, result });
+          } catch (err) {
+            if (err && err.kind === 'timeout') {
+              await reply({
+                id: req.id,
+                ok: false,
+                error: { message: err.message, kind: 'timeout', hint: err.hint },
+              });
+            } else {
+              // Non-timeout failure: no kind → client/deviceFail default to
+              // 'device'. Only the timeout path sets kind:'timeout'.
+              await reply({ id: req.id, ok: false, error: { message: err.message || String(err) } });
+            }
+          } finally {
+            inFlight -= 1;
+            armIdle(); // arm idle only after the reply has completed
+          }
+          continue;
+        }
+        await reply({ id: req.id, ok: false, error: { message: `unknown request type: ${req.type}` } });
+        armIdle();
+      }
+    });
+
+    socket.on('error', () => {
+      sockets.delete(socket);
+    });
+    socket.on('close', () => {
+      sockets.delete(socket);
+    });
+  });
+
+  const socketPath = paths.socketPath(projectRoot);
+
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(socketPath, () => {
+        server.removeListener('error', reject);
+        resolve();
+      });
+    });
+  } catch (err) {
+    // listen failed (e.g. EADDRINUSE from a double-spawn that beat us to the
+    // bind, or a recycled-pid wedge). The connection was already built — close
+    // it so we never leak the mobile-mcp child, and release the lock.
+    try {
+      await close();
+    } catch (_) {
+      /* best-effort */
+    }
+    releaseLock();
+    throw err;
+  }
+
+  // Persist handle + pidfile now that we are actually listening.
+  const handle = {
+    pid: process.pid,
+    device: device || null,
+    socket: socketPath,
+    started_at: new Date().toISOString(),
+    idle_ms: idleMs,
+  };
+  fs.writeFileSync(paths.handlePath(projectRoot), JSON.stringify(handle, null, 2) + '\n');
+  fs.writeFileSync(paths.pidFilePath(projectRoot), String(process.pid) + '\n');
+
+  process.on('SIGTERM', onSignal);
+  process.on('SIGINT', onSignal);
+
+  armIdle();
+
+  return {
+    socketPath,
+    device: device || null,
+    stop,
+    // Replies that could not be delivered (peer gone / unflushable). Surfaced so
+    // callers/tests can observe transport failures instead of them being eaten.
+    undeliverable,
+    // Resolves when the daemon has fully stopped (idle reap / signal / shutdown).
+    whenStopped: new Promise((resolve) => {
+      onStop = resolve;
+    }),
+  };
+}
+
+module.exports = { startDaemon, cleanStale, pidAlive, pidIdentity, DAEMON_CALL_TIMEOUT_MS, DEFAULT_IDLE_MS };

package/src/device/session-paths.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// Pure path helpers for the per-workspace device session daemon.
+//
+// Everything lives under <projectRoot>/mobile-automator/.session/:
+//   mauto.sock    — Unix domain socket the daemon listens on
+//   daemon.pid    — pidfile written once the daemon is listening
+//   session.json  — handle describing the live session (device pin, socket, pid)
+//
+// These are intentionally side-effect-free so they can be unit-tested without
+// touching the filesystem.
+
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const SESSION_DIRNAME = '.session';
+const SOCKET_NAME = 'mauto.sock';
+const PID_NAME = 'daemon.pid';
+const HANDLE_NAME = 'session.json';
+const LOCK_NAME = 'daemon.lock';
+
+// Unix domain socket paths have a hard length limit (~104 bytes on macOS,
+// ~108 on Linux). Deep project roots blow past it, so when the in-workspace
+// path would be too long we fall back to a short, deterministic socket path in
+// the OS temp dir keyed by a hash of the project root. pidfile + handle always
+// stay in the workspace (per-workspace ownership), and the handle records the
+// actual socket path it bound.
+const SOCKET_PATH_LIMIT = 100;
+
+function sessionDir(projectRoot) {
+  return path.join(projectRoot, 'mobile-automator', SESSION_DIRNAME);
+}
+
+// The canonical in-workspace socket path. Used when short enough.
+function workspaceSocketPath(projectRoot) {
+  return path.join(sessionDir(projectRoot), SOCKET_NAME);
+}
+
+// The path the daemon binds and the client connects to. Deterministic from the
+// project root so both sides agree without reading the handle.
+function socketPath(projectRoot) {
+  const inWorkspace = workspaceSocketPath(projectRoot);
+  if (Buffer.byteLength(inWorkspace) <= SOCKET_PATH_LIMIT) return inWorkspace;
+  const hash = crypto
+    .createHash('sha1')
+    .update(path.resolve(projectRoot))
+    .digest('hex')
+    .slice(0, 16);
+  return path.join(os.tmpdir(), `mauto-${hash}.sock`);
+}
+
+function pidFilePath(projectRoot) {
+  return path.join(sessionDir(projectRoot), PID_NAME);
+}
+
+function handlePath(projectRoot) {
+  return path.join(sessionDir(projectRoot), HANDLE_NAME);
+}
+
+// Exclusive workspace lock acquired BEFORE building the mobile-mcp connection so
+// a double-spawn loser fails fast and exits before it ever spawns a child.
+function lockPath(projectRoot) {
+  return path.join(sessionDir(projectRoot), LOCK_NAME);
+}
+
+module.exports = {
+  SESSION_DIRNAME,
+  SOCKET_NAME,
+  PID_NAME,
+  HANDLE_NAME,
+  LOCK_NAME,
+  SOCKET_PATH_LIMIT,
+  sessionDir,
+  workspaceSocketPath,
+  socketPath,
+  pidFilePath,
+  handlePath,
+  lockPath,
+};

package/src/device/session-protocol.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// Newline-delimited JSON framing for the device session daemon protocol.
+//
+// The client sends request frames; the daemon replies with response frames.
+// Each frame is a single JSON object terminated by exactly one '\n'. Requests
+// carry an `id` so a client can correlate responses on a multiplexed socket.
+//
+// Request frames:
+//   { id, type: 'call', tool, args }     — route a mobile-mcp tool call
+//   { id, type: 'shutdown' }             — control: ask the daemon to exit
+//   { id, type: 'ping' }                 — liveness probe
+//
+// Response frames:
+//   { id, ok: true, result }
+//   { id, ok: false, error: { message } }
+//
+// FrameParser owns the framing on both sides: encode() writes a frame, push()
+// buffers partial chunks and yields whole frames. A malformed line is REPORTED
+// (yielded as an error frame), never thrown — a single bad line must not kill
+// the connection. (The encode/decode of a single frame is a JSON.stringify /
+// JSON.parse one-liner with no independent reason to live as separate exports,
+// so they fold into the one module that earns its keep.)
+
+const NL = '\n';
+
+// Buffers byte chunks and yields one parsed object per complete '\n'-terminated
+// line. push() returns an array of results; each result is either
+// { value } for a parsed object or { error, line } for a malformed line.
+class FrameParser {
+  // Serialize a request/response object to one newline-terminated wire frame.
+  static encode(obj) {
+    return JSON.stringify(obj) + NL;
+  }
+
+  constructor() {
+    this._buf = '';
+  }
+
+  push(chunk) {
+    this._buf += chunk == null ? '' : String(chunk);
+    const out = [];
+    let idx;
+    while ((idx = this._buf.indexOf(NL)) !== -1) {
+      const line = this._buf.slice(0, idx);
+      this._buf = this._buf.slice(idx + 1);
+      if (line.length === 0) continue; // tolerate blank lines
+      try {
+        out.push({ value: JSON.parse(line) });
+      } catch (err) {
+        out.push({ error: err, line });
+      }
+    }
+    return out;
+  }
+}
+
+module.exports = {
+  FrameParser,
+};