dsh-builtin-browser 0.4.1 → 0.4.5

package/lib/browser-electron/bridge-connection.js

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 /**
  * Transport for the desktop shell's browser bridge: one long-lived connection to a
  * loopback TCP service.
@@ -18,53 +19,157 @@
  * @module dsh-browser/browser-electron/bridge-connection
  */
 import { connect } from 'node:net';
+/**
+ * Safety cap on one un-answered reply line. CDP answers from the sidebar (a screenshot's
+ * base64 is the big one) cross this socket, so the cap is generous; what it exists for is a
+ * peer that never sends a newline — `this.buffer += chunk` grew without bound, unlike the
+ * same buffer in remote-host.ts, which caps at 512 MiB.
+ */
+const MAX_BUFFER_BYTES = 128 * 1024 * 1024;
+/**
+ * Field this client adds to every request so the shell can echo it back and never relies on
+ * byte order to pair an answer with its request. Loosely named, and additive on purpose: a
+ * bridge that does not know it simply ignores it (the current shipped shell does), and the
+ * client then falls back to arrival order, which is what the protocol guaranteed before.
+ */
+const REQUEST_ID_FIELD = 'bridgeRequestId';
 /**
  * A reusable connection to the bridge.
  *
- * Requests are serialised by construction: one socket, one in-flight request at a
- * time, answered in order. A broken socket is discarded so the next call dials
- * again — a dead connection must never become a dead plugin.
+ * Requests may be in flight CONCURRENTLY, so answers are correlated by id rather than by
+ * position: `call()` stamps a unique {@link REQUEST_ID_FIELD} on the request and `onData()`
+ * resolves the entry that carries the echoed id. A bridge that does not echo it is still
+ * supported — its answer is handed to the oldest outstanding request, which is the
+ * arrival-order rule the protocol states. Once such an answer has been seen, the connection
+ * stops keeping two requests in flight (a second one re-dials), so position can never be the
+ * only thing distinguishing two callers' answers. An answer that matches nothing is never
+ * handed to whichever request happens to be first: the socket is dropped instead.
+ *
+ * A broken socket is discarded so the next call dials again — a dead connection must never
+ * become a dead plugin.
  */
 export class BridgeConnection {
     endpoint;
+    endpointPath;
     socket;
     buffer = '';
+    /** Outstanding requests by id. */
+    pending = new Map();
+    /** Ids of the requests sent on the current socket, oldest first. */
     queue = [];
+    nextId = 1;
+    /** True once any reply arrived without an id: this bridge does not echo request ids. */
+    idLessBridge = false;
+    /** True once this connection may only have one request in flight at a time. */
+    serialisable = false;
     /**
      * @param endpoint - the shell's published bridge endpoint.
+     * @param endpointPath - where that endpoint is republished, so a moved port can be followed.
      */
-    constructor(endpoint) {
+    constructor(endpoint, endpointPath) {
         this.endpoint = endpoint;
+        this.endpointPath = endpointPath;
+    }
+    /**
+     * Re-read the published endpoint, and adopt it if the shell has moved.
+     *
+     * The bridge binds an ephemeral port and picks a NEW one whenever its server is recreated. The
+     * endpoint file is rewritten every fifteen seconds, but a host that adopted the old one keeps
+     * dialling a dead port forever: measured here as `connect ECONNREFUSED 127.0.0.1:52276` while
+     * the live bridge sat on 52411. Discarding the socket is not enough — the comment below says a
+     * dead connection must never become a dead plugin, and a stale PORT makes exactly that happen.
+     *
+     * Cheap and safe: one small file read per call, no socket work.
+     *
+     * @returns true when a different endpoint was adopted.
+     */
+    refreshEndpoint() {
+        if (this.endpointPath === undefined)
+            return false;
+        try {
+            const raw = JSON.parse(readFileSync(this.endpointPath, 'utf8'));
+            if (typeof raw.port !== 'number' || typeof raw.token !== 'string')
+                return false;
+            if (raw.port === this.endpoint.port && raw.token === this.endpoint.token)
+                return false;
+            this.endpoint = {
+                port: raw.port,
+                token: raw.token,
+                pid: typeof raw.pid === 'number' ? raw.pid : this.endpoint.pid,
+            };
+            // The old socket belongs to the old port.
+            this.reset(new Error('dsh-builtin-browser: the bridge moved; reconnecting to the new port'));
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
     /**
      * Send one request, reusing the socket if it is still healthy.
-     * @param request - the request body (the token is added here).
+     *
+     * Requests may overlap: the request is written as soon as it is queued, so two concurrent
+     * callers have two requests in flight. Each carries a unique {@link REQUEST_ID_FIELD}, and
+     * `onData()` resolves the entry that carries the echoed id — which is what makes
+     * correlation independent of arrival order. A bridge that does not echo the field (the
+     * shipped shell today) still works by arrival order; see {@link onData}.
+     * @param request - the request body (the token and the request id are added here).
      * @param timeoutMs - how long to wait for the answer before dropping the socket.
      * @returns the bridge's answer.
      */
     async call(request, timeoutMs = 20_000) {
-        const socket = this.ensureSocket();
+        // One re-dial, and only for the case this exists for: a socket that has already carried
+        // an id-less answer cannot have a second request in flight, because two outstanding
+        // requests would be matched by position — the swap this correlation prevents. It is a
+        // straight-line re-dial rather than a retry loop: an earlier revision re-entered call()
+        // from inside its own promise executor, which left an orphaned pending entry behind and,
+        // when the condition could not clear, spun until the process ran out of heap.
+        // Follow the shell if its bridge moved to a new port (see refreshEndpoint).
+        this.refreshEndpoint();
+        let socket = this.ensureSocket();
+        if (this.serialisable && this.queue.length > 0) {
+            this.reset(new Error('dsh-builtin-browser: bridge connection reopened so replies stay attributable'));
+            socket = this.ensureSocket();
+        }
+        const id = this.nextId++;
         return await new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: answer => { clearTimeout(timer); resolve(answer); },
+                reject: error => { clearTimeout(timer); reject(error); },
+            });
+            this.queue.push(id);
             const timer = setTimeout(() => {
-                const index = this.queue.findIndex(entry => entry.resolve === resolve);
-                if (index !== -1)
-                    this.queue.splice(index, 1);
                 const error = new Error(`dsh-builtin-browser: bridge timed out after ${timeoutMs}ms`);
-                this.reset(error);
+                // An unanswered request desynchronises the stream for an id-less bridge, and leaves one
+                // outstanding for one that echoes ids — either way the next call should start on a
+                // fresh socket. Only when THIS request's socket is still the live one: tearing down the
+                // REPLACEMENT because an abandoned request timed out would break whatever is using it.
+                //
+                // This test used to read `this.pending.has(id) && this.socket === socket`, with
+                // `forget(id)` on the line above it — and forget() is what removes the entry that `has`
+                // was looking for, so the condition was false every single time and the rebuild never
+                // ran. A timed-out call therefore left the desynchronised socket in place, and every
+                // later call inherited exactly the ambiguity this reset exists to clear. Deciding
+                // before forgetting is the whole fix; the `else` still drops the stale entry.
+                if (this.socket === socket)
+                    this.reset(error);
+                else
+                    this.forget(id);
+                // reset() already rejected this entry through its wrapper when it ran, so this is
+                // either the only rejection or a no-op that guarantees the caller settles.
                 reject(error);
             }, timeoutMs);
-            this.queue.push({
-                resolve: answer => { clearTimeout(timer); resolve(answer); },
-                reject: error => { clearTimeout(timer); reject(error); },
-            });
             try {
-                socket.write(JSON.stringify({ token: this.endpoint.token, ...request }) + '\n');
+                // The id is added LAST so a request body can never shadow it, and the token is
+                // added here rather than by the caller.
+                socket.write(JSON.stringify({ token: this.endpoint.token, ...request, [REQUEST_ID_FIELD]: id }) + '\n');
             }
             catch (error) {
                 clearTimeout(timer);
-                this.queue.pop();
+                this.forget(id);
                 const failure = error instanceof Error ? error : new Error(String(error));
-                this.reset(failure);
+                if (this.socket === socket)
+                    this.reset(failure);
                 reject(failure);
             }
         });
@@ -80,16 +185,33 @@ export class BridgeConnection {
         const socket = connect({ host: '127.0.0.1', port: this.endpoint.port });
         socket.setEncoding('utf8');
         socket.on('data', chunk => this.onData(String(chunk)));
-        socket.on('error', error => this.reset(error));
-        socket.on('close', () => this.reset(new Error('dsh-builtin-browser: bridge connection closed')));
+        // Both handlers pass the socket they belong to, so a late event from a socket that was
+        // already replaced cannot tear down its successor: 'close' still fires for a socket that
+        // was removed mid-recycle, and acting on it there would kill a perfectly good connection.
+        socket.on('error', error => this.socketFailed(socket, error));
+        socket.on('close', () => this.socketFailed(socket, new Error('dsh-builtin-browser: bridge connection closed')));
         this.buffer = '';
         this.socket = socket;
         socket.write(JSON.stringify({ token: this.endpoint.token }) + '\n');
         return socket;
     }
-    /** Resolve queued requests in order as answers arrive. */
+    /** Tear the connection down for an event raised by `source`, unless it is already gone. */
+    socketFailed(source, error) {
+        if (this.socket !== source)
+            return;
+        this.reset(error);
+    }
+    /** Resolve queued requests by id, or in order when the bridge does not echo one. */
     onData(chunk) {
         this.buffer += chunk;
+        // A peer that never sends a newline must not grow this buffer without bound. Failing
+        // the connection is the honest outcome: the caller gets an error naming the cap, while
+        // the next call dials a fresh socket.
+        if (this.buffer.length > MAX_BUFFER_BYTES) {
+            this.buffer = '';
+            this.reset(new Error(`dsh-builtin-browser: bridge reply exceeded ${String(MAX_BUFFER_BYTES)} bytes`));
+            return;
+        }
         let newline = this.buffer.indexOf('\n');
         while (newline !== -1) {
             const line = this.buffer.slice(0, newline).trim();
@@ -97,9 +219,28 @@ export class BridgeConnection {
             newline = this.buffer.indexOf('\n');
             if (line === '')
                 continue;
-            const entry = this.queue.shift();
+            const echoed = echoOf(line);
+            const id = echoed ?? this.queue[0];
+            if (id === undefined) {
+                // Nothing is waiting for this answer: the peer is answering something this socket
+                // never asked (or answered twice). Drop the socket rather than trust the stream.
+                this.reset(new Error('dsh-builtin-browser: bridge answered with no request outstanding'));
+                return;
+            }
+            const index = this.queue.indexOf(id);
+            if (index !== -1)
+                this.queue.splice(index, 1);
+            const entry = this.pending.get(id);
             if (entry === undefined)
                 continue;
+            this.pending.delete(id);
+            // Id-less bridges pair by order, so a reply for the WRONG request cannot be told apart
+            // from the right one. Remember that this bridge does not echo ids, and serialise every
+            // later call so the ambiguity cannot arise again.
+            if (echoed === undefined) {
+                this.idLessBridge = true;
+                this.serialisable = true;
+            }
             try {
                 const answer = JSON.parse(line);
                 // A rejected token means the shell restarted with a new one, so this socket
@@ -117,6 +258,13 @@ export class BridgeConnection {
             }
         }
     }
+    /** Forget one request (its answer can no longer be matched). */
+    forget(id) {
+        this.pending.delete(id);
+        const index = this.queue.indexOf(id);
+        if (index !== -1)
+            this.queue.splice(index, 1);
+    }
     /** Tear the socket down, failing pending work. */
     reset(error) {
         if (this.socket !== undefined) {
@@ -126,8 +274,23 @@ export class BridgeConnection {
             socket.destroy();
         }
         this.buffer = '';
-        const pending = this.queue.splice(0, this.queue.length);
+        this.queue.length = 0;
+        const pending = [...this.pending.values()];
+        this.pending.clear();
         for (const entry of pending)
             entry.reject(error);
     }
 }
+/** The request id a raw answer line echoes back, when it carries one. */
+function echoOf(line) {
+    try {
+        const answer = JSON.parse(line);
+        const value = answer[REQUEST_ID_FIELD];
+        return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined;
+    }
+    catch {
+        // A malformed line cannot be matched by id; the caller consumes it in order and
+        // reports the parse failure itself.
+        return undefined;
+    }
+}

package/lib/browser-electron/desktop-bridge-host.d.ts

@@ -36,14 +36,51 @@ export declare function bridgeEndpointPath(): string;
  */
 export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
     private readonly connection;
+    /**
+     * One entry per view this host handed out: the conversation it serves, and the guest backing it.
+     *
+     * The conversation belongs to the ENTRY, not to this host. A single plugin process serves every
+     * conversation — DSH runs them all through one host instance — so an owner held on the host
+     * would be one conversation's id applied to all of them, and a page could still land in
+     * another's sidebar however carefully the bridge checked it.
+     */
     private readonly views;
     /**
-     * Guests whose view is gone but whose page may still be open in the sidebar.
+     * This process's identity with the bridge, for tab ownership.
+     *
+     * Every DSH session is its own plugin process, and the sidebar is one surface they all share.
+     * A session can only see its own `views` map, so before the bridge kept a ledger it adopted
+     * whichever tab it found — including one another session had opened, which is how a URL from
+     * one session appeared in another's sidebar. The id is per process, so two sessions never
+     * collide and one session's tabs are never handed to another; it is deliberately not the DSH
+     * session id, which this layer has no access to and does not need.
+     *
+     * The whole ledger rests on that premise, so it was measured rather than assumed: with two
+     * sessions running, the desktop had TWO host processes (plus one main, two renderers and a
+     * gpu/utility pair). If sessions ever shared a process, every owner check in the bridge would
+     * compare equal and the bleed would return in a new shape — so a change to how DSH spawns
+     * sessions invalidates this file, not just this comment.
+     *
+     * It is now the CONVERSATION id rather than an invented uuid, read from the plugin's ctx by the
+     * same path DSH's own desktop host uses. That matters because the shell keeps one sidebar per
+     * conversation and writes its session id onto each sidebar container (on the React fiber,
+     * measured on the running app) — so the bridge can only answer "is this sidebar mine" if it has
+     * a comparable id. With an invented uuid it never could, which is how a command came to be typed
+     * into another conversation's address bar.
+     *
+     * Falls back to a random uuid when the host cannot supply one — an older DSH, or a non-desktop
+     * composition. That is no worse than before: the bridge then knows only "this process", and it
+     * refuses to operate on a sidebar it cannot prove is its own.
+     */
+    private readonly owner;
+    /**
+     * Guests whose view is gone but whose page may still be open in the sidebar, with the
+     * conversation each belongs to.
      *
-     * The provider destroys its view handles before it asks for a release, so the
-     * mapping is dropped by then — keeping the guest ids here is what lets us close
-     * only our own tabs when several sessions are running (requirements §4: each
-     * session gets its own page).
+     * The provider destroys its view handles before it asks for a release, so the mapping is dropped
+     * by then — keeping the guest ids here is what lets us close only our own tabs when several
+     * conversations are running (requirements §4: each session gets its own page). The owner rides
+     * along for the same reason it does in {@link views}: a release names one conversation.
      */
     private readonly orphaned;
     /**
@@ -69,49 +106,43 @@ export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
      * caller falls back to self-hosting, which always works.
      * @returns the host, or undefined when no bridge is available.
      */
-    static discover(): Promise<DesktopBridgeViewHost | undefined>;
+    static discover(sessionId?: string): Promise<DesktopBridgeViewHost | undefined>;
     /** Whether this host can back views: the bridge already answered `list`. */
     available(): boolean;
     /**
-     * The guest id backing a view, materialized on first use.
+     * The guest backing a view, materialized on first use.
      *
-     * The sidebar browser is itself a multi-tab surface, so each view gets its own
-     * tab's guest: the provider's tab bookkeeping then maps onto real tabs the human
-     * can see and switch between. Two rules keep that honest:
-     *   - a cached guest is used as-is: probing it first cost a round-trip on every
-     *     command, so liveness is established by the command failing instead;
-     *   - a fresh view takes an unclaimed guest, growing the tab strip only when
-     *     every existing guest is already spoken for.
+     * The conversation that called owns exactly one sidebar page on this carrier — a human and the
+     * agent look at the same page — so every view resolves to that conversation's own guest, and the
+     * page does not multiply behind the provider's own tab bookkeeping.
+     *
+     * A cached guest is used as-is: probing it first cost a round-trip on every command, so liveness
+     * is established by the command failing instead.
      * @param viewId - the view whose guest is wanted.
-     * @param url - address to use when a sidebar browser has to be opened first.
+     * @param url - address to use when this conversation has no page yet.
      */
     private guestFor;
     /**
-     * Ask for at least `count` sidebar tabs and return their guest ids.
-     * @param count - minimum number of tabs.
+     * @param owner - the conversation this view serves. Recorded WITH the view: one host instance
+     *   serves every conversation, so the owner cannot live on the host.
      */
-    private guestIds;
-    createView(): ElectronViewHandle;
+    createView(owner?: string): ElectronViewHandle;
     destroyView(handle: ElectronViewHandle): void;
     /**
-     * Nothing to show: the sidebar is already on screen, and showing it again is
-     * the shell's business (it owns the tab strip and the visibility toggle).
-     */
-    showView(): void;
-    /** Same as {@link showView}: the page is already presented by the shell. */
-    presentView(): Promise<void>;
-    /**
-     * The shell owns window grouping, and one sidebar serves every view, so there
-     * is nothing to record here. (It must not write a placeholder guest id either:
-     * a view whose guest is not yet materialized has to stay absent from the map,
-     * or the first real command would be sent to the placeholder.)
+     * Bring this view's tab to the front in the sidebar.
+     *
+     * This used to be empty, on the reasoning that the sidebar is already on screen so there is
+     * nothing to show. That confused "the sidebar is visible" with "this page is the one being
+     * looked at": opening a page left it behind whatever the human had in front, which is issue
+     * #23. The other two carriers both do this — the self-hosted window re-adds the view and the
+     * system browser calls `Page.bringToFront` — so this carrier was the odd one out.
+     *
+     * Best-effort by design: the tab strip belongs to the shell's renderer, and failing to raise
+     * it must not fail the navigation that has already happened.
+     * @param handle - the view to bring forward.
      */
-    groupView(): void;
-    /** Focus is the shell's to manage, and there is no separate window to raise. */
-    focus(): Promise<void>;
+    showView(handle: ElectronViewHandle): void;
     onUserAction(handler: (action: BrowserUserAction) => void): void;
-    /** The shell reports its own window lifecycle; nothing to subscribe to here. */
-    onViewClosed(): void;
     /**
      * Release the sidebar's browser pages (requirements §3, `ui.closeWithSession`).
      *
@@ -119,9 +150,11 @@ export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
      * belongs to the shell and would happily keep the page (and its renderer) alive.
      * Closing the tabs is what actually ends the page — and only the page: cookies
      * live in the partition, history on disk, so both survive.
+     * @param owner - the conversation whose pages to close. Omit to close every conversation's,
+     *   which is only correct from a teardown that is itself global.
      * @returns a promise that settles once the shell has been asked.
      */
-    releasePage(): Promise<void>;
+    releasePage(owner?: string): Promise<void>;
     /**
      * Fold the sidebar away without ending the page (`ui.autoExpandOnce` is off, or
      * the caller wants the screen back while work continues).