@talotrace/connect 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,45 @@
+# @talotrace/connect
+
+Lets TaloTrace's cloud browser and phones test the app running on your laptop, and gives your coding agent the
+TaloTrace MCP tools. Node 18 or newer; npm installs the build for your OS (macOS, Linux arm64/x64, Windows x64).
+
+```
+npx @talotrace/connect login                # once: signs in through your browser
+npx @talotrace/connect 3000                 # serve http://localhost:3000 to TaloTrace runs until Ctrl-C
+npx @talotrace/connect mcp                  # the MCP server for Claude Code, Cursor, Codex
+npx @talotrace/connect --help               # every command
+```
+
+Set `TALOTRACE_URL` to your TaloTrace API (pilot: `https://dev.api.talotrace.ai`) or pass `--url`.
+
+## A page and its API on two ports
+
+`talotrace-connect 5173 8787` serves both ports in one session, but a run opens your page at its own https address,
+not at `localhost:5173`. A `fetch("http://localhost:8787/...")` from the page therefore stays inside the cloud browser
+and is refused there. Until the cloud browser maps `localhost` ports itself, call the API with a relative URL and let
+your dev server proxy it:
+
+- Vite: `server: { proxy: { '/api': 'http://localhost:8787' } }`
+- Next.js: `rewrites()` returning `{ source: '/api/:path*', destination: 'http://localhost:8787/api/:path*' }`
+
+Then `talotrace-connect 5173` is enough.
+
+## Several apps at once
+
+Each `talotrace-connect` holds a session of its own, so an app and its API (or two apps) can run in two terminals at
+the same time. One person may hold up to five sessions open at once; past that, a new one is refused with a message
+saying so. Ctrl-C ends a session at once; a killed one counts until its two-minute grace window ends.
+
+## Stopping
+
+Ctrl-C, SIGTERM or a closed terminal stops it within 2 seconds and ends its session (`dev` may take up to 30 seconds:
+it releases the phone and closes a cloud workspace first). A second Ctrl-C stops it at once. The stdio MCP server stops when your agent closes it.
+
+If the binary stops responding (for example, the disk holding npm's cache was unplugged, which leaves a program unable
+to run its own code), the launcher stops it after 5 seconds and says so.
+
+## Exit codes
+
+`0` done or stopped, `1` failure, `2` usage, `3` TaloTrace ended the session, `4` you ended it, `5` the session expired,
+`6` the relay refused its credential, `7` another `talotrace-connect` took the session over, `8` it did not finish
+stopping within its budget, `9` it stopped responding and the launcher stopped it.

package/bin/talotrace-connect.js

@@ -3,6 +3,14 @@
 
 const { spawn } = require('node:child_process');
 const { binaryPath } = require('../lib/resolve');
+const {
+  ALIVE_ENV,
+  ALIVE_FD,
+  ALIVE_INTERVAL_MS,
+  EXIT_UNRESPONSIVE,
+  UNRESPONSIVE_MESSAGE,
+  aliveWatch,
+} = require('../lib/alive');
 
 let binary;
 try {
@@ -12,17 +20,49 @@ try {
   process.exit(1);
 }
 
-// stdio is inherited: `mcp` speaks the protocol on this process's stdin and stdout.
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+// stdio is inherited: `mcp` speaks the protocol on this process's stdin and stdout. Off Windows the
+// child also gets the alive pipe (lib/alive.js); Windows passes handles, not descriptors.
+const watched = process.platform !== 'win32';
+const stdio = watched ? ['inherit', 'inherit', 'inherit', 'pipe'] : 'inherit';
+const env = watched ? { ...process.env, [ALIVE_ENV]: String(ALIVE_FD) } : process.env;
+const child = spawn(binary, process.argv.slice(2), { stdio, env });
+
+// The first signal is passed on and the binary stops within its own shutdown budget; a second one
+// kills it now.
+let stopping = false;
 for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
-  process.on(signal, () => child.kill(signal));
+  process.on(signal, () => {
+    child.kill(stopping ? 'SIGKILL' : signal);
+    stopping = true;
+  });
+}
+
+let unresponsive = false;
+let looking = null;
+if (watched) {
+  const watch = aliveWatch(Date.now);
+  child.stdio[ALIVE_FD].on('data', () => watch.beat());
+  child.stdio[ALIVE_FD].on('error', () => {}); // the child exiting closes it; 'exit' reports that
+  looking = setInterval(() => {
+    if (watch.look()) {
+      clearInterval(looking);
+      unresponsive = true;
+      console.error(UNRESPONSIVE_MESSAGE);
+      child.kill('SIGKILL');
+    }
+  }, ALIVE_INTERVAL_MS);
 }
+
 child.on('error', (error) => {
   console.error(`could not start ${binary}: ${error.message}`);
   process.exit(1);
 });
 child.on('exit', (code, signal) => {
-  if (signal) {
+  clearInterval(looking);
+  if (unresponsive) {
+    process.exit(EXIT_UNRESPONSIVE);
+  } else if (signal) {
+    process.removeAllListeners(signal); // so the signal ends this process as it ended the child
     process.kill(process.pid, signal);
   } else {
     process.exit(code ?? 1);

package/lib/alive.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// The launcher's watch on the Go binary. The binary writes one byte to an extra pipe every second
+// (cmd/talotrace-connect/shutdown.go; keep ALIVE_ENV and ALIVE_INTERVAL_MS equal to envAliveFD and
+// aliveInterval there). A binary whose program file sat on a disk that went away cannot run its own
+// code any more: it spins at full CPU and never handles a signal, so only SIGKILL from outside stops it
+// (31 Oct 2026: two clients spun for 8 hours after an external disk dropped out). The launcher runs from
+// node, which is on another disk, so it notices the silence and does that.
+
+/** The environment variable that tells the binary which file descriptor its alive pipe is. */
+const ALIVE_ENV = 'TALOTRACE_CONNECT_ALIVE_FD';
+/** The alive pipe's file descriptor in the child (after stdin, stdout and stderr). */
+const ALIVE_FD = 3;
+/** How often the binary writes, and how often the launcher looks. */
+const ALIVE_INTERVAL_MS = 1000;
+/** A binary silent this long is stopped. */
+const SILENT_LIMIT_MS = 5000;
+/** The launcher's exit code after it stopped a silent binary (the binary's own codes are 0-8). */
+const EXIT_UNRESPONSIVE = 9;
+/** What the launcher prints when it does. */
+const UNRESPONSIVE_MESSAGE =
+  'talotrace-connect stopped responding (was its program file on a disk that went away?); stopped it';
+
+/**
+ * Tracks the binary's beats. `look()` is called every ALIVE_INTERVAL_MS and says whether the binary
+ * has been silent for longer than SILENT_LIMIT_MS. When the looks themselves were late (the laptop
+ * slept, so the binary could not write either), the silence starts again from now.
+ */
+function aliveWatch(now) {
+  let lastBeat = now();
+  let lastLook = lastBeat;
+  return {
+    beat() {
+      lastBeat = now();
+    },
+    look() {
+      const at = now();
+      if (at - lastLook > 2 * ALIVE_INTERVAL_MS) {
+        lastBeat = at;
+      }
+      lastLook = at;
+      return at - lastBeat > SILENT_LIMIT_MS;
+    },
+  };
+}
+
+module.exports = {
+  ALIVE_ENV,
+  ALIVE_FD,
+  ALIVE_INTERVAL_MS,
+  SILENT_LIMIT_MS,
+  EXIT_UNRESPONSIVE,
+  UNRESPONSIVE_MESSAGE,
+  aliveWatch,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talotrace/connect",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TaloTrace Connect: the TaloTrace MCP server for your coding agent, with a tunnel to the app on your laptop.",
   "license": "UNLICENSED",
   "bin": {
@@ -18,10 +18,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@talotrace/connect-darwin-arm64": "0.4.0",
-    "@talotrace/connect-darwin-x64": "0.4.0",
-    "@talotrace/connect-linux-arm64": "0.4.0",
-    "@talotrace/connect-linux-x64": "0.4.0",
-    "@talotrace/connect-win32-x64": "0.4.0"
+    "@talotrace/connect-darwin-arm64": "0.6.0",
+    "@talotrace/connect-darwin-x64": "0.6.0",
+    "@talotrace/connect-linux-arm64": "0.6.0",
+    "@talotrace/connect-linux-x64": "0.6.0",
+    "@talotrace/connect-win32-x64": "0.6.0"
   }
 }