replica-bridge 0.3.12 → 0.3.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replica-bridge",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
   "type": "module",
   "bin": {

package/src/bridge/board.js

@@ -1,13 +1,18 @@
 // The optional 任务 board (PROTOCOL.md "看板"): reads AgensWork's agens-backend, which only listens on this computer, for
 // a phone that asked. The bridge does not start the backend or care how it started: it knows a port, and a computer
-// where nothing answers there simply has no board. Reads are a short allowlist, and the only background traffic is one
-// poll of /v1/changes while a phone is subscribed, because reading the lists counts as the user having seen them.
-                                                              
+// where nothing answers there simply has no board. Reads and writes are short allowlists, and the only background traffic
+// is the change log (/v1/changes, or its push stream /v1/changes/stream where the backend has one) while a phone is
+// subscribed, because reading the lists counts as the user having seen them. Each subscriber has its own place in the
+// log, so a phone that comes back says where it was and gets only what changed since (0.3.14).
+// The bridge stays thin: it checks the shape of a write and leaves what it means to the backend, whose status and body
+// (REC_NOT_FOUND, REC_STATE_CONFLICT, …) go back to the phone unchanged.
+                                                                           
+import { PACKAGE_VERSION } from "./install.js";
 
 /** agens-backend's default port, which its own AGENS_BACKEND_PORT changes. */
 export const DEFAULT_BOARD_PORT = 4753;
-/** agens-backend's own page polls every 10 s. */
-const DEFAULT_POLL_SECONDS = 10;
+/** How often the log is read when the backend cannot push it; one indexed query on this computer. */
+const DEFAULT_POLL_SECONDS = 1;
 /** Past this the backend is treated as gone, so a hung one cannot hold a phone waiting. */
 const READ_TIMEOUT_MS = 5000;
 /** Well under RELAY_REPLY_LIMIT, since the bridge sends board answers in one frame. */
@@ -15,19 +20,64 @@ const BODY_MAX_BYTES = 8 * 1024 * 1024;
 const CHANGES_PAGE = 100;
 /** Stops a catch-up on a change log that never ends; the backend keeps 30 days of it. */
 const CATCH_UP_PAGES = 1000;
+/** More changed tasks than this in one event, and the phone reads the whole board instead. */
+export const CHANGED_ITEMS_MAX = 200;
+/** What this bridge can do beyond reading, for board/state (PROTOCOL.md "看板"). */
+export const BOARD_CAPS = ["post", "delta"]         ;
 
-/** Read-only, and none of them does work on the backend. Not /session, /share, /actions, /assist, /mcp or /search. */
-const READS = [/^\/v1\/status$/, /^\/v1\/today$/, /^\/v1\/recommendations$/, /^\/v1\/recommendations\/[A-Za-z0-9_.:-]+$/];
+/** The backend's own cap on a request body (agens-backend src/http.mjs BODY_MAX). */
+export const POST_BODY_MAX_BYTES = 16 * 1024;
+const REC = "[A-Za-z0-9_.:-]+";
 
-/** The path and query to read, or null when it is not on the allowlist. */
-export function allowedBoardPath(path         )                {
+/**
+ * GETs (#367). /session also writes TASK.md in the task's working folder, which is what 开工 asks for; /share and /me
+ * only read. Not /assist, /mcp, /search, /changes (the bridge's own poll) or anything under /ui.
+ */
+const READS = [/^\/v1\/status$/, /^\/v1\/today$/, /^\/v1\/recommendations$/, new RegExp(`^/v1/recommendations/${REC}$`),
+  new RegExp(`^/v1/recommendations/${REC}/(share|session)$`), /^\/v1\/me$/];
+
+/** POSTs (#367): a task's follow-up actions, cancelling its preparation note, and muting a conversation. Nothing else. */
+const WRITES = [new RegExp(`^/v1/recommendations/${REC}/actions$`), new RegExp(`^/v1/recommendations/${REC}/prep/cancel$`), /^\/v1\/me\/muted$/];
+/** agens-backend src/recs.mjs ACTIONS. */
+export const BOARD_ACTIONS = ["accept", "snooze", "delegate", "dismiss", "done", "reopen"]         ;
+
+function localTarget(path         )             {
   if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//") || path.includes("\\")) return null;
   let target     ;
   try { target = new URL(path, "http://board.invalid"); } catch { return null; }
-  if (target.origin !== "http://board.invalid" || !READS.some((read) => read.test(target.pathname))) return null;
+  return target.origin === "http://board.invalid" ? target : null;
+}
+
+/** The path and query to read, or null when it is not on the allowlist. */
+export function allowedBoardPath(path         )                {
+  const target = localTarget(path);
+  if (!target || !READS.some((read) => read.test(target.pathname))) return null;
   return target.pathname + target.search;
 }
 
+/**
+ * The path and body to POST, or why not. The path is one of WRITES with no query; the body is JSON text of an object
+ * within the backend's size cap (absent or empty means `{}`, for prep/cancel), and on /actions names a known action.
+ */
+export function allowedBoardPost(path         , body         )                                                                                       {
+  const target = localTarget(path);
+  if (!target || target.search || !WRITES.some((write) => write.test(target.pathname))) return { error: "not_allowed" };
+  if (body === undefined || body === "") body = "{}";
+  if (typeof body !== "string") return { error: "bad_body" };
+  if (Buffer.byteLength(body, "utf8") > POST_BODY_MAX_BYTES) return { error: "too_large" };
+  let value         ;
+  try { value = JSON.parse(body); } catch { return { error: "bad_body" }; }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { error: "bad_body" };
+  if (target.pathname.endsWith("/actions")) {
+    const action = (value                        ).action;
+    if (typeof action !== "string" || !(BOARD_ACTIONS                     ).includes(action)) return { error: "not_allowed" };
+  }
+  const sent = JSON.stringify(value);
+  // Rewriting can lengthen it (1e5 becomes 100000), and the backend counts what it receives.
+  if (Buffer.byteLength(sent, "utf8") > POST_BODY_MAX_BYTES) return { error: "too_large" };
+  return { path: target.pathname, body: sent };
+}
+
 /** The port from AGENS_BACKEND_PORT, the backend's own setting, when it names a real one. */
 export function boardPortFrom(env                    = process.env)         {
   const port = Number(env.AGENS_BACKEND_PORT);
@@ -39,33 +89,79 @@ export function boardPortFrom(env                    = process.env)         {
                        
  
 
+                                            
+
+/** One subscriber and how far through the change log it has been told. */
+               
+                     
+                                                                                                           
+                        
+                                                                         
+                        
+                     
+ 
+
+/** Changes as a phone gets them: one per task, the latest, or a reset when there are too many. */
+function changedEvent(items               )             {
+  const latest = new Map                     ();
+  for (const item of items) { latest.delete(item.recId); latest.set(item.recId, item); }
+  return latest.size > CHANGED_ITEMS_MAX ? { t: "board/changed", reset: true } : { t: "board/changed", items: [...latest.values()] };
+}
+
+function changeOf(value         )                     {
+  const item = value                                                             ;
+  if (!item || !Number.isSafeInteger(item.seq) || typeof item.recId !== "string" || typeof item.kind !== "string") return null;
+  return { seq: item.seq          , recId: item.recId, kind: item.kind };
+}
+
 export class BoardReader {
                    port        ;
                    pollMs        ;
-                   listeners = new Set                             ();
+                   subs = new Set     ();
           timer                        = null;
           polling = false;
-  /** Where the change log was read to; null until a poll has found its end. */
-          after                = null;
+  /** Where the change log was read to; null until a read has found its end. Kept while the backend is away. */
+          end                = null;
           up                 = null;
-  /** Bumped when polling stops, so a poll still on its way does not speak for the next round. */
+  /** Bumped when polling stops, so a read still on its way does not speak for the next round. */
           round = 0;
+  /** The backend's push stream: open, unknown (try it), or not there (an older backend answers 404). */
+          stream                         = null;
+          streamSupported                 = null;
 
   constructor(options               = {}) {
     this.port = options.port ?? boardPortFrom();
     this.pollMs = (options.pollSeconds ?? DEFAULT_POLL_SECONDS) * 1000;
   }
 
+  /** How many phones are subscribed. */
+  get listeners()                   { return this.subs; }
+  /** Whether the backend is pushing changes now, rather than being polled. */
+  get streaming()          { return this.stream !== null; }
+
   /** The fetch adds the Host header the backend insists on (127.0.0.1:<port>) and no Origin, as a local caller. */
-          fetch(pathAndQuery        )                    {
-    return fetch(`http://127.0.0.1:${this.port}${pathAndQuery}`, { redirect: "error", signal: AbortSignal.timeout(READ_TIMEOUT_MS) });
+          fetch(pathAndQuery        , post         , signal              = AbortSignal.timeout(READ_TIMEOUT_MS))                    {
+    return fetch(`http://127.0.0.1:${this.port}${pathAndQuery}`, {
+      redirect: "error", signal,
+      ...(post === undefined ? {} : { method: "POST", headers: { "content-type": "application/json" }, body: post }),
+    });
   }
 
-  async read(path         )                       {
+  read(path         )                       {
     const allowed = allowedBoardPath(path);
-    if (!allowed) return { error: "not_allowed" };
+    return allowed ? this.answer(allowed) : Promise.resolve({ error: "not_allowed" });
+  }
+
+  /** Sent once and never retried: a write that timed out may still have happened, so the phone reads the task again. */
+  post(path         , body         )                       {
+    const allowed = allowedBoardPost(path, body);
+    return "error" in allowed ? Promise.resolve(allowed) : this.answer(allowed.path, allowed.body);
+  }
+
+  /** The backend's status and body as they are, errors included. */
+          async answer(pathAndQuery        , post         )                       {
     try {
-      const response = await this.fetch(allowed);
+      const response = await this.fetch(pathAndQuery, post);
       const body = await response.text();
       if (Buffer.byteLength(body, "utf8") > BODY_MAX_BYTES) return { error: "too_large" };
       return { status: response.status, body };
@@ -74,72 +170,188 @@ export class BoardReader {
     }
   }
 
-  /** Tells `listener` about the board until the returned function is called. Polls only while someone listens. */
-  subscribe(listener                             )             {
-    this.listeners.add(listener);
-    if (this.up !== null) listener({ t: "board/state", up: this.up });
+  /**
+   * Tells `listener` about the board until the returned function is called. Its first board/state carries `seq`, the
+   * point in the change log it starts from; with `after` (where the phone was) it then gets what changed since, else it
+   * reads the whole board. The log is read only while someone listens.
+   */
+  subscribe(listener          , after         )             {
+    const sub      = { listener, wanted: Number.isSafeInteger(after) && after  >= 0 ? after  : null, cursor: null, admitting: false };
+    this.subs.add(sub);
+    if (this.up === false) listener(this.state(false, null));
     if (!this.timer) {
       this.timer = setInterval(() => void this.poll(), this.pollMs);
       this.timer.unref();
       void this.poll();
-    }
+    } else if (this.up && this.end !== null) void this.admit(sub);
     return () => {
-      this.listeners.delete(listener);
-      if (!this.listeners.size) this.stop();
+      this.subs.delete(sub);
+      if (!this.subs.size) this.stop();
     };
   }
 
   stop() {
-    this.listeners.clear();
+    this.subs.clear();
     if (this.timer) clearInterval(this.timer);
     this.timer = null;
-    this.after = null;
+    this.stream?.abort();
+    this.stream = null;
+    this.streamSupported = null;
+    this.end = null;
     this.up = null;
     this.polling = false;
     this.round++;
   }
 
-          emit(event            ) {
-    for (const listener of this.listeners) listener(event);
+          state(up         , seq               )             {
+    return up && seq !== null ? { t: "board/state", up, seq, caps: [...BOARD_CAPS], bridge: PACKAGE_VERSION } : { t: "board/state", up };
   }
 
-          async changes(after        )                                              {
+          async changes(after        )                                                  {
     const response = await this.fetch(`/v1/changes?after=${after}&limit=${CHANGES_PAGE}`);
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
     const page = await response.json()                                       ;
     if (!Array.isArray(page.items)) throw new Error("not a page of changes");
-    return { items: page.items, next: typeof page.next === "number" ? page.next : after };
+    const items = page.items.map(changeOf).filter((item)                      => item !== null);
+    return { items, next: typeof page.next === "number" ? page.next : after };
+  }
+
+  /** Brings a new subscriber to the end of the log: its board/state, then what it missed, or a reset. */
+          async admit(sub     ) {
+    if (sub.admitting || sub.cursor !== null || this.end === null) return;
+    sub.admitting = true;
+    const round = this.round;
+    const missed                = [];
+    let reset = false, cursor = sub.wanted;
+    try {
+      if (cursor !== null && cursor > this.end) { reset = true; cursor = this.end; } // a log that went backwards: another backend, or a new database
+      // Read until this subscriber is at least where the shared reader is, so nothing falls between the two.
+      for (let page = 0; !reset && cursor !== null && cursor < this.end  && page < CATCH_UP_PAGES; page++) {
+        const { items, next } = await this.changes(cursor);
+        if (round !== this.round || !this.subs.has(sub)) return;
+        // The log keeps 30 days: a first change past the next number means some were deleted unseen.
+        if (page === 0 && items.length && items[0].seq > cursor + 1) reset = true;
+        missed.push(...items);
+        if (missed.length > CHANGED_ITEMS_MAX * 4) reset = true;
+        if (next === cursor && items.length === 0) break;
+        cursor = next;
+      }
+    } catch {
+      sub.admitting = false; // the next read of the log tries again
+      return;
+    }
+    if (round !== this.round || !this.subs.has(sub)) return;
+    sub.admitting = false;
+    sub.cursor = Math.max(cursor ?? this.end , this.end );
+    sub.listener(this.state(true, sub.cursor));
+    if (reset) sub.listener({ t: "board/changed", reset: true });
+    else if (missed.length) sub.listener(changedEvent(missed));
+  }
+
+  /** New changes up to `end`: each subscriber gets those past its own place. */
+          deliver(items               , end        ) {
+    for (const sub of this.subs) {
+      if (sub.cursor === null) continue;
+      const fresh = items.filter((item) => item.seq > sub.cursor );
+      sub.cursor = Math.max(sub.cursor, end);
+      if (fresh.length) sub.listener(changedEvent(fresh));
+    }
+  }
+
+          setUp(up         ) {
+    if (up === this.up) return;
+    this.up = up;
+    for (const sub of this.subs) {
+      if (!up) sub.listener(this.state(false, null));
+      else if (sub.cursor !== null) sub.listener(this.state(true, sub.cursor));
+    }
   }
 
           async poll() {
-    if (this.polling) return;
+    if (this.polling || this.stream) return;
     this.polling = true;
     const round = this.round;
-    let changed = false, up = true, after = this.after;
+    let items                = [], up = true, end = this.end;
     try {
-      // The first poll only finds the end of the log: what happened before someone was listening is not news.
-      if (after === null) {
-        after = 0;
+      // The first read only finds the end of the log: what happened before someone was listening is not news.
+      if (end === null) {
+        end = 0;
         for (let page = 0; page < CATCH_UP_PAGES; page++) {
-          const { items, next } = await this.changes(after);
-          after = next;
-          if (items.length < CHANGES_PAGE) break;
+          const { items: found, next } = await this.changes(end);
+          end = next;
+          if (found.length < CHANGES_PAGE) break;
         }
       } else {
-        const { items, next } = await this.changes(after);
-        after = next;
-        changed = items.length > 0;
+        const page = await this.changes(end);
+        items = page.items;
+        end = page.next;
       }
     } catch {
       up = false;
     }
     if (round !== this.round) return;
     this.polling = false;
-    if (up) this.after = after;
-    if (up !== this.up) {
-      this.up = up;
-      this.emit({ t: "board/state", up });
+    if (up) this.end = end;
+    this.setUp(up);
+    if (!up) return;
+    if (items.length) this.deliver(items, end );
+    for (const sub of this.subs) if (sub.cursor === null) void this.admit(sub);
+    if (this.streamSupported !== false) void this.openStream(round);
+  }
+
+  /**
+   * Listens to the backend's push stream from where the log was read to. A backend without one answers 404 (or not as
+   * an event stream), and the bridge keeps polling; a stream that ends hands back to polling, which reopens it.
+   */
+          async openStream(round        ) {
+    if (this.stream || this.end === null) return;
+    const controller = new AbortController();
+    this.stream = controller;
+    let response          ;
+    try {
+      response = await this.fetch(`/v1/changes/stream?after=${this.end}`, undefined, controller.signal);
+    } catch {
+      if (this.stream === controller) this.stream = null;
+      return;
     }
-    if (changed) this.emit({ t: "board/changed" });
+    if (round !== this.round || this.stream !== controller) { controller.abort(); return; }
+    if (!response.ok || !(response.headers.get("content-type") ?? "").startsWith("text/event-stream") || !response.body) {
+      this.streamSupported = false;
+      this.stream = null;
+      controller.abort();
+      return;
+    }
+    this.streamSupported = true;
+    let buffer = "", pending                = [], flush                        = null;
+    const send = () => {
+      flush = null;
+      if (round !== this.round || this.stream !== controller) return;
+      const batch = pending;
+      pending = [];
+      const end = Math.max(this.end ?? 0, ...batch.map((item) => item.seq));
+      this.end = end;
+      this.deliver(batch, end);
+    };
+    try {
+      const decoder = new TextDecoder();
+      for await (const chunk of response.body                                        ) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let split        ;
+        while ((split = buffer.search(/\r?\n\r?\n/)) >= 0) {
+          const event = buffer.slice(0, split);
+          buffer = buffer.slice(split).replace(/^\r?\n\r?\n/, "");
+          const data = event.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+          if (!data) continue; // a heartbeat
+          let item                     = null;
+          try { item = changeOf(JSON.parse(data)); } catch { /* not a change */ }
+          if (!item || item.seq <= (this.end ?? 0)) continue;
+          pending.push(item);
+          // Changes that land together (a maintenance round) go to the phone as one event.
+          flush ??= setTimeout(send, 20);
+        }
+      }
+    } catch { /* aborted, or the backend went away */ }
+    if (flush) { clearTimeout(flush); send(); }
+    if (this.stream === controller) this.stream = null;
   }
 }

package/src/bridge/service.js

@@ -269,8 +269,10 @@ export class BridgeService {
     } else if (message.t === "board/get") {
       // Not awaited: a slow backend should not hold up the frames behind this one.
       void this.board.read(message.path).then((answer) => this.sendInner(conn, { t: "board/res", id: message.id, ...answer }));
+    } else if (message.t === "board/post") {
+      void this.board.post(message.path, message.body).then((answer) => this.sendInner(conn, { t: "board/res", id: message.id, ...answer }));
     } else if (message.t === "board/sub") {
-      conn.boardUnsubscribe ??= this.board.subscribe((event) => this.sendInner(conn, event));
+      conn.boardUnsubscribe ??= this.board.subscribe((event) => this.sendInner(conn, event), message.after);
     } else if (message.t === "board/unsub") {
       conn.boardUnsubscribe?.();
       conn.boardUnsubscribe = null;

package/src/protocol.js

@@ -239,14 +239,23 @@ export class FrameCipher {
                              
                                    
                                                 
+                                                                
                                                   
-                      
+                                      
                         
                
 
-/** A read of the optional board: the backend's status and body, or why there is none (PROTOCOL.md "看板"). */
-                                                                                                                 
-                                                                                    
+/** A read or write of the optional board: the backend's status and body, or why there is none (PROTOCOL.md "看板"). */
+                                                                                                                              
+/** One task that changed, from agens-backend's change log (0.3.14). */
+                                                                       
+/**
+ * What a subscriber hears. From 0.3.14 a board/state that says up also gives `seq` (where in the change log the phone
+ * starts), `caps` and the bridge's version, and board/changed names the tasks, or says `reset` when there are too many.
+ */
+                        
+                                                                                     
+                                                                
 
                                                                  
 /** One segment of a long line: `data` is base64 of bytes [segment * chunk size, …) of the payload, `size` its length. */