@platless/axom-cli 0.1.0 → 0.3.13

package/dist/workstation/channels/agent.js

@@ -78,7 +78,13 @@ export async function dispatchAgentChannelFrames(messages, send, agents, close =
                 }
                 continue;
             }
-            await dispatchAgentFrame(agents, frame);
+            // Start handlers in wire order, but keep receiving while their RPCs / disk I/O wait.
+            // A probe can take longer than an open's 30s or a config change's 10s deadline; awaiting it
+            // here makes every unrelated session time out while heartbeats still report a healthy socket.
+            // The manager owns open deduplication, close-during-open tombstones and per-session journal
+            // ordering. Answers, interrupts and closes must also reach it while an earlier RPC is pending.
+            // dispatchAgentFrame catches rejections, including for these detached handlers.
+            void dispatchAgentFrame(agents, frame);
         }
     }
     catch (error) {

package/dist/workstation/channels/computer.js

@@ -1,17 +1,27 @@
+import { DesktopBridge } from '../desktop/bridge.js';
+import { resolveBrowserBinding } from '../desktop/binding.js';
 import { createHash } from 'node:crypto';
 import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { runExec } from '../exec.js';
 import { decodeComputerFrame, encodeComputerFrame } from '../protocol/computer.js';
 import { workstationChannelUrl } from './url.js';
 import { TaskRegistry } from '../update/taskRegistry.js';
+import { createComputerDirSafely, listComputerDirSafely, readComputerFileSafely, writeComputerFileSafely } from '../fileWorkerClient.js';
+import { computerFileError } from '../filePaths.js';
+import { ToolsClient } from '../tools/client.js';
+import { object } from '../tools/validation.js';
 /**
  * Consumes computer frames without serializing long-running commands behind one another.
  * All command failures and post-close sends are contained here because this is called detached
  * from the socket connection loop.
  */
-export async function dispatchComputerFrames(messages, send, execute, tasks = new TaskRegistry()) {
+export async function dispatchComputerFrames(messages, send, execute, tasks = new TaskRegistry(), files = {}, tools, desktop) {
     const active = new Map();
-    const safeSend = (frame) => { try {
+    const activeTools = new Set();
+    let open = true;
+    let wireVersion = 1;
+    const safeSend = (frame) => { if (!open)
+        return; try {
         send(frame);
     }
     catch { /* socket already closed */ } };
@@ -51,15 +61,149 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
             }
         })();
     };
+    const runFile = (request) => {
+        // Read/write landed in wire v2; directory listing and creation arrived with v3.
+        const minWireVersion = request.t === 'file_ls_request' || request.t === 'file_mkdir_request' ? 3 : 2;
+        const fail = (code, message) => {
+            if (request.t === 'file_read_request')
+                safeSend({ t: 'file_read_result', id: request.id, error: { code, message } });
+            else if (request.t === 'file_write_request')
+                safeSend({ t: 'file_write_result', id: request.id, error: { code, message } });
+            else if (request.t === 'file_ls_request')
+                safeSend({ t: 'file_ls_result', id: request.id, error: { code, message } });
+            else
+                safeSend({ t: 'file_mkdir_result', id: request.id, error: { code, message } });
+        };
+        if (wireVersion < minWireVersion) {
+            fail('unsupported_protocol', `Computer file operations require wire v${minWireVersion}`);
+            return;
+        }
+        if (!tasks.accepting) {
+            fail('workstation_offline', 'Workstation is not accepting new work');
+            return;
+        }
+        active.get(request.id)?.abort();
+        const controller = new AbortController();
+        active.set(request.id, controller);
+        void (async () => {
+            try {
+                const data = await tasks.withShellTask(async (shutdown) => {
+                    const onShutdown = () => controller.abort();
+                    if (shutdown.aborted)
+                        controller.abort();
+                    else
+                        shutdown.addEventListener('abort', onShutdown, { once: true });
+                    try {
+                        if (request.t === 'file_read_request') {
+                            return await (files.readFile ?? readComputerFileSafely)({ root: request.root, path: request.path, startLine: request.startLine, maxLines: request.maxLines }, controller.signal);
+                        }
+                        if (request.t === 'file_write_request') {
+                            return await (files.writeFile ?? writeComputerFileSafely)({ root: request.root, path: request.path, content: request.content, mode: request.mode, expectedSha256: request.expectedSha256 }, controller.signal);
+                        }
+                        if (request.t === 'file_ls_request') {
+                            return await (files.listDir ?? listComputerDirSafely)({ root: request.root, path: request.path, startAfter: request.startAfter, maxEntries: request.maxEntries }, controller.signal);
+                        }
+                        return await (files.createDir ?? createComputerDirSafely)({ root: request.root, path: request.path, parents: request.parents }, controller.signal);
+                    }
+                    finally {
+                        shutdown.removeEventListener('abort', onShutdown);
+                    }
+                });
+                if (active.get(request.id) !== controller)
+                    return;
+                if (request.t === 'file_read_request')
+                    safeSend({ t: 'file_read_result', id: request.id, data: data });
+                else if (request.t === 'file_write_request')
+                    safeSend({ t: 'file_write_result', id: request.id, data: data });
+                else if (request.t === 'file_ls_request')
+                    safeSend({ t: 'file_ls_result', id: request.id, data: data });
+                else
+                    safeSend({ t: 'file_mkdir_result', id: request.id, data: data });
+            }
+            catch (error) {
+                if (active.get(request.id) !== controller)
+                    return;
+                const mapped = computerFileError(error);
+                if (controller.signal.aborted) {
+                    const mutation = request.t === 'file_write_request' || request.t === 'file_mkdir_request';
+                    fail(mutation ? 'outcome_unknown' : 'workstation_offline', request.t === 'file_write_request' ? 'Write outcome is unknown after cancellation'
+                        : request.t === 'file_mkdir_request' ? 'Directory creation outcome is unknown after cancellation'
+                            : 'Read was cancelled');
+                }
+                else
+                    fail(mapped.code, mapped.message);
+            }
+            finally {
+                if (active.get(request.id) === controller)
+                    active.delete(request.id);
+            }
+        })();
+    };
+    const runTool = (request) => {
+        const fail = (error) => safeSend({ t: 'tool_result', id: request.id, ok: false, result: {}, error: (error || 'Workstation tool failed').slice(0, 1024) });
+        if (wireVersion < 3) {
+            fail('Workstation tools require computer wire v3');
+            return;
+        }
+        if (!tasks.accepting) {
+            fail('Workstation is not accepting new work');
+            return;
+        }
+        if (!tools && request.method !== 'browser.sharedText') {
+            fail('Workstation tools keeper is not configured');
+            return;
+        }
+        if (activeTools.has(request.id)) {
+            fail('Duplicate tool request id');
+            return;
+        }
+        if (activeTools.size >= 16) {
+            fail('Too many simultaneous tool requests');
+            return;
+        }
+        activeTools.add(request.id);
+        void (async () => {
+            let timer;
+            try {
+                const result = await tasks.withShellTask(() => Promise.race([
+                    request.method === 'browser.sharedText' ? (desktop ? desktop.insertText(request.params) : Promise.reject(Error('Shared desktop unavailable'))) : tools(request.method, request.params),
+                    new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error('Workstation tool timed out; mutation outcome may be unknown')), 7500); }),
+                ]));
+                if (!object(result))
+                    throw new Error('Invalid workstation tool result');
+                safeSend({ t: 'tool_result', id: request.id, ok: true, result, error: null });
+            }
+            catch (error) {
+                fail(error instanceof Error ? error.message : 'Workstation tool failed');
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                activeTools.delete(request.id);
+            }
+        })();
+    };
     try {
         for await (const frame of messages) {
-            if (frame.t === 'exec_request')
+            if (frame.t.startsWith('desktop_'))
+                desktop?.onFrame(frame);
+            else if (frame.t === 'tool_request')
+                runTool(frame);
+            else if (frame.t === 'exec_request')
                 run(frame);
             else if (frame.t === 'exec_cancel')
                 active.get(frame.id)?.abort();
+            else if (frame.t === 'computer_ready') {
+                wireVersion = frame.wireVersion;
+                desktop?.ready(frame.generation, frame.wireVersion);
+            }
+            else if (frame.t === 'file_read_request' || frame.t === 'file_write_request' || frame.t === 'file_ls_request' || frame.t === 'file_mkdir_request')
+                runFile(frame);
         }
     }
     finally {
+        open = false;
+        desktop?.close();
         for (const controller of active.values())
             controller.abort();
     }
@@ -68,9 +212,12 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
 export class ComputerChannel {
     options;
     tasks;
+    tools;
     constructor(options) {
         this.options = options;
         this.tasks = options.taskRegistry ?? new TaskRegistry();
+        const client = options.toolsConfig ? new ToolsClient(options.toolsConfig) : undefined;
+        this.tools = options.tools ?? (client ? (method, params) => client.request(method, params) : undefined);
     }
     activeTaskCount() { return this.tasks.snapshot().activeShellTasks; }
     async connect(ticket, signal) {
@@ -86,6 +233,7 @@ export class ComputerChannel {
         return { closed: channel.closed, close: () => channel.close() };
     }
     async dispatch(channel) {
-        await dispatchComputerFrames(channel.messages, (frame) => channel.send(frame), this.options.runExec ?? runExec, this.tasks);
+        const desktop = new DesktopBridge(resolveBrowserBinding(this.options.browserBinding ?? this.options.toolsConfig?.browserBinding), frame => channel.send(frame), () => channel.bufferedAmount);
+        await dispatchComputerFrames(channel.messages, (frame) => channel.send(frame), this.options.runExec ?? runExec, this.tasks, this.options, this.tools, desktop);
     }
 }

package/dist/workstation/channels/management.js

@@ -8,7 +8,7 @@ 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: { min: 1, max: 4 }, 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) {
@@ -180,8 +180,8 @@ 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,
             channels: {

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)

package/dist/workstation/daemon.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AGENT_WIRE_MIN_VERSION } from './protocol/agent.js';
-import { clientDir, loadClientConfig, readKeys } from './config.js';
+import { clientDir, loadClientConfig, readKeys, updateServiceContext } from './config.js';
 import { AgentSessionManager } from './agentSessions.js';
 import { AcpAgents } from './acp/acpAgents.js';
 import { ConnectionSupervisor } from './connection/supervisor.js';
@@ -12,6 +12,7 @@ import { TaskRegistry } from './update/taskRegistry.js';
 import { createUpdateCoordinator } from './update/runUpdate.js';
 import { resolveCliPath } from './daemonctl.js';
 import { SystemMetricsSampler } from './systemMetrics.js';
+import { preflightOptionalPty } from './update/ptyPreflight.js';
 /**
  * The path `runDaemon` hands `createUpdateCoordinator` as `cliPath`, used to re-provision the OS
  * service after an update (see runUpdate.ts's `provisionService`).
@@ -140,6 +141,22 @@ export function resolveServiceLifecycle(options) {
     // provision-and-arm would hand that mode to a one-shot, unsupervised debugging invocation.
     return options.supervision === 'container' ? 'container' : 'none';
 }
+/**
+ * Builds the object `ManagementChannelOptions.snapshot` reports on every management heartbeat.
+ *
+ * Lifted out of `runDaemon` into its own function -- rather than staying the closure literal
+ * passed inline to `new ManagementChannel({ snapshot: ... })` -- specifically so a test can drive
+ * it directly. `runDaemon` boots a whole daemon (real config, real keys, a real `ManagementChannel`
+ * with no seam for injecting a socket), so before this extraction the *only* thing that ever
+ * verified `update:` here was the boot-*reconciled* phase (`updates.snapshotAsync()`), rather than
+ * the raw on-disk one (`updates.snapshot()`), was `tsc` accepting the `await`. `tsc` cannot tell
+ * `snapshotAsync()` and `snapshot()` apart by behavior -- both type-check -- so a future edit that
+ * quietly swaps one for the other would compile clean and wedge the server's view of every
+ * workstation the next time one restarts mid-update.
+ */
+export async function buildManagementSnapshot(supervisor, tasks, updates) {
+    return { channels: supervisor.channelSnapshot(), ...tasks.snapshot(), update: await updates.snapshotAsync() };
+}
 export async function runDaemon(options = {}) {
     // Last line of defence for the whole process. Node's default for an unhandled rejection is to
     // *exit*, and this daemon is the only thing keeping every session on this workstation alive —
@@ -152,6 +169,9 @@ export async function runDaemon(options = {}) {
     const dir = clientDir();
     const cfg = await loadClientConfig(dir);
     const { clientKey, serverPub } = await readKeys(dir);
+    // Repair the first fixed release even when it was installed by an older ignore-scripts updater,
+    // before a newly started terminal keeper snapshots native dependency availability.
+    await preflightOptionalPty(updateServiceContext(dir));
     const tasks = new TaskRegistry();
     // Attaches both the server-driven update path (onUpdate below) and axom update's manual path to
     // the same coordinator assembly — see runUpdate.ts.
@@ -183,7 +203,9 @@ export async function runDaemon(options = {}) {
     // Plaintext WebSockets are only for an explicitly opted-in local development fixture. Production
     // ticket handshakes must be WSS because the ticket is the data-channel key derivation material.
     const allowInsecureWs = process.env.AXOM_WORKSTATION_ALLOW_INSECURE_WS === '1';
-    const computer = new ComputerChannel({ server: cfg.server, allowInsecureWs, taskRegistry: tasks });
+    const computer = new ComputerChannel({ server: cfg.server, allowInsecureWs, taskRegistry: tasks,
+        toolsConfig: { configDir: dir, workstationId: cfg.workstationId, server: cfg.server, roots: (cfg.workspaces ?? []).map(workspace => workspace.cwd), browserBinding: cfg.browserBinding },
+    });
     const metrics = new SystemMetricsSampler(cfg.workspaces ?? []);
     await metrics.start();
     const management = new ManagementChannel({
@@ -198,7 +220,7 @@ export async function runDaemon(options = {}) {
             bridges = await acp.roster();
             return bridges;
         },
-        snapshot: () => ({ channels: supervisor.channelSnapshot(), ...tasks.snapshot(), update: updates.snapshot() }),
+        snapshot: () => buildManagementSnapshot(supervisor, tasks, updates),
     });
     const agent = new AgentChannel({ server: cfg.server, agents, bridges: () => bridges, allowInsecureWs });
     supervisor = new ConnectionSupervisor({

package/dist/workstation/desktop/binding.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+function endpoint(text, kind) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new Error('Invalid browser endpoint');
+    }
+    // Require literal loopback authorities, before WHATWG canonicalizes short/hex IPv4.
+    if (!/^(?:tcp|ws|wss|http|https):\/\/(?:127\.0\.0\.1|\[::1\]):\d+(?:\/|$)/.test(text) || url.username || url.password || url.search || url.hash || !url.port || Number(url.port) < 1 || Number(url.port) > 65535)
+        throw new Error('Browser endpoints require an explicit loopback host and port without credentials');
+    if (kind === 'vnc' ? !['tcp:', 'ws:', 'wss:'].includes(url.protocol) : !['http:', 'https:'].includes(url.protocol))
+        throw new Error('Unsupported browser endpoint transport');
+    if (url.protocol === 'tcp:' && url.pathname && url.pathname !== '/')
+        throw new Error('TCP endpoint cannot have a path');
+    return url.toString();
+}
+export function resolveBrowserBinding(config, env = process.env) {
+    if (config && (typeof config !== 'object' || typeof config.vncEndpoint !== 'string' || !config.vncEndpoint))
+        throw new Error('Invalid browser binding config');
+    const vnc = env.AXOM_BROWSER_VNC_URL ?? config?.vncEndpoint;
+    if (!vnc)
+        return undefined;
+    const binding = { bindingId: config?.bindingId ?? 'default', displayName: config?.displayName ?? 'Shared browser', vncEndpoint: endpoint(vnc, 'vnc'), cdpEndpoint: env.AXOM_BROWSER_CDP_URL ?? config?.cdpEndpoint, downloadsRoot: config?.downloadsRoot };
+    if (typeof binding.bindingId !== 'string' || !binding.bindingId || binding.bindingId.length > 128 || typeof binding.displayName !== 'string' || !binding.displayName || binding.displayName.length > 128)
+        throw new Error('Invalid browser binding metadata');
+    if (binding.cdpEndpoint)
+        binding.cdpEndpoint = endpoint(binding.cdpEndpoint, 'cdp');
+    if (binding.downloadsRoot !== undefined && (typeof binding.downloadsRoot !== 'string' || !path.isAbsolute(binding.downloadsRoot) || binding.downloadsRoot.includes('\0')))
+        throw new Error('Browser downloadsRoot must be an explicit absolute directory');
+    return binding;
+}
+export function browserCapability(binding) {
+    return { bindingId: binding?.bindingId ?? null, displayName: binding?.displayName ?? null, configured: !!binding, cdp: !!binding?.cdpEndpoint };
+}