meshingly-mcp 0.1.0 → 0.3.0

package/README.md

@@ -32,10 +32,28 @@ Other tools take the same command as a local stdio server: `npx -y meshingly-mcp
 | `meshingly_peers` | Lists the other sessions in the collaboration |
 | `meshingly_send` | Sends an encrypted message to the others |
 | `meshingly_receive` | Reads new messages, optionally waiting for one |
+| `meshingly_handoff`, `meshingly_queue`, `meshingly_claim`, `meshingly_release`, `meshingly_done` | A work queue: park unfinished work, list it, take it over, give it back, finish it |
+| `meshingly_watch_start`, `meshingly_watch_stop`, `meshingly_watch_status` | Optional background watcher that restarts queued work (see below) |
+| `meshingly_journal` | Writes a short note for the other sessions (only if you turned the journal on) |
+| `meshingly_settings` | Shows your preferences, and changes them when you ask your agent to |
+
+## Several computers and handing work over
+
+The same person can join one collaboration from several computers; each session is labelled with a computer name you choose (not the host name). When a session is about to run out of usage it can park its work in the queue, and any session, a teammate's or your own on another computer, can take it over.
+
+## Remembering what the other sessions did
+
+Two settings, both off until you turn them on (just ask your agent, or use the terminal). `journal` (`milestones` or `detailed`) lets sessions write short notes for the others with `meshingly_journal`; `catchUp` (a number of entries) adds a digest of the latest notes, handoffs and messages to the join and status results, so a session on another computer already knows what happened. Everyone in a collaboration can read its notes, so sessions are told never to write secrets in them. Messages are kept by the relay for seven days; code travels through git, not through Meshingly.
+
+## The optional watcher
+
+A session that has ended cannot wake itself. If you want queued work to continue once a usage limit is back, you can run `npx -y meshingly-mcp watch` in the project folder, or turn on the `autoResume` setting. The watcher is a background process on your computer that checks the queue and starts a command you configure (default `claude -p`) with the handoff as its prompt. **It is off by default.** Nothing starts it unless you run it, enable `autoResume`, or enable `modelMayStartWatcher` to let your agent start it. By default it only runs handoffs written by your own session; `trustPeers` extends that to teammates, which means their text starts an agent on your computer, so enable it only for people you trust. Handoffs marked as a question for a person are never run.
+
+Settings live in your home folder, not in the project (so a repository cannot ship them), and you can change them by asking your agent ("turn on the journal", "let every session know what the others did") or in a terminal: `npx -y meshingly-mcp settings` lists them and `settings set <key> <value>` changes one. The agent changes the harmless ones (journal, catch-up, retry tuning, switching things off) when you ask. The ones that make programs start on your computer (`autoResume`, `resumeCommand`, `trustPeers`, `onQuestion: recommended`, `modelMayStartWatcher`) need your approval: your client asks you directly, outside the model's reach, and if it cannot ask, nothing changes and you are given the terminal command instead.
 
 ## What it runs, stores and sends
 
-The server runs locally over stdio and starts no other program. Creating a collaboration generates a random key on your machine. It is stored in `.meshingly/connection.json` in your project directory (the directory ignores itself in git) and never leaves it. The only network traffic goes to `https://api.meshingly.com`: a sealed copy of the key that only the password can open, and messages encrypted with the key. Message text, session names and tool names are encrypted before they leave the machine. The relay keeps messages for seven days. Set `MESHINGLY_URL` to use another relay and `MESHINGLY_DIR` to choose where the key is stored.
+Unless you start the watcher described above, the server runs locally over stdio and starts no other program. Creating a collaboration generates a random key on your machine. It is stored in `.meshingly/connection.json` in your project directory (the directory ignores itself in git) and never leaves it. The only network traffic goes to `https://api.meshingly.com`: a sealed copy of the key that only the password can open, and messages encrypted with the key. Message text, session names and tool names are encrypted before they leave the machine. The relay keeps messages for seven days. Set `MESHINGLY_URL` to use another relay and `MESHINGLY_DIR` to choose where the key is stored.
 
 Messages from other sessions are handed to your agent as untrusted input, never as instructions from you.
 

package/dist/background.js

@@ -0,0 +1,183 @@
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveSettings } from "./settings.js";
+
+const MAX_LOG_BYTES = 1_000_000;
+/** The watcher process writes a heartbeat this often; a pid alone is not proof that the process is still our watcher. */
+export const BEAT_MS = 30_000;
+const BEAT_STALE_MS = 5 * 60_000;
+const START_GRACE_MS = 30_000;
+
+                         
+              
+                    
+                  
+                     
+ 
+
+                               
+                   
+                         
+                  
+ 
+
+const dir = (root        ) => join(root, ".meshingly");
+const recordFile = (root        ) => join(dir(root), "watch.json");
+const beatFile = (root        ) => join(dir(root), "watch.beat");
+const logFile = (root        ) => join(dir(root), "watch.log");
+const lockFile = (root        ) => join(dir(root), "watch.lock");
+export const stateFile = (root        ) => join(dir(root), "watch-state.json");
+
+/** The handoff a watcher was running when it stopped (killed, crashed): the caller gives it back. */
+export function takeCurrentRun(root        )                     {
+  try {
+    if (!existsSync(stateFile(root))) return undefined;
+    const raw = JSON.parse(readFileSync(stateFile(root), "utf8"))                           ;
+    if (typeof raw.current !== "string") return undefined;
+    const id = raw.current;
+    delete raw.current;
+    writeFileSync(stateFile(root), JSON.stringify(raw));
+    return id;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeBeat(root        )       {
+  try {
+    mkdirSync(dir(root), { recursive: true });
+    writeFileSync(beatFile(root), String(Date.now()));
+  } catch {
+    /* a missed beat only makes the watcher look stale for a moment */
+  }
+}
+
+export function clearBeat(root        )       {
+  rmSync(beatFile(root), { force: true });
+}
+
+function alive(pid        )          {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but is not ours to signal.
+    return (err                         ).code === "EPERM";
+  }
+}
+
+/** Ends a process and everything it started: with `shell: true` the pid is the shell's, and a plain kill would leave the agent running. */
+export function killTree(pid        )       {
+  if (process.platform === "win32") {
+    spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+    return;
+  }
+  // Children are started detached (their own process group), so the negative pid reaches the whole group.
+  for (const target of [-pid, pid]) {
+    try {
+      process.kill(target, "SIGTERM");
+      return;
+    } catch {
+      /* try the single process, then give up: it is already gone */
+    }
+  }
+}
+
+/**
+ * A watcher counts as running only when its pid is alive AND it has a fresh heartbeat (or has only just been started).
+ * After a crash or a reboot the pid may belong to an unrelated process; without the heartbeat check Meshingly would
+ * refuse to start a new watcher and, worse, stop would kill a stranger.
+ */
+export function watcherState(root        )               {
+  const file = recordFile(root);
+  if (!existsSync(file)) return { running: false, logFile: logFile(root) };
+  try {
+    const record = JSON.parse(readFileSync(file, "utf8"))                 ;
+    if (!alive(record.pid)) return { running: false, record, logFile: logFile(root) };
+    const now = Date.now();
+    const beat = existsSync(beatFile(root)) ? now - statSync(beatFile(root)).mtimeMs : Infinity;
+    const young = now - Date.parse(record.startedAt) < START_GRACE_MS;
+    return { running: beat < BEAT_STALE_MS || young, record, logFile: logFile(root) };
+  } catch {
+    return { running: false, logFile: logFile(root) };
+  }
+}
+
+/** Starts `meshingly-mcp watch` detached, so it keeps running after this session (and its MCP server) ended. */
+export function startWatcher(root        , entry        )         {
+  const state = watcherState(root);
+  if (state.running) return `The watcher is already running (pid ${state.record .pid}, since ${state.record .startedAt}). Log: ${state.logFile}`;
+  if (!entry || !existsSync(entry)) throw new Error("cannot find the script that starts the watcher");
+
+  // Two servers starting together (two sessions in one project) must not both start a watcher: one would be orphaned.
+  mkdirSync(dir(root), { recursive: true });
+  let lock        ;
+  try {
+    lock = openSync(lockFile(root), "wx");
+  } catch {
+    if (existsSync(lockFile(root)) && Date.now() - statSync(lockFile(root)).mtimeMs < 30_000) return "A watcher is being started right now.";
+    rmSync(lockFile(root), { force: true }); // left behind by a start that died
+    lock = openSync(lockFile(root), "wx");
+  }
+  try {
+    const again = watcherState(root);
+    if (again.running) return `The watcher is already running (pid ${again.record .pid}, since ${again.record .startedAt}). Log: ${again.logFile}`;
+    return launch(root, entry);
+  } finally {
+    closeSync(lock);
+    rmSync(lockFile(root), { force: true });
+  }
+}
+
+function launch(root        , entry        )         {
+
+  // The watcher reads the same settings itself; the flags pin what this start saw, so a later edit needs a restart.
+  const { resumeCommand: command, trustPeers: fromPeers, onQuestion, maxAttempts, checkIntervalSeconds, settleMinutes } = resolveSettings(root).values;
+  mkdirSync(dir(root), { recursive: true });
+  writeFileSync(join(dir(root), ".gitignore"), "*\n");
+  const log = logFile(root);
+  if (existsSync(log) && statSync(log).size > MAX_LOG_BYTES) rmSync(log);
+  const fd = openSync(log, "a", 0o600);
+  try {
+    const args = [
+      entry, "watch", "--dir", root, "--cmd", command, "--on-question", onQuestion,
+      "--max-attempts", String(maxAttempts), "--interval", String(checkIntervalSeconds), "--settle-minutes", String(settleMinutes),
+      ...(fromPeers ? ["--from-peers"] : []),
+    ];
+    const child = spawn(process.execPath, args, { detached: true, stdio: ["ignore", fd, fd], windowsHide: true, env: process.env });
+    // Without a listener a failed spawn would be an uncaught exception that takes the MCP server down with it.
+    child.on("error", (err) => console.error(`meshingly: the watcher process failed: ${err.message}`));
+    child.unref();
+    if (!child.pid) throw new Error("the watcher process did not start");
+    const record                = { pid: child.pid, startedAt: new Date().toISOString(), command, fromPeers };
+    writeFileSync(recordFile(root), JSON.stringify(record, null, 2), { mode: 0o600 });
+  } finally {
+    closeSync(fd);
+  }
+  return [
+    `Watcher started. It checks the queue every ${checkIntervalSeconds} s and, once a handoff is ready, runs: ${command}`,
+    onQuestion === "recommended" ? "If a run would ask a question it takes the recommended option and notes the assumption." : "If a run would need an answer it parks the question for a person.",
+    fromPeers ? "It also runs handoffs written by other sessions (trustPeers)." : "It runs only handoffs written by this project's own session.",
+    `It keeps running after this session ends, for as long as this computer is on. Log: ${log}. Stop it with meshingly_watch_stop. Settings: meshingly_settings.`,
+  ].join("\n");
+}
+
+export function stopWatcher(root        )         {
+  const state = watcherState(root);
+  rmSync(recordFile(root), { force: true });
+  if (!state.running || !state.record) {
+    clearBeat(root);
+    return "No watcher is running.";
+  }
+  const { pid } = state.record;
+  killTree(pid);
+  clearBeat(root);
+  return `Watcher stopped (pid ${pid}).`;
+}
+
+export function describeWatcher(root        )         {
+  const s = watcherState(root);
+  if (!s.running || !s.record) return "No watcher is running.";
+  return `Watcher running (pid ${s.record.pid}, since ${s.record.startedAt}), command: ${s.record.command}${s.record.fromPeers ? ", also for peers' handoffs" : ", own handoffs only"}. Log: ${s.logFile}`;
+}