@platless/axom-cli 0.1.0

package/dist/workstation/crypto.js

@@ -0,0 +1,63 @@
+import { createHmac, createCipheriv, createDecipheriv, generateKeyPairSync, createPublicKey, createPrivateKey, diffieHellman, randomBytes as nodeRandomBytes, } from 'node:crypto';
+const INFO = Buffer.from('axom-workstation-tunnel-v1');
+// DER prefixes for raw X25519 keys (RFC 8410).
+const PUB_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+const PRIV_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex');
+export function randomBytes(n) {
+    return nodeRandomBytes(n);
+}
+export function generateKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync('x25519');
+    const pubDer = publicKey.export({ type: 'spki', format: 'der' });
+    const privDer = privateKey.export({ type: 'pkcs8', format: 'der' });
+    return {
+        publicKey: pubDer.subarray(pubDer.length - 32),
+        privateKey: privDer.subarray(privDer.length - 32),
+    };
+}
+function rawToPublicKey(raw) {
+    return createPublicKey({ key: Buffer.concat([PUB_PREFIX, raw]), format: 'der', type: 'spki' });
+}
+function rawToPrivateKey(raw) {
+    return createPrivateKey({ key: Buffer.concat([PRIV_PREFIX, raw]), format: 'der', type: 'pkcs8' });
+}
+function hkdfSha256(ikm, salt, info, length) {
+    const prk = createHmac('sha256', salt).update(ikm).digest();
+    let t = Buffer.alloc(0);
+    const chunks = [];
+    let generated = 0;
+    let counter = 1;
+    while (generated < length) {
+        const h = createHmac('sha256', prk);
+        h.update(t);
+        h.update(info);
+        h.update(Buffer.from([counter]));
+        t = h.digest();
+        chunks.push(t);
+        generated += t.length;
+        counter++;
+    }
+    return Buffer.concat(chunks).subarray(0, length);
+}
+export function deriveSessionKey(privSelf, pubPeer, clientNonce, serverNonce) {
+    const shared = diffieHellman({
+        privateKey: rawToPrivateKey(privSelf),
+        publicKey: rawToPublicKey(pubPeer),
+    });
+    return hkdfSha256(shared, Buffer.concat([clientNonce, serverNonce]), INFO, 32);
+}
+export function seal(sessionKey, plaintext) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', sessionKey, iv);
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, ct, tag]);
+}
+export function open(sessionKey, frame) {
+    const iv = frame.subarray(0, 12);
+    const tag = frame.subarray(frame.length - 16);
+    const ct = frame.subarray(12, frame.length - 16);
+    const decipher = createDecipheriv('aes-256-gcm', sessionKey, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ct), decipher.final()]);
+}

package/dist/workstation/daemon.js

@@ -0,0 +1,225 @@
+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 { AgentSessionManager } from './agentSessions.js';
+import { AcpAgents } from './acp/acpAgents.js';
+import { ConnectionSupervisor } from './connection/supervisor.js';
+import { ManagementChannel } from './channels/management.js';
+import { ComputerChannel } from './channels/computer.js';
+import { AgentChannel, dispatchAgentFrame as dispatchAgentChannelFrame } from './channels/agent.js';
+import { TaskRegistry } from './update/taskRegistry.js';
+import { createUpdateCoordinator } from './update/runUpdate.js';
+import { resolveCliPath } from './daemonctl.js';
+import { SystemMetricsSampler } from './systemMetrics.js';
+/**
+ * The path `runDaemon` hands `createUpdateCoordinator` as `cliPath`, used to re-provision the OS
+ * service after an update (see runUpdate.ts's `provisionService`).
+ *
+ * Delegates to `resolveCliPath` (daemonctl.ts) rather than hand-rolling a second join: `daemon.ts`
+ * compiles to `dist/workstation/daemon.js`, the same depth as `dist/workstation/daemonctl.js`, so
+ * the package's real bin entry is one level *up* from either — not a sibling of `daemon.js`, which
+ * is where the old, now-removed `@platless/axom-workstation` package's `cli.js` used to live.
+ *
+ * Takes the directory explicitly, defaulting to this module's own compiled location, so a test can
+ * drive it against a directory that mirrors the compiled layout without depending on a prior build.
+ */
+export function daemonCliPath(daemonDir = path.dirname(fileURLToPath(import.meta.url))) {
+    return resolveCliPath(daemonDir);
+}
+/**
+ * Dispatch one `agent_*` frame, swallowing whatever the manager (and the agent behind it) throws.
+ *
+ * The websocket listener this runs under is an async callback: a rejection escaping it is an
+ * unhandled rejection, which by Node's default **kills the process** — taking exec, the heartbeat
+ * and every other session on this workstation with it. `prompt`/`answer`/`setConfigOption` are
+ * called synchronously on this path and end up in third-party agent output handling, so "the
+ * manager happens to catch everything today" is not a property worth resting a daemon on.
+ *
+ * Exported for the test that pins this behaviour.
+ */
+export async function dispatchAgentFrame(agents, frame) {
+    await dispatchAgentChannelFrame(agents, frame);
+}
+/**
+ * The per-connection agent-wire negotiation, lifted out of the websocket callback so it can be
+ * driven by a test.
+ *
+ * Worth its own seam because of what the one comparison inside it can do: gate on
+ * `AGENT_WIRE_VERSION` instead of {@link AGENT_WIRE_MIN_VERSION} and every workstation whose server
+ * is one version behind silently loses external agents entirely. That failure is invisible to any
+ * test whose two ends are built from the same constant — which is every same-version test there is —
+ * so the only thing that can catch it is feeding a deliberately *older* `ready` and checking that
+ * agent frames still flow.
+ */
+export function createAgentWireGate(agents, send) {
+    let supported = false;
+    return {
+        get supported() { return supported; },
+        onReady(serverAgentWire) {
+            // An older server cannot decode agent_* frames and drops the connection on receiving one, so
+            // below the floor the manager stays unbound and emits nothing.
+            //
+            // The floor is the *minimum*, not this build's own version: gating on an exact match would
+            // mean every wire bump switches external agents off for everyone who has not upgraded their
+            // server yet. The server's actual version is handed to the manager so the frames added after
+            // v1 can gate themselves on it.
+            const negotiated = serverAgentWire ?? 0;
+            supported = negotiated >= AGENT_WIRE_MIN_VERSION;
+            if (supported)
+                agents.bindSend(send, negotiated);
+        },
+        async handleAgentFrame(frame) {
+            if (!supported)
+                return;
+            await dispatchAgentFrame(agents, frame);
+        },
+    };
+}
+/**
+ * How long an agent session may go without a single frame from the server and without producing a
+ * single event before the daemon closes it on its own.
+ *
+ * Six hours, because this timer is a garbage collector for *orphans*, not an inactivity policy. A
+ * session the server still knows about is refreshed by any traffic in either direction, so the only
+ * way to reach six hours of two-way silence is for the server to have forgotten the session (its
+ * table is in memory — a restart wipes it, and the `agent_close` for those refs is never sent) or
+ * for the workstation to have been offline when the run was archived. A human pause — thinking,
+ * lunch, a long unattended tool call, an approval card left open over a meeting — has to stay far
+ * inside the budget, because the cost of being wrong is killing a running agent and its unsaved
+ * work. Six hours is comfortably past any of those and still bounds an orphan's lifetime to well
+ * under a day, versus "until the daemon restarts" without it.
+ */
+export const IDLE_SESSION_TTL_MS = 6 * 60 * 60 * 1000;
+/**
+ * How often the sweep runs. Ten minutes: the deadline is six hours, so the interval only sets how
+ * far past it an orphan may linger — 10min is ~3% slop, invisible against the TTL, while keeping
+ * the wakeups (and the map scan behind them) to 144 a day on a laptop that may be on battery.
+ */
+export const IDLE_SWEEP_INTERVAL_MS = 10 * 60 * 1000;
+/**
+ * Starts the idle-session sweep and returns its stop function.
+ *
+ * Tied to the daemon's lifetime: started with it, cleared when it ends. The timer is `unref`'d so
+ * it can never be the reason the process stays alive, and the callback swallows its own failure —
+ * nobody awaits a timer callback, and an escaping rejection is an unhandled rejection, which Node
+ * answers by exiting.
+ */
+export function startIdleSweep(agents, ttlMs = IDLE_SESSION_TTL_MS, intervalMs = IDLE_SWEEP_INTERVAL_MS) {
+    const timer = setInterval(() => {
+        void (async () => {
+            try {
+                const swept = await agents.sweepIdle(ttlMs, Date.now());
+                if (swept.length > 0) {
+                    // Worth a log line at warn: this closed agent subprocesses nothing else was going to.
+                    console.warn(`[agent] closed ${swept.length} idle session(s) after ${ttlMs}ms: ${swept.join(', ')}`);
+                }
+            }
+            catch (err) {
+                const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+                console.error(`[agent] idle sweep failed: ${detail}`);
+            }
+        })();
+    }, intervalMs);
+    timer.unref();
+    return () => clearInterval(timer);
+}
+/**
+ * Pure mapping from how this process was invoked to the update lifecycle it gets. Lifted out of
+ * `runDaemon` — which also loads client config, reads keys off disk and opens network connections
+ * — so a test can pin the mapping itself without booting the whole daemon. See `RunDaemonOptions`
+ * for why `supervisedByServiceManager` must be explicit rather than inferred from an absent key.
+ */
+export function resolveServiceLifecycle(options) {
+    if (options.supervisedByServiceManager)
+        return 'provision-and-arm';
+    // The bare `axom workstation` command's own detected supervision only ever distinguishes
+    // 'container' (see runUpdate.ts's serviceLifecycle doc for that policy) from everything else,
+    // which all means 'none': `detectSupervision()` reports 'launchd' for any darwin process,
+    // supervised or not, so treating a merely *detected* launchd/systemd as license to
+    // provision-and-arm would hand that mode to a one-shot, unsupervised debugging invocation.
+    return options.supervision === 'container' ? 'container' : 'none';
+}
+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 —
+    // dying because one async callback rejected is strictly worse than logging and carrying on.
+    // Registered once, on the daemon path only (the CLI's one-shot commands keep the default).
+    process.on('unhandledRejection', (reason) => {
+        const detail = reason instanceof Error ? (reason.stack ?? reason.message) : String(reason);
+        console.error(`[daemon] unhandled rejection (ignored, daemon stays up): ${detail}`);
+    });
+    const dir = clientDir();
+    const cfg = await loadClientConfig(dir);
+    const { clientKey, serverPub } = await readKeys(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.
+    const updates = createUpdateCoordinator({
+        dir, server: cfg.server, tasks,
+        cliPath: daemonCliPath(),
+        // launchd/systemd is configured with KeepAlive/Restart=always, and a container has its own
+        // restart policy. Exiting is therefore the atomic hand-off from the old package to the freshly
+        // installed daemon.
+        //
+        // Passed unconditionally on purpose: `createUpdateCoordinator` drops it for the one lifecycle
+        // that has nothing to hand off to (`'none'` — see `lifecyclePolicy().restartsOnHandoff`),
+        // alongside the other three policy decisions. Gating it here instead would put a fourth copy of
+        // the same string comparison at a call site, which is exactly where the first three were
+        // deliberately taken out of.
+        restart: async () => { process.exit(0); },
+        // The daemon is the service manager's own supervised process: it is the one caller that must
+        // rewrite the service definition and arm the rollback watchdog. See RunDaemonOptions and
+        // resolveServiceLifecycle above for how that treatment is keyed on *how this process was
+        // invoked*, not on what the host merely supports.
+        serviceLifecycle: resolveServiceLifecycle(options),
+    });
+    // One ACP client for every external agent; the roster it reports is the ACP agent registry, keyed
+    // by registry agent id (ruling R2) — the same key `agent_open.bridge` now carries.
+    const acp = new AcpAgents({ cacheDir: dir });
+    const agents = new AgentSessionManager(acp, null, path.join(dir, 'agents'), undefined, tasks);
+    let bridges = await acp.roster();
+    let supervisor;
+    // 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 metrics = new SystemMetricsSampler(cfg.workspaces ?? []);
+    await metrics.start();
+    const management = new ManagementChannel({
+        server: cfg.server, workstationId: cfg.workstationId, workstation: cfg.workstationId, clientKey, serverPub,
+        bridges: () => bridges,
+        workspaces: cfg.workspaces,
+        metrics: () => metrics.snapshot(),
+        allowInsecureWs,
+        onReady: (ready) => updates.managementReady(ready.release, ready.generation),
+        onUpdate: (command) => updates.handle(command),
+        onExternalAgentsScan: async () => {
+            bridges = await acp.roster();
+            return bridges;
+        },
+        snapshot: () => ({ channels: supervisor.channelSnapshot(), ...tasks.snapshot(), update: updates.snapshot() }),
+    });
+    const agent = new AgentChannel({ server: cfg.server, agents, bridges: () => bridges, allowInsecureWs });
+    supervisor = new ConnectionSupervisor({
+        management, computer, agent,
+        // Timestamped here rather than inside the supervisor: the daemon owns this log's shape. The
+        // stamp is not decoration -- when the 2026-09-03 outage was diagnosed, the moment the tunnel
+        // died had to be recovered from the log *file's* mtime, because not one line carried a time.
+        log: (message) => console.log(`${new Date().toISOString()} ${message}`),
+    });
+    const stopIdleSweep = startIdleSweep(agents);
+    const shutdown = new AbortController();
+    const stop = () => shutdown.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    try {
+        await supervisor.run(shutdown.signal);
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+        stopIdleSweep();
+        metrics.stop();
+    }
+}

package/dist/workstation/daemonctl.js

@@ -0,0 +1,95 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { clientDir, loadClientConfig } from './config.js';
+import { createServiceManager } from './service/installer.js';
+import { buildServicePath } from './service/types.js';
+import { loginShellPath } from './service/loginShell.js';
+const __filename = fileURLToPath(import.meta.url);
+/**
+ * The package's real npm bin entry (`package.json`'s `bin.axom`), given the directory a compiled
+ * `daemonctl.js` lives in.
+ *
+ * `daemonctl.js` compiles to `dist/workstation/daemonctl.js` (tsconfig: rootDir `src`, outDir
+ * `dist`), so the bin entry `dist/cli.js` is one level *up* from it — a sibling of `dist/`, not a
+ * file inside `dist/workstation/`. This value is embedded verbatim into the generated launchd
+ * plist / systemd unit as the program the OS service execs; see launchd.ts and systemd.ts.
+ */
+export function resolveCliPath(daemonctlDir) {
+    return path.join(daemonctlDir, '..', 'cli.js');
+}
+/**
+ * The package's real npm bin entry, resolved exactly once from this module's own compiled
+ * location — never re-derived by a caller from its *own* `import.meta.url`. `resolveCliPath`'s
+ * contract ("give me the directory a compiled `daemonctl.js` lives in") is easy to satisfy with
+ * the wrong directory: a caller compiled to a different depth under `dist/` (a new command file,
+ * say) can pass its own directory and get a path that still looks plausible — same shape of bug
+ * already caught once for real, in `cliPath` (commit `1bd7f38dc`). Every caller that just wants
+ * "the CLI's own bin path" should import this constant instead of calling `resolveCliPath` itself.
+ */
+export const CLI_PATH = resolveCliPath(path.dirname(__filename));
+/** Build the service context from the installed client, never from a caller-provided shell string. */
+export function serviceContext() {
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+        throw new Error('Axomwork Workstation user service supervision is supported only on macOS and Linux.');
+    }
+    const directory = path.dirname(__filename);
+    const nodeDirectory = path.dirname(process.execPath);
+    return {
+        platform: process.platform,
+        username: os.userInfo().username,
+        userId: process.getuid?.() ?? os.userInfo().uid,
+        homeDir: os.homedir(),
+        nodePath: process.execPath,
+        cliPath: CLI_PATH,
+        npmPath: process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(nodeDirectory, 'npm'),
+        // dist/workstation/ is nested under lib/node_modules/@platless/axom-cli; climb to npm's prefix.
+        npmPrefix: process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(directory, '../../../../../..'),
+        configDir: clientDir(),
+        pathEnv: buildServicePath(process.env.PATH, nodeDirectory),
+    };
+}
+const defaultDeps = {
+    service: (context) => createServiceManager(context ?? serviceContext()),
+    config: () => loadClientConfig(clientDir()),
+};
+/**
+ * User services own the daemon lifecycle. Deliberately no PID-file fallback remains: a stale
+ * PID can describe an unrelated process and cannot survive a reboot reliably.
+ */
+export function createDaemonController(overrides = {}) {
+    const deps = { ...defaultDeps, ...overrides };
+    return {
+        async install() {
+            // The definition is written from the login shell's PATH when one can be had, unioned with
+            // this process's own. In a terminal the two are the same; when the daemon re-provisions
+            // itself after an update they are not, and only the login shell knows where the user's CLIs
+            // are — see loginShellPath for why reusing the service's own PATH would make a machine
+            // reinstall its own blind spot.
+            const shellPath = await loginShellPath();
+            const base = serviceContext();
+            const context = shellPath
+                ? { ...base, pathEnv: buildServicePath(`${shellPath}:${process.env.PATH ?? ''}`, path.dirname(base.nodePath)) }
+                : base;
+            await deps.service(context).install({ interactive: true });
+        },
+        async uninstall() { await deps.service().uninstall(); },
+        async start() { await deps.service().start(); },
+        async stop() { await deps.service().stop(); },
+        async restart() { await deps.service().restart(); },
+        async status() {
+            const state = await deps.service().status();
+            if (!state.running)
+                return { running: false };
+            const config = await deps.config().catch(() => null);
+            return { running: true, server: config?.server, workstationId: config?.workstationId };
+        },
+    };
+}
+const controller = createDaemonController();
+export const install = () => controller.install();
+export const uninstall = () => controller.uninstall();
+export const start = () => controller.start();
+export const stop = () => controller.stop();
+export const restart = () => controller.restart();
+export const status = () => controller.status();

package/dist/workstation/exec.js

@@ -0,0 +1,112 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+const MAX_BYTES = 65536;
+export function runExec(req, onOutput, signal) {
+    const running = startExec(req, onOutput);
+    const onAbort = () => { void running.cancel(); };
+    if (signal?.aborted)
+        onAbort();
+    else
+        signal?.addEventListener('abort', onAbort, { once: true });
+    void running.result.finally(() => signal?.removeEventListener('abort', onAbort));
+    return running.result;
+}
+/** Starts an exec in its own process group and exposes the same cancellation used by force update. */
+export function startExec(req, onOutput) {
+    let cancel = async () => { };
+    const result = new Promise((resolve) => {
+        const env = { ...process.env, ...req.env };
+        if (req.pathPrepend.length > 0) {
+            env.PATH = [...req.pathPrepend, env.PATH ?? ''].filter(Boolean).join(path.delimiter);
+        }
+        // macOS and Linux create a new session/process group for a detached child. Every command it
+        // launches (pipelines and background jobs included) stays in that group, so cancellation does
+        // not leave descendants running after the shell parent is gone.
+        const child = spawn(req.shell, ['-lc', req.command], { cwd: req.cwd, env, detached: process.platform !== 'win32' });
+        let stdout = '';
+        let stderr = '';
+        let truncated = false;
+        let timedOut = false;
+        let cancelled = false;
+        let settled = false;
+        const capture = (buf, stream) => {
+            const text = buf.toString();
+            if (req.streaming && onOutput)
+                onOutput(stream, text);
+            if (stream === 'stdout') {
+                if (stdout.length >= MAX_BYTES) {
+                    truncated = true;
+                    return;
+                }
+                if (stdout.length + text.length > MAX_BYTES) {
+                    stdout += text.slice(0, MAX_BYTES - stdout.length);
+                    truncated = true;
+                }
+                else {
+                    stdout += text;
+                }
+            }
+            else {
+                if (stderr.length >= MAX_BYTES) {
+                    truncated = true;
+                    return;
+                }
+                if (stderr.length + text.length > MAX_BYTES) {
+                    stderr += text.slice(0, MAX_BYTES - stderr.length);
+                    truncated = true;
+                }
+                else {
+                    stderr += text;
+                }
+            }
+        };
+        child.stdout.on('data', (b) => capture(b, 'stdout'));
+        child.stderr.on('data', (b) => capture(b, 'stderr'));
+        const terminateCommandGroup = () => {
+            if (child.pid && process.platform !== 'win32') {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                    return;
+                }
+                catch {
+                    // The group may have already exited between pid observation and signal delivery.
+                }
+            }
+            child.kill('SIGKILL');
+        };
+        let timer;
+        if (req.timeoutSeconds && req.timeoutSeconds > 0) {
+            timer = setTimeout(() => { timedOut = true; terminateCommandGroup(); }, req.timeoutSeconds * 1000);
+        }
+        const abort = () => { cancelled = true; terminateCommandGroup(); };
+        cancel = async () => { abort(); };
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({
+                t: 'exec_exit', id: req.id,
+                exitCode: timedOut || cancelled ? null : code,
+                stdout, stderr, timedOut, truncated,
+            });
+        });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({
+                t: 'exec_exit', id: req.id,
+                exitCode: null,
+                stdout,
+                stderr: stderr + String(err?.message ?? err),
+                timedOut: false,
+                truncated,
+            });
+        });
+    });
+    return { result, cancel: async () => cancel() };
+}