@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/channels/management.js

@@ -1,14 +1,15 @@
 import { deriveSessionKey, randomBytes } from '../crypto.js';
 import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { CLIENT_PACKAGE_NAME, CLIENT_VERSION } from '../version.js';
-import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, } from '../protocol/management.js';
-import { bridgesForWire } from '../protocol/common.js';
+import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_GPU_VERSION, MANAGEMENT_WIRE_KEEPERS_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, } from '../protocol/management.js';
+import { bridgesForWire, helloRoster } from '../protocol/common.js';
 import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_VERSION } from '../protocol/agent.js';
 import { osInfo } from '../osinfo.js';
 import { workstationChannelUrl } from './url.js';
 const protocols = {
     MANAGEMENT: { min: MANAGEMENT_WIRE_MIN_VERSION, max: MANAGEMENT_WIRE_VERSION },
-    COMPUTER: { min: 1, max: 1 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
+    // COMPUTER v5: durable exec frames (exec_started/attach/status/ack, offsets on exec_output; spec §4.3).
+    COMPUTER: { min: 1, max: 5 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
 };
 /** Exported so tests can assert the wire frame's `clientPackage` without opening a socket. */
 export function buildHelloFrame(options, clientNonce) {
@@ -24,7 +25,7 @@ export function buildHelloFrame(options, clientNonce) {
  */
 function helloBridges(bridges) {
     const roster = bridges?.();
-    return roster === undefined ? undefined : bridgesForWire(roster, 'management_hello');
+    return roster === undefined ? undefined : bridgesForWire(helloRoster(roster), 'management_hello');
 }
 /** Exported so the roster this answer carries can be asserted without driving a whole channel. */
 export function buildScanResultFrame(commandId, bridges) {
@@ -57,6 +58,10 @@ export function metricsForManagementWire(metrics, serverManagementWire) {
     if (!metrics)
         return metrics;
     const selectedWire = serverManagementWire ?? 0;
+    if (selectedWire < MANAGEMENT_WIRE_GPU_VERSION && metrics.gpus !== undefined) {
+        const { gpus: _gpus, ...withoutGpus } = metrics;
+        return metricsForManagementWire(withoutGpus, selectedWire);
+    }
     if (selectedWire >= MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION) {
         const { cpuLoadNormalized: _cpuLoadNormalized, ...rawLoad } = metrics;
         return rawLoad;
@@ -98,6 +103,51 @@ export function dispatchUpdateCommand(channel, command, onUpdate, serverManageme
     })
         .catch(() => { });
 }
+/**
+ * The most a heartbeat waits for its `keepers` sample. The channel builds the next heartbeat only after this one went out, so a sample
+ * that hangs (a wedged `ps`, a stuck file read) must never hold the frame: past this it goes out with `keepers: null`.
+ */
+export const KEEPERS_SAMPLE_CAP_MS = 1500;
+/**
+ * Heartbeat `keepers` for the negotiated wire: absent below 8 (an older server does not know the field), the sampled list from 8 on,
+ * `null` when sampling failed or did not answer within `capMs`. Never rejects, never waits longer than `capMs`. Exported for tests.
+ */
+export async function keepersForManagementWire(sample, serverManagementWire, capMs = KEEPERS_SAMPLE_CAP_MS) {
+    if (!sample || (serverManagementWire ?? 0) < MANAGEMENT_WIRE_KEEPERS_VERSION)
+        return {};
+    let timer;
+    const capped = new Promise((resolve) => { timer = setTimeout(() => resolve(null), capMs); timer.unref?.(); });
+    try {
+        const sampled = Promise.resolve().then(sample);
+        sampled.catch(() => undefined); // a late rejection after the cap must not be unhandled
+        return { keepers: await Promise.race([sampled, capped]) };
+    }
+    catch {
+        return { keepers: null };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Runs one `keeper_control` and sends its result if the channel is still open. Detached from the frame loop (a replace-now stops
+ * keeper processes, which takes seconds). Exported for tests.
+ */
+export function dispatchKeeperControl(channel, frame, onKeeperControl) {
+    return onKeeperControl(frame)
+        .catch((error) => ({
+        t: 'keeper_control_result', commandId: frame.commandId, kind: frame.kind, action: frame.action, ok: false, affected: [],
+        error: error instanceof Error ? error.message : String(error),
+    }))
+        .then((result) => {
+        if (channel.state !== 'OPEN')
+            return;
+        try {
+            channel.send(result);
+        }
+        catch { /* the channel closed meanwhile; the server asks again with the same commandId */ }
+    });
+}
 /**
  * The server nonce to derive this session's key from.
  *
@@ -125,9 +175,29 @@ export class ManagementChannel {
     options;
     /** Undefined until this connection receives management_ready; reset for every reconnect. */
     serverManagementWire;
+    /** The open channel of the current connection, for frames this client sends unprompted ({@link pushRoster}). */
+    channel;
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Tell the server about a roster that changed without a scan asking (adapter builds moved by Axom,
+     * spec §6.1): the same `external_agents_scan_result` frame a scan answers with, under a client-made
+     * command id no scan is waiting on — the server records the roster and completes nothing. `false`
+     * when there is no open connection; the next `management_hello` carries {@link ManagementChannelOptions.bridges} then.
+     */
+    pushRoster(bridges) {
+        const channel = this.channel;
+        if (!channel || channel.state !== 'OPEN')
+            return false;
+        try {
+            channel.send(buildScanResultFrame(`roster-push-${randomBytes(8).toString('hex')}`, bridges));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     async connect(signal) {
         this.serverManagementWire = undefined;
         const nonce = randomBytes(16);
@@ -161,6 +231,10 @@ export class ManagementChannel {
         // is never driven by the local browser/device-authorization flow.
         await this.options.onReady?.({ generation: ready.generation, release: ready.release });
         const pending = new Map();
+        this.channel = channel;
+        void channel.closed.then(() => { if (this.channel === channel)
+            this.channel = undefined; }, () => { if (this.channel === channel)
+            this.channel = undefined; });
         void this.routeMessages(channel, pending);
         return {
             generation: ready.generation,
@@ -180,10 +254,11 @@ export class ManagementChannel {
             }),
         };
     }
-    heartbeat(seq, sentAtEpochMs) {
-        const snapshot = this.options.snapshot();
+    async heartbeat(seq, sentAtEpochMs) {
+        const snapshot = await this.options.snapshot();
         return {
             t: 'heartbeat', seq, sentAtEpochMs, clientVersion: CLIENT_VERSION,
+            ...(this.options.playgroundCwd ? { playgroundCwd: this.options.playgroundCwd } : {}),
             channels: {
                 MANAGEMENT: snapshot.channels.management,
                 COMPUTER: snapshot.channels.computer,
@@ -195,6 +270,7 @@ export class ManagementChannel {
                 ? { metrics: metricsForManagementWire(this.options.metrics(), this.serverManagementWire) }
                 : {}),
             ...(snapshot.update ? { update: statusForManagementWire(snapshot.update, this.serverManagementWire) } : {}),
+            ...await keepersForManagementWire(this.options.keepers, this.serverManagementWire, this.options.keepersCapMs),
         };
     }
     async nextReady(channel) {
@@ -217,6 +293,10 @@ export class ManagementChannel {
                     void dispatchUpdateCommand(channel, frame, this.options.onUpdate, this.serverManagementWire);
                     continue;
                 }
+                if (frame.t === 'keeper_control' && this.options.onKeeperControl) {
+                    void dispatchKeeperControl(channel, frame, this.options.onKeeperControl);
+                    continue;
+                }
                 if (frame.t === 'external_agents_scan' && this.options.onExternalAgentsScan) {
                     channel.send(buildScanResultFrame(frame.commandId, await this.options.onExternalAgentsScan()));
                 }

package/dist/workstation/config.js

@@ -1,3 +1,4 @@
+import { resolveBrowserBinding } from './desktop/binding.js';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -33,7 +34,8 @@ export async function loadClientConfig(dir) {
     if (!parsed?.server || !parsed.workstationId) {
         throw new Error('Invalid workstation config: server and workstationId are required; run axom auth again');
     }
-    return { server: parsed.server, workstationId: parsed.workstationId, ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
+    const browserBinding = parsed.browserBinding ? resolveBrowserBinding(parsed.browserBinding, {}) : undefined;
+    return { ...(browserBinding ? { browserBinding } : {}), server: parsed.server, workstationId: parsed.workstationId, ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
 }
 export async function writeKeys(dir, clientKeyB64, serverPubB64) {
     await fs.mkdir(dir, { recursive: true });

package/dist/workstation/connection/encryptedChannel.js

@@ -67,6 +67,8 @@ export function connectEncryptedChannel(options) {
     let openTimer;
     let nextSequence = 1;
     const outstandingAcks = new Set();
+    let lastReceivedAt = timers.now();
+    let maxHeartbeatLagMs = 0;
     let resolveClosed;
     let removeAbortListener = () => { };
     const closed = new Promise((resolve) => { resolveClosed = resolve; });
@@ -103,30 +105,87 @@ export function connectEncryptedChannel(options) {
         socket.send(crypto.seal(sessionKey, Buffer.from(options.encode(frame))));
     };
     const scheduleHeartbeat = () => {
+        const dueAt = timers.now() + heartbeatMs;
         heartbeatTimer = timers.setTimeout(() => {
             if (settled)
                 return;
+            maxHeartbeatLagMs = Math.max(maxHeartbeatLagMs, timers.now() - dueAt);
             const sequence = nextSequence++;
             // Register before send: a synchronous server acknowledgement/work frame emitted from
-            // `send` must observe and satisfy this precise liveness period.
+            // `send` must observe and satisfy this precise liveness period. This happens synchronously,
+            // before `options.heartbeat` is even awaited below, so that guarantee holds regardless of
+            // how long building the frame takes.
             outstandingAcks.add(sequence);
-            try {
-                send(options.heartbeat(sequence, timers.now()));
-            }
-            catch {
-                outstandingAcks.delete(sequence);
-                close();
-                return;
-            }
-            // `ws.send` can synchronously deliver close/error through a test double or a transport
-            // implementation. Never resurrect liveness state after that terminal callback.
-            if (settled)
-                return;
-            if (outstandingAcks.size >= missedAcks) {
-                close();
-                return;
-            }
-            scheduleHeartbeat();
+            // `options.heartbeat` may be async (management's reconciles on-disk update state first), so
+            // the rest of this tick's work moves into a promise chain. There is deliberately no separate
+            // "did we close while the frame was being built" guard between the await and `send`: `settled`
+            // and `state` are only ever flipped together, synchronously, inside `finish()`, so `send`'s own
+            // `state !== 'OPEN'` check already covers every case such a guard could -- a second copy of the
+            // same condition here would be unreachable, untestable dead code, not defense in depth.
+            void (async () => {
+                let frame;
+                try {
+                    frame = await options.heartbeat(sequence, timers.now());
+                }
+                catch (error) {
+                    // Unlike a `send` failure (below), this can come from `options.heartbeat` itself doing
+                    // real work before it returns a frame -- management's reconciles on-disk update state
+                    // first -- so a rejection here can be the *only* sign a whole heartbeat cycle silently
+                    // gave up. Log it rather than let the channel simply close with no trace of why.
+                    console.error(`[encrypted-channel] heartbeat frame build failed, closing: ${error instanceof Error ? error.message : String(error)}`);
+                    outstandingAcks.delete(sequence);
+                    close();
+                    return;
+                }
+                try {
+                    send(frame);
+                }
+                catch (error) {
+                    console.error(`[encrypted-channel] heartbeat send failed, closing: ${error instanceof Error ? error.message : String(error)}`);
+                    outstandingAcks.delete(sequence);
+                    close();
+                    return;
+                }
+                // `ws.send` can synchronously deliver close/error through a test double or a transport
+                // implementation. Never resurrect liveness state after that terminal callback.
+                if (settled)
+                    return;
+                if (outstandingAcks.size >= missedAcks) {
+                    console.warn(`${new Date(timers.now()).toISOString()} [encrypted-channel] ${options.url.pathname} closing after ` +
+                        `${outstandingAcks.size} unconfirmed heartbeats; silentMs=${Math.max(0, timers.now() - lastReceivedAt)}, ` +
+                        `timerLagMs=${maxHeartbeatLagMs}`);
+                    close();
+                    return;
+                }
+                scheduleHeartbeat();
+            })().catch((error) => {
+                // Nothing above is expected to throw past its own try/catch except `close()`'s
+                // `socket.close()` (a caller-supplied `WebSocketLike`) and `scheduleHeartbeat`'s
+                // `timers.setTimeout` -- both call into code this module does not control. Before
+                // `options.heartbeat` could be async, the equivalent synchronous throw escaped this
+                // `setTimeout` callback as an uncaught exception, which Node turns into a process exit that
+                // the supervisor restarts: loud and recoverable. Now it is a promise rejection instead, and
+                // `daemon.ts` registers a process-wide `unhandledRejection` handler that deliberately logs
+                // and keeps the daemon alive -- exactly wrong here, because an uncaught throw from
+                // `scheduleHeartbeat` in particular leaves `settled` false and `state` stuck at `'OPEN'`
+                // with nothing left to ever arm another heartbeat: the channel reports healthy forever while
+                // it has silently stopped. Force it terminal by hand instead of trusting whichever call
+                // above almost got there. `finish()` alone is synchronous and safe to call unconditionally
+                // (and idempotent if `close()` already ran before throwing). It does call two
+                // caller-supplied functions -- `timers.clearTimeout` and `removeAbortListener` (which wraps
+                // `AbortSignal.removeEventListener` when `options.signal` was given) -- so it is not
+                // literally incapable of throwing; it is safe here because production wiring for both is a
+                // real timer API and a real `AbortSignal`, neither of which throws from clearing/removing.
+                // The socket close is only ever best-effort from here, specifically so
+                // this handler's own failure stays impossible even if the very thing that just threw was
+                // `socket.close()` itself.
+                console.error(`[encrypted-channel] heartbeat cycle failed unrecoverably: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+                finish();
+                try {
+                    socket.close();
+                }
+                catch { /* best-effort; already reported above */ }
+            });
         }, heartbeatMs);
     };
     return new Promise((resolve, reject) => {
@@ -183,7 +242,7 @@ export function connectEncryptedChannel(options) {
                         throw new Error('Encrypted channel needs a session key or handshake');
                     opened = true;
                     if (options.initialFrame)
-                        send(options.initialFrame());
+                        send(await options.initialFrame());
                     // An initial proof may synchronously trigger a socket close/error. `opened` permits the
                     // proof frame itself, but the public connection is not published until this guard passes.
                     if (settled || connectionSettled)
@@ -193,6 +252,7 @@ export function connectEncryptedChannel(options) {
                     disarmOpenTimer();
                     resolve({
                         send,
+                        get bufferedAmount() { return socket.bufferedAmount ?? 0; },
                         messages,
                         close,
                         closed,
@@ -226,14 +286,20 @@ export function connectEncryptedChannel(options) {
                 // be the only server traffic while a task runs. Invalid frames take the catch path and never
                 // get to satisfy liveness.
                 outstandingAcks.clear();
+                lastReceivedAt = timers.now();
+                maxHeartbeatLagMs = 0;
                 if (!acknowledged)
                     messages.push(frame);
             }
             catch {
+                console.warn(`${new Date(timers.now()).toISOString()} [encrypted-channel] ${options.url.pathname} closing after an invalid encrypted frame`);
                 close();
             }
         });
-        socket.on('close', () => {
+        socket.on('close', (code, reason) => {
+            if (!settled)
+                console.warn(`${new Date(timers.now()).toISOString()} [encrypted-channel] ${options.url.pathname} peer closed; ` +
+                    `code=${code ?? 'unknown'}, reason=${reason?.toString() || 'none'}`);
             if (!connectionSettled) {
                 connectionSettled = true;
                 finish();
@@ -242,9 +308,10 @@ export function connectEncryptedChannel(options) {
             }
             finish();
         });
-        socket.on('error', () => {
+        socket.on('error', (error) => {
             if (settled)
                 return;
+            console.warn(`${new Date(timers.now()).toISOString()} [encrypted-channel] ${options.url.pathname} socket error: ${error?.message ?? 'unknown'}`);
             const rejectOpening = !connectionSettled;
             // Mark this before close(): ws and deterministic fakes can emit close synchronously.
             if (rejectOpening)