parawatch 0.3.15 → 0.3.17

package/dist/core/store.js

@@ -2,7 +2,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { UserError } from "./errors.js";
+import { mergeLogs, parseEventLines, stampFor } from "./log.js";
 import { STORE_FORMAT } from "./types.js";
+export { mergeLogs, parseEventLines };
 /** Directory holding all parawatch state for this user on this machine. */
 export function homeDir() {
     const explicit = process.env.PARAWATCH_HOME;
@@ -188,48 +190,6 @@ export function readEvents() {
         return lists[0] ?? [];
     return mergeLogs(lists);
 }
-/** Merge per-device logs, each already in its own order, into one. */
-export function mergeLogs(lists) {
-    const at = lists.map(() => 0);
-    const out = [];
-    for (;;) {
-        let pick = -1;
-        for (let i = 0; i < lists.length; i++) {
-            const ev = lists[i][at[i]];
-            if (!ev)
-                continue;
-            if (pick < 0) {
-                pick = i;
-                continue;
-            }
-            const best = lists[pick][at[pick]];
-            if (ev.ts < best.ts || (ev.ts === best.ts && (ev.dev ?? "") < (best.dev ?? "")))
-                pick = i;
-        }
-        if (pick < 0)
-            return out;
-        out.push(lists[pick][at[pick]++]);
-    }
-}
-export function parseEventLines(text, device) {
-    const out = [];
-    for (const line of text.split("\n")) {
-        if (!line.trim())
-            continue;
-        try {
-            const ev = JSON.parse(line);
-            if (typeof ev.seq !== "number" || typeof ev.type !== "string")
-                continue;
-            if (device)
-                ev.dev = device;
-            out.push(ev);
-        }
-        catch {
-            // a torn or hand-edited line; keep going
-        }
-    }
-    return out;
-}
 // ------------------------------------------------------------------ writing
 /** Append one event. `build` sees the current events so it can pick ids under the lock. */
 export function appendEvent(build) {
@@ -263,9 +223,13 @@ export function appendLocked(build) {
     for (const e of own)
         if (e.seq > seq)
             seq = e.seq;
-    const ts = new Date().toISOString();
+    const mine = new Set(own);
+    let last = 0;
     const v = writeFormat();
-    const out = build(events).map((body) => ({ v, seq: ++seq, ts, ...body }));
+    const out = build(events).map((body) => {
+        last = stampFor(events, (e) => mine.has(e), body.card, Math.max(Date.now(), last));
+        return { v, seq: ++seq, ts: new Date(last).toISOString(), ...body };
+    });
     if (out.length) {
         ensureDir(path.dirname(eventsPath()));
         fs.appendFileSync(eventsPath(), out.map((e) => JSON.stringify(e) + "\n").join(""));

package/dist/core/sync.js

@@ -15,6 +15,7 @@ import path from "node:path";
 import { UserError } from "./errors.js";
 import { DEVICE_NAME, configPath, deviceName, eventFiles, expandHome, homeDir, parseEventLines, readConfig, sharedDir, withLock, writeConfig, } from "./store.js";
 import { syncthingAdapter } from "./syncthing.js";
+import { relayAdapter } from "./relay.js";
 function devicesDir(shared) {
     return path.join(shared, "devices");
 }
@@ -209,6 +210,7 @@ function adapters() {
     registry ??= new Map([
         [folderAdapter.name, folderAdapter],
         [syncthingAdapter.name, syncthingAdapter],
+        [relayAdapter.name, relayAdapter],
     ]);
     return registry;
 }

package/dist/relay/server.js

@@ -0,0 +1,234 @@
+/**
+ * The relay: a small server that carries the shared folder between machines in place of a sync
+ * tool. It keeps sealed files and hands out what changed. It never sees what is in them: every
+ * machine seals a file and its path with a key the server is never given (see core/relay.ts).
+ *
+ * A space is the folder of one person (or one group). Each space has a token; anyone with it can
+ * read and write the space's sealed files. Making a space needs the server's invite, so a public
+ * server is not open to everyone.
+ *
+ *   POST   /v1/spaces                       invite → { space, token }
+ *   GET    /v1/spaces/:space/changes?after=N&wait=S   { head, changes: [{ name, seq, size?, deleted? }] }
+ *   PUT    /v1/spaces/:space/files/:name    the sealed bytes → { seq }
+ *   GET    /v1/spaces/:space/files/:name    the sealed bytes
+ *   DELETE /v1/spaces/:space/files/:name    → { seq }
+ *   GET    /healthz
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+export const RELAY_MAX_FILE = 256 * 1024 * 1024;
+const MAX_WAIT_S = 30;
+const SPACE = /^[a-f0-9]{24}$/;
+const NAME = /^[a-f0-9]{40}$/;
+const sha = (s) => crypto.createHash("sha256").update(s).digest();
+function sameSecret(given, hash) {
+    if (!given)
+        return false;
+    return crypto.timingSafeEqual(sha(given), hash);
+}
+class Store {
+    root;
+    spaces = new Map();
+    constructor(root) {
+        this.root = root;
+        fs.mkdirSync(root, { recursive: true });
+    }
+    create() {
+        const id = crypto.randomBytes(12).toString("hex");
+        const token = crypto.randomBytes(32).toString("base64url");
+        const dir = path.join(this.root, id);
+        fs.mkdirSync(path.join(dir, "files"), { recursive: true });
+        fs.writeFileSync(path.join(dir, "space.json"), JSON.stringify({ v: 1, token: sha(token).toString("hex"), at: new Date().toISOString() }) + "\n");
+        return { space: id, token };
+    }
+    open(id) {
+        if (!SPACE.test(id))
+            return undefined;
+        const had = this.spaces.get(id);
+        if (had)
+            return had;
+        const dir = path.join(this.root, id);
+        let meta;
+        try {
+            meta = JSON.parse(fs.readFileSync(path.join(dir, "space.json"), "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+        const s = { id, dir, tokenHash: Buffer.from(meta.token, "hex"), head: 0, files: new Map(), journalLines: 0, waiters: new Set() };
+        let text = "";
+        try {
+            text = fs.readFileSync(path.join(dir, "journal.jsonl"), "utf8");
+        }
+        catch {
+            // a new space
+        }
+        for (const line of text.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const e = JSON.parse(line);
+                if (!NAME.test(e.name) || !Number.isInteger(e.seq))
+                    continue;
+                s.files.set(e.name, e.deleted ? { seq: e.seq, deleted: true } : { seq: e.seq, size: e.size });
+                s.head = Math.max(s.head, e.seq);
+                s.journalLines++;
+            }
+            catch {
+                // a line cut short by a crash; the file it named is written again by its machine
+            }
+        }
+        this.spaces.set(id, s);
+        if (s.journalLines > 4 * s.files.size + 100)
+            this.compact(s);
+        return s;
+    }
+    compact(s) {
+        const lines = [...s.files].sort((a, b) => a[1].seq - b[1].seq).map(([name, e]) => JSON.stringify({ name, ...e }) + "\n");
+        const tmp = path.join(s.dir, "journal.jsonl.tmp");
+        fs.writeFileSync(tmp, lines.join(""));
+        fs.renameSync(tmp, path.join(s.dir, "journal.jsonl"));
+        s.journalLines = lines.length;
+    }
+    record(s, name, e) {
+        const seq = ++s.head;
+        const entry = { seq, ...e };
+        s.files.set(name, entry);
+        fs.appendFileSync(path.join(s.dir, "journal.jsonl"), JSON.stringify({ name, ...entry }) + "\n");
+        s.journalLines++;
+        if (s.journalLines > 4 * s.files.size + 100)
+            this.compact(s);
+        for (const w of [...s.waiters])
+            w();
+        return seq;
+    }
+    filePath(s, name) {
+        return path.join(s.dir, "files", name);
+    }
+    changes(s, after) {
+        const changes = [...s.files].filter(([, e]) => e.seq > after).map(([name, e]) => ({ name, ...e }));
+        return { head: s.head, changes: changes.sort((a, b) => a.seq - b.seq) };
+    }
+}
+function send(res, status, body) {
+    const text = body === undefined ? "" : JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(text);
+}
+function bearer(req) {
+    const h = req.headers.authorization;
+    return h?.startsWith("Bearer ") ? h.slice(7).trim() : undefined;
+}
+/** A relay server; call `.listen(port)` on it. */
+export function createRelayServer(opts) {
+    const store = new Store(opts.dataDir);
+    const log = opts.log ?? (() => { });
+    const inviteHash = opts.invite ? sha(opts.invite) : undefined;
+    return http.createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://relay");
+        const parts = url.pathname.split("/").filter(Boolean);
+        const fail = (status, error) => send(res, status, { error });
+        try {
+            if (req.method === "GET" && url.pathname === "/healthz")
+                return send(res, 200, { ok: true });
+            if (parts[0] !== "v1" || parts[1] !== "spaces")
+                return fail(404, "not found");
+            if (parts.length === 2 && req.method === "POST") {
+                if (!inviteHash || !sameSecret(bearer(req), inviteHash))
+                    return fail(403, "this server needs its invite to make a space");
+                const made = store.create();
+                log(`space ${made.space} made`);
+                return send(res, 201, made);
+            }
+            const s = parts[2] ? store.open(parts[2]) : undefined;
+            // an unknown space and a wrong token look the same from outside
+            if (!s || !sameSecret(bearer(req), s.tokenHash))
+                return fail(401, "unknown space or wrong token");
+            if (parts.length === 4 && parts[3] === "changes" && req.method === "GET") {
+                const after = Math.max(0, Number(url.searchParams.get("after") ?? 0) || 0);
+                const wait = Math.min(MAX_WAIT_S, Math.max(0, Number(url.searchParams.get("wait") ?? 0) || 0));
+                const now = store.changes(s, after);
+                if (now.changes.length || !wait)
+                    return send(res, 200, now);
+                // nothing new: hold the request until something changes or the wait runs out
+                let done = false;
+                const finish = () => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(timer);
+                    s.waiters.delete(finish);
+                    if (!res.writableEnded)
+                        send(res, 200, store.changes(s, after));
+                };
+                const timer = setTimeout(finish, wait * 1000);
+                s.waiters.add(finish);
+                req.on("close", () => {
+                    done = true;
+                    clearTimeout(timer);
+                    s.waiters.delete(finish);
+                });
+                return;
+            }
+            if (parts.length === 5 && parts[3] === "files") {
+                const name = parts[4];
+                if (!NAME.test(name))
+                    return fail(400, "bad file name");
+                const file = store.filePath(s, name);
+                if (req.method === "GET") {
+                    const e = s.files.get(name);
+                    if (!e || e.deleted)
+                        return fail(404, "no such file");
+                    res.writeHead(200, { "content-type": "application/octet-stream", "cache-control": "no-store", "x-seq": String(e.seq) });
+                    fs.createReadStream(file).on("error", () => res.destroy()).pipe(res);
+                    return;
+                }
+                if (req.method === "DELETE") {
+                    fs.rmSync(file, { force: true });
+                    return send(res, 200, { seq: store.record(s, name, { deleted: true }) });
+                }
+                if (req.method === "PUT") {
+                    const declared = Number(req.headers["content-length"] ?? NaN);
+                    if (Number.isFinite(declared) && declared > RELAY_MAX_FILE)
+                        return fail(413, "file too large");
+                    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+                    const out = fs.createWriteStream(tmp);
+                    let size = 0;
+                    let tooBig = false;
+                    req.on("data", (chunk) => {
+                        size += chunk.length;
+                        if (size > RELAY_MAX_FILE && !tooBig) {
+                            tooBig = true;
+                            out.destroy();
+                            fs.rmSync(tmp, { force: true });
+                            fail(413, "file too large");
+                            req.destroy();
+                        }
+                    });
+                    req.pipe(out);
+                    out.on("finish", () => {
+                        if (tooBig)
+                            return;
+                        fs.renameSync(tmp, file);
+                        send(res, 200, { seq: store.record(s, name, { size }) });
+                    });
+                    out.on("error", () => {
+                        fs.rmSync(tmp, { force: true });
+                        if (!res.headersSent)
+                            fail(500, "could not store the file");
+                    });
+                    return;
+                }
+            }
+            return fail(404, "not found");
+        }
+        catch (err) {
+            log(`error: ${err.message}`);
+            if (!res.headersSent)
+                fail(500, "server error");
+        }
+    });
+}
+//# sourceMappingURL=server.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parawatch",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "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",
@@ -39,7 +39,7 @@
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/bin/cli.ts",
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit && npm run typecheck -w @parawatch/panel -w @parawatch/desktop",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit && npm run typecheck -w @parawatch/panel -w @parawatch/desktop -w @parawatch/web",
     "prepublishOnly": "npm run build && npm test",
     "demo": "tsx scripts/demo.ts"
   },

package/skills/parawatch/SKILL.md

@@ -130,6 +130,7 @@ The session then shows as done, not as idle, and the line goes into the human's
 - The lead owns the cards for the work it hands out. 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.
 - A session the human started on their own asks the human directly. Its cards and pull requests are its own: answers and news on them go to it, not to the lead. When that work belongs in the lead's queue, the session tells the lead, not the other way round.
 - Tell workers in their brief what to return to you, so the lead can turn it into one clear card.
+- **A lead that finishes one task claims its next work, not `--done`** (`parawatch claim -p <project> -t <next> --role lead`). `--done` ends the session as lead too: from then on what no session owns in the project goes nowhere until a session claims the lead. When you do a worker's task yourself, its brief's rules for workers (such as "do not use parawatch") are not yours.
 - Before ending a session, close cards you handled, end runs you started, and claim `--done`.
 
 ## On more than one machine