@koalaauto/agentchannel 3.3.0 → 3.4.0

package/dist/src/attention.d.ts

@@ -46,31 +46,59 @@ export declare class AttentionNotifier {
     private run;
     stop(): void;
 }
+/** What ChangeFeed needs of a WebSocket (the WHATWG interface: undici's, a browser's, a test's fake). */
+export interface FeedSocket {
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', fn: (ev: any) => void): void;
+    close(code?: number, reason?: string): void;
+}
 export interface ChangeFeedOptions {
     request: Request;
     onChange: () => unknown;
+    /** Opens the hub's change stream (GET /api/ach/events; Client.eventsSocket). Absent or null: long poll only. */
+    socket?: () => FeedSocket | null;
+    /** How long a socket may take to open before the long poll takes over. */
+    wsOpenMs?: number;
+    /** While on the socket, check anyway this often (a change that published no event, a socket that died silently). */
+    wsCheckMs?: number;
     /** Long-poll wait (s), ≤ 25. */
     waitS?: number;
     /** Fallback polling interval. */
     pollMs?: number;
+    /** In polling mode, try the socket again after this many polls (a hub that was down at start). */
+    wsRetryPolls?: number;
     sleep?: (ms: number) => Promise<void>;
     log?: (s: string) => void;
 }
 /**
- * Follows GET /api/ach/changes (long poll). Falls back to polling (onChange
- * every pollMs) when the hub refuses the route (403/404: an older hub, or
- * person sessions only) — permanently — or after an error (one interval, then
- * the long poll again).
+ * Follows the hub's changes, with fallbacks, like the panel (hub/pb_public/realtime.js):
+ *   1. the WebSocket GET /api/ach/events (the Worker hub): "something changed", ids only; a socket that worked and
+ *      then closed (a deploy, a network change) is opened again;
+ *   2. when it does not open, the long poll GET /api/ach/changes (the PocketBase hub);
+ *   3. when the hub refuses that (403/404/405), polling (onChange every pollMs); from there the socket is tried again
+ *      now and then. An error on the long poll: one polling interval, then the long poll again.
+ * onChange calls never overlap: a change during one runs it once more afterwards.
  */
 export declare class ChangeFeed {
     private o;
-    mode: 'longpoll' | 'poll';
+    mode: 'ws' | 'longpoll' | 'poll';
     private stopped;
     private cursor;
+    private ws;
+    /** Ends the socket being followed now (stop() does not wait for the closing handshake). */
+    private endSocket;
+    private wsDue;
+    /** The socket opened at least once (a later failure retries it before giving up). */
+    private wsWorked;
+    private firing;
+    private again;
     constructor(o: ChangeFeedOptions);
     stop(): void;
     private fire;
-    /** Runs until stop(). `rounds` bounds the loop (tests). */
+    /** One socket, until it ends. Resolves with how long it was open (ms), or -1 when it never opened. */
+    private oneSocket;
+    /** Stays on the socket while it works; returns when it cannot be used (or on stop). */
+    private followSocket;
+    /** Runs until stop(). `rounds` bounds the long-poll / polling loop (tests). */
     run(rounds?: number): Promise<void>;
 }
 export type Exec = (cmd: string, args: string[]) => Promise<{

package/dist/src/attention.js

@@ -2,9 +2,9 @@
  * Reminders, never content. Two pieces shared by `ach mcp` (an open Claude
  * Code / Codex session) and `ach run --notify` (the background helper):
  *
- * - ChangeFeed: follows the hub's change stream. GET /api/ach/changes long-poll
- *   (wait ≈ 25 s); when the hub refuses it (older hub: person sessions only) or
- *   it errors, falls back to polling every 15 s.
+ * - ChangeFeed: follows the hub's change stream: the GET /api/ach/events
+ *   WebSocket (the Worker hub), else the GET /api/ach/changes long poll
+ *   (wait ≈ 25 s; the PocketBase hub), else polling every 15 s.
  * - AttentionNotifier: on a change, counts what needs the owner (questions,
  *   decisions, mentions...) and, when something new arrived, delivers ONE line
  *   ("AgentChannel: 2 items need you (1 question, 1 decision) — say 'check my
@@ -171,40 +171,183 @@ export class AttentionNotifier {
 }
 const realSleep = (ms) => new Promise((r) => setTimeout(r, ms).unref?.());
 /**
- * Follows GET /api/ach/changes (long poll). Falls back to polling (onChange
- * every pollMs) when the hub refuses the route (403/404: an older hub, or
- * person sessions only) — permanently — or after an error (one interval, then
- * the long poll again).
+ * Follows the hub's changes, with fallbacks, like the panel (hub/pb_public/realtime.js):
+ *   1. the WebSocket GET /api/ach/events (the Worker hub): "something changed", ids only; a socket that worked and
+ *      then closed (a deploy, a network change) is opened again;
+ *   2. when it does not open, the long poll GET /api/ach/changes (the PocketBase hub);
+ *   3. when the hub refuses that (403/404/405), polling (onChange every pollMs); from there the socket is tried again
+ *      now and then. An error on the long poll: one polling interval, then the long poll again.
+ * onChange calls never overlap: a change during one runs it once more afterwards.
  */
 export class ChangeFeed {
     o;
     mode = 'longpoll';
     stopped = false;
     cursor = '';
+    ws = null;
+    /** Ends the socket being followed now (stop() does not wait for the closing handshake). */
+    endSocket = null;
+    wsDue;
+    /** The socket opened at least once (a later failure retries it before giving up). */
+    wsWorked = false;
+    firing = null;
+    again = false;
     constructor(o) {
         this.o = o;
+        this.wsDue = !!o.socket;
     }
     stop() {
         this.stopped = true;
-    }
-    async fire() {
+        const s = this.ws;
+        this.ws = null;
         try {
-            await this.o.onChange();
+            s?.close(1000, 'bye');
         }
         catch {
-            /* the consumer logs its own errors */
+            /* already closed */
         }
+        this.endSocket?.();
     }
-    /** Runs until stop(). `rounds` bounds the loop (tests). */
+    fire() {
+        if (this.firing) {
+            this.again = true;
+            return this.firing;
+        }
+        this.firing = (async () => {
+            do {
+                this.again = false;
+                try {
+                    await this.o.onChange();
+                }
+                catch {
+                    /* the consumer logs its own errors */
+                }
+            } while (this.again && !this.stopped);
+        })().finally(() => {
+            this.firing = null;
+        });
+        return this.firing;
+    }
+    /** One socket, until it ends. Resolves with how long it was open (ms), or -1 when it never opened. */
+    oneSocket() {
+        return new Promise((resolve) => {
+            let s = null;
+            try {
+                s = this.o.socket();
+            }
+            catch (e) {
+                this.o.log?.(`change stream: socket: ${String(e?.message ?? e).slice(0, 200)}`);
+            }
+            if (!s)
+                return resolve(-1);
+            const sock = s;
+            this.ws = sock;
+            let openedAt = 0;
+            let done = false;
+            let check = null;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(openTimer);
+                if (check)
+                    clearInterval(check);
+                if (this.ws === sock)
+                    this.ws = null;
+                this.endSocket = null;
+                resolve(openedAt ? Date.now() - openedAt : -1);
+            };
+            this.endSocket = finish;
+            const openTimer = setTimeout(() => {
+                if (openedAt)
+                    return;
+                try {
+                    sock.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                finish();
+            }, this.o.wsOpenMs ?? 5000);
+            openTimer.unref?.();
+            sock.addEventListener('open', () => {
+                if (done)
+                    return;
+                openedAt = Date.now();
+                clearTimeout(openTimer);
+                if (this.mode !== 'ws')
+                    this.o.log?.('change stream: connected (websocket)');
+                this.mode = 'ws';
+                this.wsWorked = true;
+                void this.fire();
+                check = setInterval(() => void this.fire(), this.o.wsCheckMs ?? 5 * 60_000);
+                check.unref?.();
+            });
+            sock.addEventListener('message', () => {
+                if (!done && !this.stopped)
+                    void this.fire();
+            });
+            sock.addEventListener('close', finish);
+            sock.addEventListener('error', () => {
+                try {
+                    sock.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                finish();
+            });
+        });
+    }
+    /** Stays on the socket while it works; returns when it cannot be used (or on stop). */
+    async followSocket(sleep) {
+        let fails = 0;
+        while (!this.stopped) {
+            const lived = await this.oneSocket();
+            if (this.stopped)
+                return;
+            // a socket that stayed up a while worked: open it again at once; one that dropped quickly counts as a failure
+            if (lived >= 10_000)
+                fails = 0;
+            else
+                fails++;
+            if (!this.wsWorked || fails >= 4)
+                return;
+            if (fails > 0)
+                this.o.log?.('change stream: socket closed; reconnecting');
+            await sleep(Math.min(30_000, 1000 * 2 ** Math.max(0, fails - 1)));
+        }
+    }
+    /** Runs until stop(). `rounds` bounds the long-poll / polling loop (tests). */
     async run(rounds = Infinity) {
         const sleep = this.o.sleep ?? realSleep;
         const poll = this.o.pollMs ?? 15_000;
         const wait = Math.min(25, this.o.waitS ?? 25);
+        const retryPolls = this.o.wsRetryPolls ?? 20;
         let errors = 0;
-        for (let i = 0; i < rounds && !this.stopped; i++) {
+        let polls = 0;
+        let longpollRefused = false;
+        for (let i = 0; i < rounds && !this.stopped;) {
+            if (this.wsDue) {
+                this.wsDue = false;
+                await this.followSocket(sleep);
+                if (this.stopped)
+                    return;
+                const was = this.mode;
+                this.mode = longpollRefused ? 'poll' : 'longpoll';
+                this.cursor = '';
+                if (was === 'ws')
+                    this.o.log?.(`change stream: websocket lost; ${this.mode === 'poll' ? `polling every ${Math.round(poll / 1000)} s` : 'long poll'}`);
+                continue;
+            }
+            i++;
             if (this.mode === 'poll') {
                 await this.fire();
                 await sleep(poll);
+                if (this.o.socket && ++polls >= retryPolls) {
+                    polls = 0;
+                    this.wsDue = true;
+                }
                 continue;
             }
             const t0 = Date.now();
@@ -226,6 +369,7 @@ export class ChangeFeed {
             catch (e) {
                 if (e instanceof HubError && (e.status === 403 || e.status === 404 || e.status === 405)) {
                     this.mode = 'poll';
+                    longpollRefused = true;
                     this.o.log?.(`change stream not available (${e.status}); polling every ${Math.round(poll / 1000)} s`);
                     continue;
                 }

package/dist/src/cli.js

@@ -1692,7 +1692,7 @@ async function runCommand(p, io) {
     let desk = null;
     if (v.notify && !v['no-notify']) {
         const { DeskNotifier } = await import('./desknotify.js');
-        const dn = new DeskNotifier({ request: (m, path) => c.request(m, path), home, hub: env.ACH_PUBLIC_URL || cfg.hub, env, log: io.err });
+        const dn = new DeskNotifier({ request: (m, path) => c.request(m, path), socket: () => c.eventsSocket(), home, hub: env.ACH_PUBLIC_URL || cfg.hub, env, log: io.err });
         dn.start();
         desk = dn;
         io.err('ach run: desktop notifications on (--no-notify to turn off)');

package/dist/src/client.d.ts

@@ -303,6 +303,13 @@ export declare class Client {
     private cfSecret?;
     private fetchFn;
     constructor(o: ClientOptions);
+    private ownFetch;
+    /**
+     * The hub's change stream (GET /api/ach/events, a WebSocket that says "something changed", ids only). The token
+     * travels as the `ach.<token>` subprotocol; the Cloudflare Access service token as headers, like every request.
+     * null without a token, or when this client was given its own fetch (a socket would bypass it).
+     */
+    eventsSocket(): WebSocket | null;
     headers(json?: boolean): Record<string, string>;
     /** `files`: local paths (already checked by resolveAttachments) sent as multipart with the JSON in field "json". */
     request<T = any>(method: string, path: string, body?: unknown, files?: string[]): Promise<T>;

package/dist/src/client.js

@@ -1,5 +1,6 @@
 import { openAsBlob, statSync } from 'node:fs';
 import { basename } from 'node:path';
+import { WebSocket as UndiciWebSocket } from 'undici';
 import { attachmentForm, bigFiles, downloadFile, isLinkRef, linkRef, taskFiles, typeOf, uploadTarget } from './attachments.js';
 export const TERMINAL = ['completed', 'failed', 'canceled'];
 export function isTerminal(s) {
@@ -69,6 +70,25 @@ export class Client {
         this.cfId = o.cfId;
         this.cfSecret = o.cfSecret;
         this.fetchFn = o.fetch ?? ((u, i) => fetch(u, i));
+        this.ownFetch = !!o.fetch;
+    }
+    ownFetch;
+    /**
+     * The hub's change stream (GET /api/ach/events, a WebSocket that says "something changed", ids only). The token
+     * travels as the `ach.<token>` subprotocol; the Cloudflare Access service token as headers, like every request.
+     * null without a token, or when this client was given its own fetch (a socket would bypass it).
+     */
+    eventsSocket() {
+        if (!this.token || this.ownFetch)
+            return null;
+        const url = new URL('/api/ach/events', `${this.hub}/`);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        const headers = { 'user-agent': 'agentchannel-cli' };
+        if (this.cfId && this.cfSecret) {
+            headers['CF-Access-Client-Id'] = this.cfId;
+            headers['CF-Access-Client-Secret'] = this.cfSecret;
+        }
+        return new UndiciWebSocket(url.href, { protocols: [`ach.${this.token}`], headers });
     }
     headers(json = true) {
         const h = json ? { 'content-type': 'application/json', accept: 'application/json' } : { accept: 'application/json' };

package/dist/src/desknotify.d.ts

@@ -60,6 +60,8 @@ export interface DeskNotifierOptions {
     /** Runs a notifier that waits for the click (alerter, notify-send --wait): long timeout. */
     actionExec?: NotifyExec;
     log?: (s: string) => void;
+    /** Opens the hub's change stream (Client.eventsSocket); absent: long poll, then polling. */
+    socket?: () => import('./attention.js').FeedSocket | null;
 }
 /** A decision notification waits up to an hour for the click. */
 export declare const ACTION_TIMEOUT_S = 3600;
@@ -149,7 +151,7 @@ export declare class DeskNotifier {
      * handled in the background: the notifier keeps polling meanwhile.
      */
     private showActions;
-    /** Follows the hub's change stream (long poll; 15 s polling fallback). */
+    /** Follows the hub's change stream (WebSocket, else long poll, else 15 s polling). */
     start(): void;
     private stopped;
     stop(): void;

package/dist/src/desknotify.js

@@ -411,12 +411,12 @@ export class DeskNotifier {
         });
         return true;
     }
-    /** Follows the hub's change stream (long poll; 15 s polling fallback). */
+    /** Follows the hub's change stream (WebSocket, else long poll, else 15 s polling). */
     start() {
         void import('./attention.js').then(({ ChangeFeed }) => {
             if (this.stopped)
                 return;
-            const feed = new ChangeFeed({ request: (m, p) => this.o.request(m, p), onChange: () => this.tick(), pollMs: this.o.intervalMs, log: this.o.log });
+            const feed = new ChangeFeed({ request: (m, p) => this.o.request(m, p), socket: this.o.socket, onChange: () => this.tick(), pollMs: this.o.intervalMs, log: this.o.log });
             this.feed = feed;
             void feed.run();
         });

package/dist/src/mcp.js

@@ -469,7 +469,7 @@ export function startSessionNotices(server, client, o = {}) {
         gapMs: o.gapMs,
         log: o.log,
     });
-    const feed = new ChangeFeed({ request, onChange: () => notifier.check(), log: o.log, ...o.feed });
+    const feed = new ChangeFeed({ request, socket: () => client.eventsSocket(), onChange: () => notifier.check(), log: o.log, ...o.feed });
     const done = feed.run();
     return {
         notifier,

package/dist/src/version.d.ts

@@ -1,3 +1,3 @@
-export declare const VERSION = "3.3.0";
+export declare const VERSION = "3.4.0";
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export declare const PKG_NAME = "@koalaauto/agentchannel";

package/dist/src/version.js

@@ -1,3 +1,3 @@
-export const VERSION = '3.3.0';
+export const VERSION = '3.4.0';
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export const PKG_NAME = '@koalaauto/agentchannel';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koalaauto/agentchannel",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Hand work between your team's agents (Claude Code, Codex) and follow it in one panel: the ach CLI, MCP server and runner for AgentChannel v2",
   "keywords": [
     "agentchannel",