parawatch 0.2.1 → 0.3.2

package/dist/core/syncthing.js

@@ -0,0 +1,121 @@
+/**
+ * The Syncthing adapter: asks the local Syncthing (its REST API) how the shared folder is doing.
+ * The API key is read from Syncthing's own config.xml and never printed or stored by parawatch.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findConflicts, folderPeers } from "./sync.js";
+/** Where Syncthing keeps config.xml on this machine, newest layout first. */
+export function syncthingHomes() {
+    const home = os.homedir();
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+        return [path.join(local, "Syncthing")];
+    }
+    const state = process.env.XDG_STATE_HOME || path.join(home, ".local", "state");
+    const out = [path.join(state, "syncthing")];
+    if (process.platform === "darwin")
+        out.push(path.join(home, "Library", "Application Support", "Syncthing"));
+    out.push(path.join(process.env.XDG_CONFIG_HOME || path.join(home, ".config"), "syncthing"));
+    return out;
+}
+/** The GUI address and API key from config.xml (`home` overrides where to look). */
+export function readSyncthingGui(home) {
+    const dirs = home ? [home] : syncthingHomes();
+    for (const d of dirs) {
+        const file = path.join(d, "config.xml");
+        let xml;
+        try {
+            xml = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const gui = /<gui\b([^>]*)>([\s\S]*?)<\/gui>/.exec(xml);
+        const attrs = gui?.[1] ?? "";
+        const body = gui?.[2] ?? "";
+        const address = /<address>([^<]+)<\/address>/.exec(body)?.[1]?.trim() || "127.0.0.1:8384";
+        const tls = /\btls="true"/.test(attrs);
+        const apiKey = /<apikey>([^<]+)<\/apikey>/.exec(body)?.[1]?.trim();
+        const host = address.replace(/^0\.0\.0\.0(?=:)/, "127.0.0.1").replace(/^\[::\](?=:)/, "[::1]");
+        return { url: `${tls ? "https" : "http"}://${host}`, apiKey, configFile: file };
+    }
+    return { url: "http://127.0.0.1:8384" };
+}
+function inside(child, parent) {
+    const rel = path.relative(path.resolve(parent), path.resolve(child));
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+export const syncthingAdapter = {
+    name: "syncthing",
+    about: "Syncthing on this machine (its REST API on localhost)",
+    async status(ctx) {
+        const base = { adapter: "syncthing", dir: ctx.dir, device: ctx.device, ok: false, peers: folderPeers(ctx.dir, ctx.device), conflicts: findConflicts(ctx.dir) };
+        const gui = readSyncthingGui(typeof ctx.config.home === "string" ? ctx.config.home : undefined);
+        const url = typeof ctx.config.url === "string" ? ctx.config.url : gui.url;
+        const key = process.env.PARAWATCH_SYNCTHING_KEY || gui.apiKey;
+        if (!key)
+            return { ...base, error: "no Syncthing API key found (is Syncthing set up on this machine?)" };
+        const f = ctx.fetch ?? fetch;
+        const timeout = ctx.timeoutMs ?? 2000;
+        const get = async (p) => {
+            const res = await f(`${url}${p}`, { headers: { "X-API-Key": key }, signal: AbortSignal.timeout(timeout) });
+            if (!res.ok)
+                throw new Error(`Syncthing answered ${res.status} for ${p.split("?")[0]}`);
+            return (await res.json());
+        };
+        let folders;
+        try {
+            folders = await get("/rest/config/folders");
+        }
+        catch (err) {
+            const msg = err.message;
+            return { ...base, error: /fetch failed|ECONNREFUSED|abort|timeout/i.test(msg) ? `Syncthing is not running at ${url}` : msg };
+        }
+        const folder = folders
+            .map((x) => ({ ...x, path: x.path.replace(/^~(?=[\\/]|$)/, os.homedir()) }))
+            .filter((x) => inside(ctx.dir, x.path))
+            .sort((a, b) => b.path.length - a.path.length)[0];
+        if (!folder)
+            return { ...base, ok: true, error: `no Syncthing folder holds ${ctx.dir}` };
+        const [sys, devices, conns, stats, db, fstats] = await Promise.all([
+            get("/rest/system/status"),
+            get("/rest/config/devices"),
+            get("/rest/system/connections"),
+            get("/rest/stats/device"),
+            get(`/rest/db/status?folder=${encodeURIComponent(folder.id)}`),
+            get("/rest/stats/folder"),
+        ]);
+        const names = new Map(devices.map((d) => [d.deviceID, d.name || d.deviceID.slice(0, 7)]));
+        const known = new Map(base.peers.map((p) => [p.name, p]));
+        const peers = [];
+        for (const d of folder.devices ?? []) {
+            if (d.deviceID === sys.myID)
+                continue;
+            const c = conns.connections[d.deviceID];
+            const seen = stats[d.deviceID]?.lastSeen;
+            const name = names.get(d.deviceID) ?? d.deviceID.slice(0, 7);
+            const fromFolder = known.get(name);
+            peers.push({
+                name,
+                connected: !!c?.connected,
+                lastSeen: c?.connected ? new Date().toISOString() : seen && !seen.startsWith("1970") ? seen : fromFolder?.lastSeen,
+                address: c?.connected ? c.address : undefined,
+                version: fromFolder?.version,
+            });
+        }
+        const idle = db.state === "idle" && !db.needFiles;
+        const pending = db.needFiles ?? 0;
+        const errors = (db.errors ?? 0) + (db.pullErrors ?? 0);
+        return {
+            ...base,
+            ok: true,
+            peers,
+            pending: pending || undefined,
+            lastSync: idle ? db.stateChanged : fstats[folder.id]?.lastFile?.at,
+            error: errors ? `${errors} file(s) could not be synced (see Syncthing)` : !peers.length ? `folder "${folder.label || folder.id}" is not shared with another device yet` : undefined,
+        };
+    },
+};
+//# sourceMappingURL=syncthing.js.map

package/dist/core/types.js

@@ -1,4 +1,11 @@
+/** The version of the JSON that commands print (`--json`) and panels read. */
 export const SCHEMA_VERSION = 1;
+/**
+ * The newest event-log format this copy reads and writes. 1: one machine. 2: per-device logs in a
+ * shared folder (prefixed ids, answers that record what they saw). A copy refuses to write to a
+ * log with a newer format than it knows.
+ */
+export const STORE_FORMAT = 2;
 export const CARD_KINDS = ["decide", "try", "block", "todo"];
 export const PR_CHANGES = ["review", "approved", "changes_requested", "commented", "ci_failed", "ci_passed", "queued", "queue_removed", "conflict", "merged", "closed", "note"];
 /** Who counts as a human when deciding what wakes an agent. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parawatch",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "description": "A control tower for people running many AI coding agents in parallel: see what is running, what needs you, and wake the right agent when you answer.",
   "keywords": [
     "ai-agents",

package/skills/parawatch/SKILL.md

@@ -74,10 +74,12 @@ News from somewhere GitHub does not show (a merge bot, a ticket system) can be r
 
 ## 4. Waiting for the answer
 
-Right after opening cards or linking a pull request, keep exactly one wait armed for your project:
+Right after opening cards or linking a pull request, keep exactly one wait armed:
 
-- **Claude Code**: run `parawatch wait -p <project>` as a background Bash command (`run_in_background: true`). When the human answers, the command exits, its output is the answer, and you are woken. Do not poll, do not sleep-loop, do not start a second wait while one is running.
-- **Other runtimes**: check `parawatch inbox -p <project>` at the start of every turn.
+- **Claude Code**: run `parawatch wait` as a background Bash command (`run_in_background: true`). When the human answers, the command exits, its output is the answer, and you are woken. Do not poll, do not sleep-loop, do not start a second wait while one is running.
+- **Other runtimes**: check `parawatch inbox` at the start of every turn.
+
+Inside your session, `wait` and `inbox` read only what is yours: answers on cards you opened, news on pull requests linked to you, and cards or pull requests no session owns in the project you claimed. Other sessions in the same project are not woken by your news and cannot take it from you. `-p <project>` reads the whole project instead; leave it to a lead (section 8).
 
 Keep working on other things meanwhile. A wait with `--timeout <seconds>` exits with code 2 when nothing came; re-arm it if you still need the answer. While no wait runs, an answer is kept, and the card tells the human that no agent is waiting; it reaches you on your next turn or your next wait.
 
@@ -119,10 +121,15 @@ The session then shows as done, not as idle, and the line goes into the human's
 
 ## 8. Leads and workers
 
+- A lead that watches the whole project waits with `parawatch wait -p <project>`.
 - The lead owns the cards for its project. Workers (subagents, `codex exec` jobs, other sessions you start) report back to the lead instead of opening cards, unless the lead told them to ask the human directly.
 - Tell workers in their brief what to return to you, so the lead can turn it into one clear card.
 - Before ending a session, close cards you handled, end runs you started, and claim `--done`.
 
+## On more than one machine
+
+When `parawatch sync` shows other machines, the human may answer from any of them. Nothing changes in how you ask or wait. Ids then carry the machine (`pc-c3`); use the id the command printed. Attach files under your home folder or the shared folder (or a folder named with `parawatch sync root`), so the human's machine can open them. An app path given to `try --open` only opens on the machine that has it, so say in the body which machine to try it on.
+
 ## Quick reference
 
 ```