@platless/axom-cli 0.1.0

package/dist/workstation/journal.js

@@ -0,0 +1,257 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/** Default cap for one session's journal. Past this, the oldest half is dropped (see {@link SessionJournal.droppedOldest}). */
+export const DEFAULT_JOURNAL_MAX_BYTES = 64 * 1024 * 1024;
+function serializeEntry(entry) {
+    return `${JSON.stringify({ seq: entry.seq, frame: entry.frame })}\n`;
+}
+function parseEntry(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed?.seq !== 'number' || !Number.isFinite(parsed.seq))
+            return null;
+        if (typeof parsed.frame !== 'object' || parsed.frame === null)
+            return null;
+        return { seq: parsed.seq, frame: parsed.frame };
+    }
+    catch {
+        return null;
+    }
+}
+function isEnoent(err) {
+    return err?.code === 'ENOENT';
+}
+/**
+ * Append-only record of everything one external agent session has streamed to the server, plus the
+ * session's seq allocator.
+ *
+ * It exists because the tunnel is not reliable: the websocket can drop mid-turn and the daemon can
+ * restart while the native agent keeps running. Every outbound `agent_event` / `agent_turn_done` is
+ * written here *before* it is sent, so on reconnect the server can say "I have applied through N"
+ * and get everything after N replayed verbatim. The server acks with `agent_event_ack`, which is
+ * what keeps the file from growing without bound in the steady state.
+ *
+ * **Scope of the guarantee: process crash, not power loss.** Writes go through `appendFile` /
+ * `writeFile` with no `fsync`, so an entry that has returned from {@link append} survives the daemon
+ * being killed, but bytes still sitting in the OS page cache can be lost to a kernel panic or a
+ * power cut. That is the right trade for streamed agent output — an fsync per event would dominate
+ * the cost of the event — and the failure mode degrades to the same seq gap a dropped socket causes.
+ *
+ * The seq allocator lives here rather than in the manager for the daemon-restart case: seq must not
+ * restart at 1 when the process comes back, or the server's `seq > bridgeSeq` de-duplication would
+ * silently swallow the whole next turn. {@link init} recovers the high-water mark from disk *and*
+ * takes the reopening server's watermark as a floor (the file can be empty precisely because
+ * everything in it was acked), and {@link nextSeq} continues from there.
+ *
+ * File layout: `<dir>/<sessionRef>.jsonl`, one `{seq, frame}` JSON object per line. `dir` is the
+ * directory that *directly* holds the files — `AgentSessionManager` passes its `sessionsDir`
+ * (`<journalDir>/sessions`). The file is created on the first {@link append}, not by {@link init},
+ * so a session that opens and is abandoned before producing anything leaves nothing behind.
+ *
+ * Every public method is serialized on an internal queue: a rewrite (ack truncation, overflow drop)
+ * must never interleave with an append, and callers hand work in from unordered bridge callbacks.
+ */
+export class SessionJournal {
+    /** Absolute path of the `.jsonl`. Exposed for logging and tests; nothing else should read it directly. */
+    filePath;
+    dir;
+    tmpPath;
+    maxBytes;
+    maxSeq = 0;
+    /** Byte size of the file as of the last write; kept in memory so append does not stat every time. */
+    bytes = 0;
+    dropped = false;
+    ready = false;
+    queue = Promise.resolve();
+    constructor(dir, sessionRef, maxBytes = DEFAULT_JOURNAL_MAX_BYTES) {
+        this.dir = dir;
+        // sessionRefs are server-supplied strings, not filenames: percent-encoding keeps '/' and '..'
+        // from steering the write out of the journal directory, and keeps the mapping reversible.
+        this.filePath = path.join(dir, `${encodeURIComponent(sessionRef)}.jsonl`);
+        this.tmpPath = `${this.filePath}.tmp`;
+        this.maxBytes = maxBytes;
+    }
+    /** True once an overflow has discarded entries. The manager turns this into a visible gap notice on resume. */
+    get droppedOldest() {
+        return this.dropped;
+    }
+    /** Highest seq ever handed out or recovered. `0` means nothing has been journaled for this session. */
+    get lastSeq() {
+        return this.maxSeq;
+    }
+    /**
+     * Creates the journal directory and recovers `maxSeq` (and the byte size) from any existing file.
+     * Must be awaited before {@link nextSeq} / {@link append}; both throw otherwise, because a missed
+     * init would restart seq at 1 and desynchronize the server's watermark.
+     *
+     * `resumeFromSeq` is the server's watermark from the `agent_open` that is (re)creating this
+     * session, and it is a **floor** under the recovered value — never a ceiling. The file alone is
+     * not a sufficient source for the allocator: acked entries are truncated away, so between turns
+     * the journal is legitimately empty. A daemon restart in that window recovers `maxSeq = 0` while
+     * the server is still at N, `nextSeq()` starts back at 1, and every event the session produces
+     * from then on is `<= lastSeenSeq` on the server — silently swallowed, no error, no recovery
+     * path, the run hangs forever. Seeding from the watermark closes that hole without asking the
+     * server to lower anything (its watermark is advance-only at the storage layer, deliberately).
+     *
+     * A trailing line torn by a crash mid-append is dropped and the file rewritten, so a later append
+     * cannot glue new bytes onto half a record.
+     */
+    async init(resumeFromSeq = 0) {
+        await this.serialize(async () => {
+            await fs.mkdir(this.dir, { recursive: true });
+            const { entries, bytes, clean } = await this.readEntries();
+            const recovered = entries.reduce((max, entry) => Math.max(max, entry.seq), 0);
+            this.maxSeq = Math.max(recovered, resumeFromSeq);
+            this.bytes = clean ? bytes : await this.rewrite(entries);
+            this.ready = true;
+        });
+    }
+    /** Next seq for this session. Synchronous by design: bridge callbacks must number events in arrival order. */
+    nextSeq() {
+        this.requireReady();
+        this.maxSeq += 1;
+        return this.maxSeq;
+    }
+    /** Writes the entry to disk. Resolves only once the bytes are handed to the OS — callers send after this. */
+    async append(entry) {
+        await this.serialize(async () => {
+            this.requireReady();
+            const line = serializeEntry(entry);
+            const size = Buffer.byteLength(line);
+            if (this.bytes + size > this.maxBytes)
+                await this.dropOldestHalf(size);
+            await fs.appendFile(this.filePath, line);
+            this.bytes += size;
+            if (entry.seq > this.maxSeq)
+                this.maxSeq = entry.seq;
+        });
+    }
+    /**
+     * Everything the server has not applied yet, in append order. `seq` is the server's watermark.
+     *
+     * This is the one method that parses the whole file, so it is O(file) in both time and peak
+     * memory. That is affordable only because it runs on the reconnect path — once per `agent_open` —
+     * and never on the append path. Keep it that way.
+     */
+    async entriesAfter(seq) {
+        return this.serialize(async () => {
+            const { entries } = await this.readEntries();
+            return entries.filter((entry) => entry.seq > seq);
+        });
+    }
+    /**
+     * Forgets everything the server has acknowledged (`seq <= throughSeq`) by rewriting the file.
+     * `maxSeq` is deliberately untouched: acking is not a reason to reissue seqs.
+     */
+    async truncateThrough(seq) {
+        await this.serialize(async () => {
+            if (seq <= 0)
+                return;
+            const { entries } = await this.readEntries();
+            const kept = entries.filter((entry) => entry.seq > seq);
+            if (kept.length === entries.length)
+                return; // nothing acked that we still hold; don't churn the file
+            this.bytes = await this.rewrite(kept);
+        });
+    }
+    /** Removes the file for good (agent_close). The journal is unusable afterwards. */
+    async destroy() {
+        await this.serialize(async () => {
+            await fs.rm(this.filePath, { force: true });
+            await fs.rm(this.tmpPath, { force: true });
+            this.bytes = 0;
+            this.ready = false;
+        });
+    }
+    // --- internals (never call from inside another serialized op except via the private helpers) ---
+    requireReady() {
+        if (!this.ready) {
+            throw new Error(`SessionJournal ${this.filePath} used before init() (or after destroy())`);
+        }
+    }
+    /**
+     * Chains `op` after whatever is already queued — including a failed predecessor, so one bad write
+     * does not wedge the session forever.
+     */
+    serialize(op) {
+        const run = this.queue.then(op, op);
+        this.queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** `clean: false` means at least one line failed to parse and the file should be rewritten. */
+    async readEntries() {
+        let text;
+        try {
+            text = await fs.readFile(this.filePath, 'utf8');
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return { entries: [], bytes: 0, clean: true };
+            throw err;
+        }
+        const entries = [];
+        let clean = true;
+        for (const line of text.split('\n')) {
+            if (line.length === 0)
+                continue;
+            const entry = parseEntry(line);
+            if (entry)
+                entries.push(entry);
+            else
+                clean = false;
+        }
+        return { entries, bytes: Buffer.byteLength(text), clean };
+    }
+    /** Replaces the file with exactly `entries`, atomically. Returns the new byte size. */
+    async rewrite(entries) {
+        return this.rewriteRaw(Buffer.from(entries.map(serializeEntry).join('')));
+    }
+    /** Replaces the file with `data`, atomically. Returns the new byte size. */
+    async rewriteRaw(data) {
+        await fs.writeFile(this.tmpPath, data);
+        await fs.rename(this.tmpPath, this.filePath);
+        return data.length;
+    }
+    /**
+     * Makes room for `incoming` bytes by discarding the oldest half, repeating until it fits. Dropping
+     * the *oldest* is the only safe direction: the newest output is what the user is watching, and the
+     * server can be told about the hole (a synthetic gap event) but cannot invent the missing bytes.
+     *
+     * This runs on the **append path**, so it deliberately never parses or re-serializes a record. It
+     * reads the file once as raw bytes, walks to a newline boundary past the half-way mark, and writes
+     * back a slice of that same buffer. At the 64MB cap that is one 64MB read plus one ≤32MB write —
+     * versus the several-hundred-MB transient and multi-second single-threaded stall an entry-level
+     * round-trip would cost, on a daemon that is also serving `exec_request` on the same loop.
+     *
+     * Halving by *bytes* rather than by record count is the same policy in a cheaper coordinate: the
+     * point is to reclaim about half the file in one pass so the trim is amortized over many appends.
+     */
+    async dropOldestHalf(incoming) {
+        let buf;
+        try {
+            buf = await fs.readFile(this.filePath);
+        }
+        catch (err) {
+            if (isEnoent(err)) {
+                this.bytes = 0; // tracked size was stale; nothing on disk to drop
+                return;
+            }
+            throw err;
+        }
+        let start = 0;
+        while (start < buf.length && buf.length - start + incoming > this.maxBytes) {
+            // Cut at the first record boundary at or after the half-way point of what is left. Every line
+            // ends in '\n', so the newline search can only land on a real boundary; if there is none left
+            // the remainder is a single oversized record and we drop all of it.
+            const half = start + Math.ceil((buf.length - start) / 2);
+            const newline = buf.indexOf(0x0a, half);
+            start = newline === -1 ? buf.length : newline + 1;
+        }
+        // Nothing to drop means a single record larger than the whole cap; write it anyway rather than
+        // lose it, and let the next append trim back down.
+        if (start === 0)
+            return;
+        this.dropped = true;
+        this.bytes = await this.rewriteRaw(buf.subarray(start));
+    }
+}

package/dist/workstation/names.js

@@ -0,0 +1,17 @@
+/** Sanitize a raw string to the workstation/workspace name charset `[A-Za-z0-9._-]`.
+ *  Non-matching chars → '-'. Empty / '.' / '..' → fallback. */
+export function sanitizeName(raw, fallback) {
+    const cleaned = (raw ?? '').replace(/[^A-Za-z0-9._-]/g, '-');
+    if (cleaned === '' || cleaned === '.' || cleaned === '..')
+        return fallback;
+    return cleaned;
+}
+/**
+ * Picks the workstation's registered name: an explicit `--name` flag, then `AXOM_WORKSTATION_NAME`
+ * (a blank value in either counts as unset), then the host name — sanitized by `sanitizeName`,
+ * which alone owns the character-set and empty/dot handling.
+ */
+export function resolveWorkstationName(flag, env, host) {
+    const fromEnv = env.AXOM_WORKSTATION_NAME?.trim() || undefined;
+    return sanitizeName(flag?.trim() || fromEnv || host, 'client');
+}

package/dist/workstation/oauth/browser.js

@@ -0,0 +1,24 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+/**
+ * Opens the authorization page when this host has a graphical session. The caller always prints
+ * the URL first, so a missing opener (or a failed opener) is never an authorization blocker.
+ */
+export function tryOpenAuthorizationUrl(url, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const env = deps.env ?? process.env;
+    const command = platform === 'darwin'
+        ? 'open'
+        : platform === 'linux' && (env.DISPLAY || env.WAYLAND_DISPLAY)
+            ? 'xdg-open'
+            : undefined;
+    if (!command)
+        return;
+    try {
+        const child = (deps.spawn ?? nodeSpawn)(command, [url], { stdio: 'ignore', detached: true });
+        child.once?.('error', () => undefined);
+        child.unref?.();
+    }
+    catch {
+        // The URL was already printed. Browser launch is a convenience only.
+    }
+}

package/dist/workstation/oauth/deviceAuthorization.js

@@ -0,0 +1,198 @@
+import WebSocket from 'ws';
+import { RetryPolicy } from '../connection/retryPolicy.js';
+import { tryOpenAuthorizationUrl } from './browser.js';
+import { loadDeviceId } from '../../config.js';
+export const DEVICE_CODE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+export class DeviceAuthorizationError extends Error {
+}
+const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+function normalizedServer(server) {
+    const normalized = server.trim().replace(/\/+$/, '');
+    if (!normalized)
+        throw new DeviceAuthorizationError('Axomwork server URL is required');
+    try {
+        new URL(normalized);
+    }
+    catch {
+        throw new DeviceAuthorizationError('Axomwork server URL is invalid');
+    }
+    return normalized;
+}
+async function requestJson(fetch_, url, init, acceptedStatus, description) {
+    let response;
+    try {
+        response = await fetch_(url, init);
+    }
+    catch (error) {
+        throw new DeviceAuthorizationError(`Failed to reach ${url.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (response.status !== acceptedStatus)
+        throw new DeviceAuthorizationError(`${description} failed: ${response.status}`);
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new DeviceAuthorizationError(`${description} returned invalid JSON`);
+    }
+}
+function requireString(value, field, description) {
+    if (typeof value !== 'string' || !value)
+        throw new DeviceAuthorizationError(`${description} missing ${field}`);
+    return value;
+}
+function websocketUrl(server) {
+    const url = new URL('/oauth/device/ws', server);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return url.toString();
+}
+function readStatus(data) {
+    try {
+        const parsed = JSON.parse(typeof data === 'string' ? data : String(data));
+        return parsed.status === 'pending' || parsed.status === 'approved' || parsed.status === 'denied' || parsed.status === 'expired'
+            ? parsed.status
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function waitForNotification(socket, sessionId, notificationTicket, deadline, now, onOpen) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => finish('expired'), Math.max(0, deadline - now()));
+        const finish = (status) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (status !== 'reconnect')
+                socket.close();
+            resolve(status);
+        };
+        socket.on('open', () => {
+            onOpen();
+            try {
+                socket.send(JSON.stringify({ session_id: sessionId, notification_ticket: notificationTicket }));
+            }
+            catch {
+                finish('reconnect');
+            }
+        });
+        socket.on('message', (data) => {
+            const status = readStatus(data);
+            if (status && status !== 'pending')
+                finish(status);
+        });
+        socket.on('close', () => finish('reconnect'));
+        socket.on('error', () => finish('reconnect'));
+    });
+}
+async function exchangeDeviceCode(server, clientId, deviceCode, fetch_) {
+    const response = await requestJson(fetch_, new URL('/oauth/token', server), {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: DEVICE_CODE_GRANT_TYPE,
+            client_id: clientId,
+            device_code: deviceCode,
+            device_id: await loadDeviceId(),
+        }),
+    }, 200, 'Device token exchange');
+    const accessToken = requireString(response.access_token, 'access_token', 'Device token response');
+    const refreshToken = requireString(response.refresh_token, 'refresh_token', 'Device token response');
+    if (!Number.isFinite(response.expires_in) || response.expires_in <= 0) {
+        throw new DeviceAuthorizationError('Device token response has invalid expires_in');
+    }
+    return { accessToken, refreshToken, expiresInSeconds: response.expires_in };
+}
+async function pollDeviceCode(server, clientId, deviceCode, fetch_) {
+    const response = await fetch_(new URL('/oauth/token', server), {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: DEVICE_CODE_GRANT_TYPE,
+            client_id: clientId,
+            device_code: deviceCode,
+            device_id: await loadDeviceId(),
+        }),
+    });
+    if (response.status === 400) {
+        const body = await response.json().catch(() => ({}));
+        if (body.error === 'authorization_pending' || body.error === 'slow_down')
+            return undefined;
+        if (body.error === 'access_denied')
+            throw new DeviceAuthorizationError('Device authorization was denied');
+        if (body.error === 'expired_token')
+            throw new DeviceAuthorizationError('Device authorization expired');
+    }
+    if (response.status !== 200)
+        throw new DeviceAuthorizationError(`Device token polling failed: ${response.status}`);
+    const token = await response.json();
+    return {
+        accessToken: requireString(token.access_token, 'access_token', 'Device token response'),
+        refreshToken: requireString(token.refresh_token, 'refresh_token', 'Device token response'),
+        expiresInSeconds: token.expires_in,
+    };
+}
+/**
+ * Uses OAuth Device Authorization for both desktop and headless clients. The notification socket
+ * only carries state; the tokens exist only in this call's return value.
+ */
+export async function authorizeDevice(server, clientName, hostname, deps = {}) {
+    const baseUrl = normalizedServer(server);
+    const fetch_ = deps.fetch ?? globalThis.fetch;
+    const print = deps.print ?? console.log;
+    const openBrowser = deps.openBrowser ?? tryOpenAuthorizationUrl;
+    const createWebSocket = deps.createWebSocket ?? ((url) => new WebSocket(url));
+    const now = deps.now ?? Date.now;
+    const wait = deps.sleep ?? sleep;
+    void clientName;
+    const clientId = 'axom-cli';
+    const authorization = await requestJson(fetch_, new URL('/oauth/device_authorization', baseUrl), {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ client_id: clientId, hostname }),
+    }, 200, 'Device authorization request');
+    const deviceCode = requireString(authorization.device_code, 'device_code', 'Device authorization response');
+    const verificationUrl = requireString(authorization.verification_uri_complete, 'verification_uri_complete', 'Device authorization response');
+    const sessionId = requireString(authorization.session_id, 'session_id', 'Device authorization response');
+    const notificationTicket = requireString(authorization.notification_ticket, 'notification_ticket', 'Device authorization response');
+    if (!Number.isFinite(authorization.expires_in) || authorization.expires_in <= 0) {
+        throw new DeviceAuthorizationError('Device authorization response has invalid expires_in');
+    }
+    print(`Open this URL to authorize: ${verificationUrl}`);
+    openBrowser(verificationUrl);
+    const deadline = now() + authorization.expires_in * 1_000;
+    const retry = new RetryPolicy();
+    while (now() < deadline) {
+        let socket;
+        try {
+            socket = createWebSocket(websocketUrl(baseUrl));
+        }
+        catch {
+            const delay = Math.min(retry.recordFailure(), Math.max(0, deadline - now()));
+            if (delay === 0)
+                break;
+            await wait(delay);
+            continue;
+        }
+        const status = await waitForNotification(socket, sessionId, notificationTicket, deadline, now, () => retry.recordSuccess());
+        if (status === 'approved') {
+            const tokens = await exchangeDeviceCode(baseUrl, clientId, deviceCode, fetch_);
+            return { clientId, ...tokens };
+        }
+        if (status === 'denied')
+            throw new DeviceAuthorizationError('Device authorization was denied');
+        if (status === 'expired')
+            break;
+        const polled = await pollDeviceCode(baseUrl, clientId, deviceCode, fetch_);
+        if (polled)
+            return { clientId, ...polled };
+        const pollingFloor = Math.max(1, authorization.interval ?? 5) * 1_000;
+        const delay = Math.min(Math.max(retry.recordFailure(), pollingFloor), Math.max(0, deadline - now()));
+        if (delay === 0)
+            break;
+        await wait(delay);
+    }
+    throw new DeviceAuthorizationError('Device authorization expired');
+}

package/dist/workstation/osinfo.js

@@ -0,0 +1,4 @@
+import os from 'node:os';
+export function osInfo() {
+    return { name: os.type(), version: os.release(), arch: os.arch(), hostname: os.hostname() };
+}