meshingly-mcp 0.1.0 → 0.2.0

package/dist/settings.js

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * Per-project preferences of the person using Meshingly. They are changed from a terminal (`meshingly-mcp settings`),
+ * never through an MCP tool: the settings decide what runs unattended on this computer, so a model that a peer's
+ * message talked into something must not be able to change them. (An agent with shell access could still edit the
+ * file, exactly as it could edit its own permission settings: the guarantee is about the tool surface.)
+ *
+ * They live in the user's home directory, keyed by the project's path, and NOT in the project's own `.meshingly/`:
+ * a repository can ship a `.meshingly/` folder, and a command to run unattended must never come from there.
+ */
+                           
+                                                                                            
+                      
+                                                                        
+                        
+                                                                                  
+                      
+                                                                                   
+                                     
+                                                                                         
+                                
+                                                                                                                                         
+                        
+                                                                   
+                      
+                                      
+                               
+ 
+
+                                                                                                                                      
+
+export const SETTING_INFO                                                                                                               = {
+  autoResume: {
+    kind: { type: "boolean" },
+    default: false,
+    env: "MESHINGLY_AUTOWATCH",
+    description: "Start the background watcher automatically, so queued work continues after the usage limit is back.",
+  },
+  resumeCommand: {
+    kind: { type: "string" },
+    default: "claude -p",
+    env: "MESHINGLY_WATCH_CMD",
+    description: "Command that receives the handoff on stdin and continues the work. Add the permissions it needs yourself.",
+  },
+  trustPeers: {
+    kind: { type: "boolean" },
+    default: false,
+    env: "MESHINGLY_WATCH_FROM_PEERS",
+    description: "Also run handoffs written by teammates. Their text starts an agent on this computer: only for people you trust.",
+  },
+  onQuestion: {
+    kind: { type: "enum", values: ["stop", "recommended"] },
+    default: "stop",
+    description:
+      "When an unattended run would ask a question: stop = park the question for a person; recommended = take the option it recommends, note the assumption and carry on (never for deleting, spending, publishing or pushing).",
+  },
+  modelMayStartWatcher: {
+    kind: { type: "boolean" },
+    default: false,
+    description: "Let an AI session start the background watcher with its meshingly_watch_start tool. Off: only you start it (watch command, or autoResume).",
+  },
+  settleMinutes: {
+    kind: { type: "int", min: 0, max: 240 },
+    default: 5,
+    description: "How long a handoff without a limit-reset time waits before the watcher runs it, in case the session that parked it is still working.",
+  },
+  maxAttempts: { kind: { type: "int", min: 1, max: 10 }, default: 3, description: "Failed runs per handoff before the watcher gives up on it." },
+  checkIntervalSeconds: { kind: { type: "int", min: 5, max: 3600 }, default: 60, description: "Seconds between queue checks." },
+};
+
+export const SETTING_KEYS = Object.keys(SETTING_INFO)                         ;
+
+/** Where this project's settings are kept: under the user's home (MESHINGLY_HOME overrides it, for tests), keyed by the project's path. */
+export function settingsPath(root        )         {
+  // The same folder must give the same file however it was spelled (c:\dev vs C:\Dev, a symlink): otherwise a setting
+  // made from one shell would be silently ignored by a server started from another.
+  let real = resolve(root);
+  try {
+    real = realpathSync.native(real);
+  } catch {
+    /* the folder does not exist (yet): use the path as given */
+  }
+  const key = createHash("sha256").update(process.platform === "win32" ? real.toLowerCase() : real).digest("hex").slice(0, 16);
+  return join(process.env.MESHINGLY_HOME ?? join(homedir(), ".meshingly"), "projects", `${key}.json`);
+}
+const file = settingsPath;
+
+/** Turns text into a valid value for the setting, or says why not. */
+export function parseSetting(key                , raw         )                                                                                {
+  const { kind } = SETTING_INFO[key];
+  const text = typeof raw === "string" ? raw.trim() : raw;
+  switch (kind.type) {
+    case "boolean": {
+      if (typeof text === "boolean") return { ok: true, value: text };
+      const t = String(text).toLowerCase();
+      if (["true", "on", "yes", "1"].includes(t)) return { ok: true, value: true };
+      if (["false", "off", "no", "0"].includes(t)) return { ok: true, value: false };
+      return { ok: false, reason: "use true or false" };
+    }
+    case "enum":
+      return typeof text === "string" && kind.values.includes(text) ? { ok: true, value: text } : { ok: false, reason: `use one of: ${kind.values.join(", ")}` };
+    case "int": {
+      const n = typeof text === "number" ? text : Number(text);
+      return Number.isInteger(n) && n >= kind.min && n <= kind.max ? { ok: true, value: n } : { ok: false, reason: `use a whole number from ${kind.min} to ${kind.max}` };
+    }
+    case "string":
+      return typeof text === "string" && text.length > 0 && text.length <= 300 && !/[\r\n]/.test(text) ? { ok: true, value: text } : { ok: false, reason: "use a single line of 1 to 300 characters" };
+  }
+}
+
+                           
+                   
+                                                                                                     
+                                                                      
+                                                                          
+                   
+ 
+
+export function resolveSettings(root        , env                    = process.env)           {
+  const values = Object.fromEntries(SETTING_KEYS.map((k) => [k, SETTING_INFO[k].default]))                       ;
+  const sources = Object.fromEntries(SETTING_KEYS.map((k) => [k, "default"]))                       ;
+  let problem                    ;
+
+  if (existsSync(file(root))) {
+    try {
+      const stored = JSON.parse(readFileSync(file(root), "utf8"))                           ;
+      for (const k of SETTING_KEYS) {
+        if (!(k in stored)) continue;
+        const parsed = parseSetting(k, stored[k]);
+        if (parsed.ok) {
+          (values                                      )[k] = parsed.value;
+          sources[k] = "file";
+        } else {
+          problem = `${k} in the settings file is invalid (${parsed.reason}); the default is used`;
+        }
+      }
+    } catch (err) {
+      problem = `the settings file could not be read (${err instanceof Error ? err.message : String(err)}); the defaults are used`;
+    }
+  }
+  for (const k of SETTING_KEYS) {
+    const name = SETTING_INFO[k].env;
+    const raw = name ? env[name] : undefined;
+    if (!name || raw === undefined || raw === "") continue;
+    const parsed = parseSetting(k, raw);
+    if (parsed.ok) {
+      (values                                      )[k] = parsed.value;
+      sources[k] = "environment";
+    }
+  }
+  return { values, sources, ...(problem ? { problem } : {}) };
+}
+
+/** Writes one setting to the project's settings file. Throws an Error whose message says what is wrong. */
+export function writeSetting(root        , key        , raw        )           {
+  if (!SETTING_KEYS.includes(key                  )) throw new Error(`Unknown setting "${key}". Settings: ${SETTING_KEYS.join(", ")}.`);
+  const k = key                  ;
+  const parsed = parseSetting(k, raw);
+  if (!parsed.ok) throw new Error(`${k}: ${parsed.reason}.`);
+  let stored                          = {};
+  try {
+    if (existsSync(file(root))) stored = JSON.parse(readFileSync(file(root), "utf8"))                           ;
+  } catch {
+    stored = {}; // a broken file is replaced, not extended
+  }
+  stored[k] = parsed.value;
+  mkdirSync(dirname(file(root)), { recursive: true });
+  const tmp = `${file(root)}.tmp`;
+  writeFileSync(tmp, JSON.stringify(stored, null, 2), { mode: 0o600 });
+  renameSync(tmp, file(root));
+  return resolveSettings(root).values;
+}
+
+export function resetSettings(root        )       {
+  rmSync(file(root), { force: true });
+}
+
+export function describeSettings(root        , env                    = process.env)         {
+  const { values, sources, problem } = resolveSettings(root, env);
+  const lines = SETTING_KEYS.map((k) => `${k.padEnd(21)} ${String(values[k]).padEnd(12)} ${sources[k] === "default" ? "(default)" : `(${sources[k]})`}  ${SETTING_INFO[k].description}`);
+  lines.push("", `File: ${settingsPath(root)}`);
+  if (problem) lines.push(`Note: ${problem}.`);
+  return lines.join("\n");
+}
+
+/** Appended to the prompt of an unattended run. */
+export function questionPolicy(onQuestion                        )         {
+  if (onQuestion === "stop") {
+    return "Nobody is at the keyboard. If you need an answer from the user to go on, do not guess: call meshingly_handoff with needsPerson=true, the question and what you have done so far, then stop.";
+  }
+  return [
+    "Nobody is at the keyboard, and the user chose that you carry on instead of waiting.",
+    "When you would ask the user to choose, take the option you would recommend, write down the assumption you made, and continue. Put every such assumption in your final summary and in meshingly_done.",
+    "Exception: never decide for the user anything that deletes data, spends money, publishes, pushes, or contacts other people. For those, call meshingly_handoff with needsPerson=true, the question and what you have done so far, then stop.",
+  ].join(" ");
+}

package/dist/watch.js

@@ -0,0 +1,328 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { BEAT_MS, clearBeat, killTree, stateFile, takeCurrentRun, writeBeat } from "./background.js";
+import { Meshingly, ToolError } from "./connection.js";
+import { LEASE_MS } from "./queue.js";
+import { questionPolicy, resolveSettings,               } from "./settings.js";
+
+                               
+                                                                                          
+                  
+                     
+                                                                             
+                
+                                                                              
+                     
+                                                                              
+                                     
+                                                             
+                      
+                                                                                                                  
+                   
+                                                                                                                 
+                   
+                                                                                                              
+                    
+                      
+                              
+ 
+
+const HELP = `meshingly-mcp watch: wakes up an AI session when work is waiting in the Meshingly queue.
+
+Usage: npx -y meshingly-mcp watch [--cmd "claude -p"] [--interval 60] [--once] [--from-peers] [--on-question stop|recommended] [--dir <project>]
+
+It checks the queue; when a handoff is open and its "limit expected back" time has passed (a handoff without one
+waits a few minutes, in case its session is still working), it claims the handoff and starts the command with the
+handoff as the prompt, in the project directory. If the command succeeds the handoff is marked finished. If it fails
+(for example the usage limit is still out) the handoff goes back to the queue and is retried later, up to
+--max-attempts times. Handoffs marked as a question for a person are never run.
+
+  --cmd             Command that reads the prompt from stdin. Default: claude -p
+                    Add the permissions the work needs yourself, e.g. "claude -p --permission-mode acceptEdits".
+  --interval        Seconds between checks. Default 60.
+  --once            Check once and exit, so cron or Task Scheduler can run it.
+  --from-peers      Also run handoffs written by OTHER sessions. By default only this project's own session is
+                    trusted, because a handoff is text that starts an AI agent on your computer: enable this
+                    only for a collaboration whose members you trust.
+  --on-question     What a run does when it would ask you something: stop (default) or recommended.
+  --max-attempts    Default 3.
+  --settle-minutes  Default 5.
+  --dir             Project directory holding .meshingly/. Default: the current directory.
+
+Every option has a setting that is used when the flag is absent: npx -y meshingly-mcp settings
+`;
+
+function sleep(ms        , signal             )                {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const done = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+/** Runs the command with the prompt on stdin and resolves with its exit code (124 when it was stopped for running too long). */
+function runCommand(command        , prompt        , cwd        , env                   , maxRunMs        , signal             )                  {
+  return new Promise((resolve, reject) => {
+    // Detached on POSIX: its own process group, so a timeout can end the agent and not just the shell around it.
+    const child = spawn(command, { shell: true, cwd, env, stdio: ["pipe", "inherit", "inherit"], detached: process.platform !== "win32" });
+    let timedOut = false;
+    const stop = () => {
+      if (child.pid) killTree(child.pid);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stop();
+    }, maxRunMs);
+    signal.addEventListener("abort", stop, { once: true });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", stop);
+      resolve(timedOut ? 124 : (code ?? 1));
+    });
+    // A command that exits before reading its input closes the pipe: that is a failed run, not a crash of the watcher.
+    child.stdin.on("error", () => {});
+    child.stdin.end(prompt);
+  });
+}
+
+/** Failed attempts and retry times per handoff, kept on disk: `--once` under cron and every restart would otherwise start from zero. */
+                 
+                                
+                               
+                                                                                                            
+                   
+ 
+
+function loadState(root        )        {
+  const st        = { attempts: new Map(), retryAt: new Map() };
+  try {
+    if (!existsSync(stateFile(root))) return st;
+    const raw = JSON.parse(readFileSync(stateFile(root), "utf8"))                                                                             ;
+    for (const [id, n] of Object.entries(raw.attempts ?? {})) if (typeof n === "number") st.attempts.set(id, n);
+    for (const [id, n] of Object.entries(raw.retryAt ?? {})) if (typeof n === "number") st.retryAt.set(id, n);
+  } catch {
+    /* a damaged file means a fresh start, not a crash */
+  }
+  return st;
+}
+
+/** Writes the state, keeping only handoffs that still exist. */
+function saveState(root        , st       , live             )       {
+  const pick = (m                     ) => Object.fromEntries([...m].filter(([id]) => live.has(id)));
+  try {
+    mkdirSync(join(root, ".meshingly"), { recursive: true });
+    const tmp = `${stateFile(root)}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ attempts: pick(st.attempts), retryAt: pick(st.retryAt), ...(st.current ? { current: st.current } : {}) }));
+    renameSync(tmp, stateFile(root));
+  } catch {
+    /* losing the counters is better than stopping the watcher */
+  }
+}
+
+/** Looks at the queue once and runs at most one handoff. Returns whether it ran one. */
+async function pass(m           , o              , st       , root        )                   {
+  const { items, self } = await m.openHandoffs();
+  const now = Date.now();
+  const known = new Set(items.map((h) => h.id));
+  for (const h of items) {
+    if (o.signal.aborted) return false;
+    if (h.status !== "open") continue; // someone is on it (a live session of this project included)
+    if (h.needsPerson) continue; // a question for a human, not work for an agent
+    if (!o.fromPeers && h.fromSessionId !== self) continue;
+    if ((st.attempts.get(h.id) ?? 0) >= o.maxAttempts) continue;
+    if ((st.retryAt.get(h.id) ?? 0) > now) continue;
+    if (h.resetsAt) {
+      if (Date.parse(h.resetsAt) > now) continue; // the limit is not back yet
+    } else if (now - h.createdAt < o.settleMs) {
+      continue; // no reset time: the session that parked it may still be working
+    }
+
+    let prompt        ;
+    try {
+      prompt = await m.claim({ id: h.id });
+    } catch (err) {
+      if (err instanceof ToolError) {
+        o.log(`"${h.title}": ${err.message}`);
+        continue;
+      }
+      throw err;
+    }
+    const attempt = (st.attempts.get(h.id) ?? 0) + 1;
+    st.attempts.set(h.id, attempt);
+    st.current = h.id;
+    saveState(root, st, known);
+    o.log(`"${h.title}": claimed, starting the command (attempt ${attempt}/${o.maxAttempts})`);
+
+    const full = `${prompt}\n\nContinue this work in the current project directory. When it is finished, call meshingly_done with handoff id ${h.id}. If you are about to run out of usage again, call meshingly_handoff with the new state and stop.\n\n${questionPolicy(o.onQuestion)}`;
+    let code        ;
+    try {
+      code = await runCommand(o.command, full, root, { ...process.env, MESHINGLY_DIR: root }, o.maxRunMs, o.signal);
+    } catch (err) {
+      o.log(`"${h.title}": could not start the command: ${err instanceof Error ? err.message : String(err)}`);
+      code = 127;
+    }
+    st.current = undefined;
+
+    // The run may have parked its own continuation (usage ran out again, or it has a question). That new handoff
+    // replaces this one, and it inherits the attempt count and waits like a failure would: otherwise it would be
+    // picked up at once, with fresh counters, in an endless loop. (A handoff parked meanwhile by the project's own live
+    // session looks the same from here: it is only delayed, never lost.)
+    const after = await m.openHandoffs();
+    const parked = after.items.filter((n) => !known.has(n.id) && n.fromSessionId === self && n.status === "open");
+    const wait = o.backoffMs * attempt;
+    for (const n of parked) {
+      st.attempts.set(n.id, attempt);
+      st.retryAt.set(n.id, Date.now() + wait);
+      o.log(`"${n.title}": parked by the run; it will not be started before ${new Date(Date.now() + wait).toISOString()}`);
+    }
+    if (parked.length > 0) {
+      // Whatever the exit code, the continuation carries the work forward: handing the original back too would leave two copies.
+      await m.done({ id: h.id, summary: "continued in a new handoff" });
+      o.log(`"${h.title}": replaced by the handoff the run parked`);
+    } else if (code === 0) {
+      // The agent normally reports "done" itself; this makes it so when it did not (the call is idempotent).
+      await m.done({ id: h.id, summary: "finished by the watcher's run" });
+      o.log(`"${h.title}": finished`);
+    } else {
+      await m.release({ id: h.id });
+      st.retryAt.set(h.id, Date.now() + wait);
+      o.log(
+        attempt >= o.maxAttempts
+          ? `"${h.title}": failed (exit ${code}); giving up after ${attempt} attempts, it stays in the queue for a person or another session`
+          : `"${h.title}": failed (exit ${code}); back in the queue, next try in ${Math.round(wait / 60000)} min`,
+      );
+    }
+    saveState(root, st, new Set([...known, ...after.items.map((n) => n.id)]));
+    return true;
+  }
+  saveState(root, st, known);
+  return false;
+}
+
+export async function watch(m           , o              , root        )                {
+  // A watcher that was killed in the middle of a run left its claim behind: give it back instead of making everyone wait for the lease.
+  const stale = takeCurrentRun(root);
+  if (stale) {
+    try {
+      await m.release({ id: stale });
+      o.log(`gave back a handoff that a previous watcher was working on when it stopped`);
+    } catch (err) {
+      o.log(`could not give back an interrupted handoff: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const st = loadState(root);
+  while (!o.signal.aborted) {
+    try {
+      // Drain what is ready; a failed item waits for its retry time, so this cannot spin.
+      while (await pass(m, o, st, root)) {
+        /* next item */
+      }
+    } catch (err) {
+      o.log(`check failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (o.once) return;
+    await sleep(o.intervalMs, o.signal);
+  }
+}
+
+/** Entry point for `meshingly-mcp watch ...`. Returns the process exit code. */
+export async function runWatch(argv          )                  {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        cmd: { type: "string" },
+        interval: { type: "string" },
+        once: { type: "boolean", default: false },
+        "from-peers": { type: "boolean" },
+        "on-question": { type: "string" },
+        "max-attempts": { type: "string" },
+        "settle-minutes": { type: "string" },
+        dir: { type: "string" },
+        help: { type: "boolean", default: false },
+      },
+    }));
+  } catch (err) {
+    console.error(`${err instanceof Error ? err.message : String(err)}\n\n${HELP}`);
+    return 2;
+  }
+  if (values.help) {
+    console.log(HELP);
+    return 0;
+  }
+  const root = values.dir ?? process.env.MESHINGLY_DIR ?? process.cwd();
+  // A flag wins; otherwise the setting (which an environment variable in the MCP configuration overrides).
+  const saved = resolveSettings(root);
+  const interval = values.interval === undefined ? saved.values.checkIntervalSeconds : Number(values.interval);
+  const maxAttempts = values["max-attempts"] === undefined ? saved.values.maxAttempts : Number(values["max-attempts"]);
+  const settleMinutes = values["settle-minutes"] === undefined ? saved.values.settleMinutes : Number(values["settle-minutes"]);
+  const onQuestion = values["on-question"] ?? saved.values.onQuestion;
+  const command = values.cmd ?? saved.values.resumeCommand;
+  const fromPeers = values["from-peers"] ?? saved.values.trustPeers;
+  if (
+    !(interval >= 5) ||
+    !Number.isInteger(maxAttempts) ||
+    maxAttempts < 1 ||
+    !(settleMinutes >= 0) ||
+    (onQuestion !== "stop" && onQuestion !== "recommended")
+  ) {
+    console.error(`--interval must be at least 5 seconds, --max-attempts a whole number of 1 or more, --settle-minutes 0 or more and --on-question stop or recommended.\n\n${HELP}`);
+    return 2;
+  }
+  const m = new Meshingly(root);
+  const stamp = (line        ) => console.error(`${new Date().toISOString()} meshingly watch: ${line}`);
+
+  if (!m.connected()) {
+    console.error("Connect this project first (ask your AI session to set up Meshingly; if .meshingly/connection.json is damaged, delete it), then run the watcher again.");
+    return 1;
+  }
+  console.error(m.status());
+  if (saved.problem) stamp(`warning: ${saved.problem}`);
+  const abort = new AbortController();
+  process.once("SIGINT", () => abort.abort());
+  process.once("SIGTERM", () => abort.abort());
+
+  // Proof of life for meshingly_watch_status and stop: a pid alone could be a stranger's after a reboot.
+  let beat                            ;
+  if (!values.once) {
+    writeBeat(root);
+    beat = setInterval(() => writeBeat(root), BEAT_MS);
+    beat.unref();
+  }
+  stamp(`watching the queue every ${interval}s with "${command}"${fromPeers ? " (also handoffs from peers)" : " (own handoffs only)"}, on a question: ${onQuestion}`);
+  try {
+    await watch(
+      m,
+      {
+        command,
+        intervalMs: interval * 1000,
+        once: values.once === true,
+        fromPeers,
+        onQuestion,
+        maxAttempts,
+        settleMs: settleMinutes * 60_000,
+        maxRunMs: LEASE_MS - 10 * 60_000,
+        backoffMs: 30 * 60_000,
+        signal: abort.signal,
+        log: stamp,
+      },
+      root,
+    );
+  } finally {
+    if (beat) clearInterval(beat);
+    if (!values.once) clearBeat(root);
+  }
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meshingly-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "End-to-end encrypted relay that lets AI coding sessions on different machines message each other.",
   "mcpName": "com.meshingly/meshingly",
   "type": "module",