dexterm-cli 0.2.0 → 0.2.1

package/dist/packages/cli/src/overlay/server.js

@@ -0,0 +1,170 @@
+// dexterm — STREAMER OVERLAY page server (task-1427). Serves the OBS browser-source scenes on loopback with the
+// popup host's security model (packages/popup/src/server.ts):
+//   * listens on 127.0.0.1 only (a random port unless --port), never 0.0.0.0 / ::; the remote must be loopback;
+//   * a scene URL carries a single-use TICKET (32 random bytes). OBS needs time to be pasted into, so its TTL is
+//     longer than a popup's (10 min by default) — but it still buys exactly one page load;
+//   * the page embeds a single-use WS TOKEN (30 s) accepted once for the WebSocket upgrade;
+//   * strict Host check on every request (DNS-rebind guard), strict Origin check on the upgrade; no CORS header is
+//     ever set; anything unknown or unauthorised gets an empty 404 and is reported as a probe;
+//   * the page's JS/CSS are inlined under a per-page nonce CSP: no remote content, no eval, no inline handlers;
+//     the only images are the PnL card PNG the socket delivers as a data: URL;
+//   * the socket is OUTBOUND ONLY: the server never parses what a page sends. Every inbound text frame is counted
+//     as dropped and ignored (pings are answered by the framing layer). There is no inbound control path: the
+//     server is constructed with nothing it could control, it only pushes view models it is handed.
+import http from 'node:http';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { WsConn } from '../../../agents/src/index.js';
+import { OVERLAY_SCENES } from "./model.js";
+import { renderOverlayPage, OVERLAY_THEMES } from "./page.js";
+export const OVERLAY_PAGES = [...OVERLAY_SCENES, 'all'];
+export const OVERLAY_TICKET_TTL_MS = 10 * 60_000;
+const WS_TOKEN_TTL_MS = 30_000;
+const LOOPBACK = new Set(['127.0.0.1', '::ffff:127.0.0.1', '::1']);
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+function safeEq(a, b) {
+    const ba = Buffer.from(a), bb = Buffer.from(b);
+    return ba.length === bb.length && timingSafeEqual(ba, bb);
+}
+const sanitize = (s, n = 80) => String(s ?? '').replace(/[^\x20-\x7e]/g, '?').slice(0, n);
+export async function createOverlayServer(opts = {}) {
+    const onEvent = opts.onEvent ?? (() => { });
+    const now = opts.now ?? (() => Date.now());
+    const ttl = Math.max(1000, opts.ticketTtlMs ?? OVERLAY_TICKET_TTL_MS);
+    const tickets = new Map();
+    const wsTokens = new Map();
+    const viewers = new Set();
+    const latest = new Map();
+    let dropped = 0;
+    let port = 0;
+    const probe = (req, reason) => onEvent({ ev: 'probe.rejected', reason, method: req.method ?? '', path: sanitize((req.url ?? '').replace(/([?&](p|t)=)[^&]*/g, '$1…')) });
+    const reject = (req, res, reason) => {
+        probe(req, reason);
+        res.writeHead(404, { 'content-length': '0', 'cache-control': 'no-store' });
+        res.end();
+    };
+    const baseChecks = (req) => {
+        if (!LOOPBACK.has(req.socket.remoteAddress ?? ''))
+            return 'remote-not-loopback';
+        if (req.headers.host !== `127.0.0.1:${port}`)
+            return 'bad-host';
+        return null;
+    };
+    const sweep = () => {
+        const t = now();
+        for (const [k, v] of tickets)
+            if (v.exp < t)
+                tickets.delete(k);
+        for (const [k, v] of wsTokens)
+            if (v.exp < t)
+                wsTokens.delete(k);
+    };
+    const server = http.createServer((req, res) => {
+        const bad = baseChecks(req);
+        if (bad)
+            return reject(req, res, bad);
+        const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+        if (req.method === 'GET' && url.pathname.startsWith('/overlay/')) {
+            sweep();
+            const page = url.pathname.slice('/overlay/'.length);
+            const p = url.searchParams.get('p') ?? '';
+            const key = [...tickets.keys()].find((k) => safeEq(k, p));
+            const t = key ? tickets.get(key) : undefined;
+            if (!key || !t || t.exp < now() || t.page !== page || !OVERLAY_PAGES.includes(page))
+                return reject(req, res, 'bad-ticket');
+            tickets.delete(key); // single use: a reload or a copied URL is refused
+            const wsToken = randomBytes(32).toString('base64url');
+            wsTokens.set(wsToken, { page, exp: now() + WS_TOKEN_TTL_MS });
+            const nonce = randomBytes(16).toString('base64url');
+            const html = renderOverlayPage({ page, theme: t.theme, nonce, wsUrl: `ws://127.0.0.1:${port}/ws?t=${wsToken}` });
+            res.writeHead(200, {
+                'content-type': 'text/html; charset=utf-8',
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+                'x-content-type-options': 'nosniff',
+                'cross-origin-opener-policy': 'same-origin',
+                'cross-origin-resource-policy': 'same-origin',
+                'permissions-policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
+                'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src ws://127.0.0.1:${port}; img-src data:; font-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; object-src 'none'`,
+            });
+            onEvent({ ev: 'page.served', page });
+            return res.end(html);
+        }
+        return reject(req, res, 'unknown-route');
+    });
+    server.on('upgrade', (req, socket) => {
+        const fail = (reason) => {
+            probe(req, reason);
+            try {
+                socket.write('HTTP/1.1 404 Not Found\r\ncontent-length: 0\r\nconnection: close\r\n\r\n');
+            }
+            catch { /* gone */ }
+            socket.destroy();
+        };
+        const bad = baseChecks(req);
+        if (bad)
+            return fail(bad);
+        if (req.headers.origin !== `http://127.0.0.1:${port}`)
+            return fail('bad-origin');
+        const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+        if (url.pathname !== '/ws')
+            return fail('unknown-route');
+        sweep();
+        const tok = url.searchParams.get('t') ?? '';
+        const key = [...wsTokens.keys()].find((k) => safeEq(k, tok));
+        const entry = key ? wsTokens.get(key) : undefined;
+        if (!key || !entry || entry.exp < now())
+            return fail('bad-ws-token');
+        wsTokens.delete(key);
+        if (String(req.headers['sec-websocket-version']) !== '13' || !req.headers['sec-websocket-key'])
+            return fail('bad-ws-handshake');
+        const accept = createHash('sha1').update(req.headers['sec-websocket-key'] + WS_GUID).digest('base64');
+        socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+        const viewer = { page: entry.page, conn: new WsConn(socket, req.socket.remoteAddress ?? '') };
+        // Outbound only: whatever a page sends is never parsed, never forwarded, never acted on.
+        viewer.conn.onMessage = () => { dropped++; onEvent({ ev: 'viewer.dropped', page: viewer.page }); };
+        viewer.conn.onClose = () => { viewers.delete(viewer); onEvent({ ev: 'viewer.closed', page: viewer.page }); };
+        viewers.add(viewer);
+        onEvent({ ev: 'viewer.connected', page: viewer.page });
+        viewer.conn.send({ type: 'hello', protocol: 'dexterm-overlay/1', page: viewer.page });
+        for (const [scene, view] of latest)
+            if (viewer.page === 'all' || viewer.page === scene)
+                viewer.conn.send({ type: 'view', scene, view });
+    });
+    server.headersTimeout = 5000;
+    server.requestTimeout = 10_000;
+    server.keepAliveTimeout = 5000;
+    server.maxHeadersCount = 40;
+    await new Promise((resolve, rejectListen) => {
+        server.once('error', rejectListen);
+        server.listen(opts.port ?? 0, '127.0.0.1', () => { server.off('error', rejectListen); resolve(); });
+    });
+    port = server.address().port;
+    return {
+        port,
+        origin: `http://127.0.0.1:${port}`,
+        issueTicket(page, theme = 'cyberspace') {
+            if (!OVERLAY_PAGES.includes(page))
+                throw new Error(`unknown overlay scene ${JSON.stringify(page)} (one of ${OVERLAY_PAGES.join(', ')})`);
+            if (!(theme in OVERLAY_THEMES))
+                throw new Error(`unknown overlay theme ${JSON.stringify(theme)} (one of ${Object.keys(OVERLAY_THEMES).join(', ')})`);
+            sweep();
+            const ticket = randomBytes(32).toString('base64url');
+            tickets.set(ticket, { page, theme, exp: now() + ttl });
+            return `http://127.0.0.1:${port}/overlay/${page}?p=${ticket}`;
+        },
+        push(scene, view) {
+            latest.set(scene, view);
+            for (const v of viewers)
+                if (v.page === 'all' || v.page === scene)
+                    v.conn.send({ type: 'view', scene, view });
+        },
+        get viewers() { return viewers.size; },
+        get dropped() { return dropped; },
+        close() {
+            for (const v of [...viewers])
+                v.conn.close(1001);
+            viewers.clear();
+            return new Promise((r) => server.close(() => r()));
+        },
+    };
+}

package/dist/packages/cli/src/overlay-cmd.js

@@ -0,0 +1,367 @@
+// `dexterm overlay` — the STREAMER OVERLAY (task-1427): OBS browser-source scenes fed by the spectator stream.
+//
+//   dexterm overlay [--scene activity|coin|pnl|all]… [--theme cyberspace|ice|neon]
+//                   [--replay FILE [--speed N] [--loop]] [--ledger TRADE_ID [--sol-usd N]]
+//                   [--port N] [--ticket-ttl MIN] [--json]
+//
+// Data: the live, read-only, redacted spectator stream (the one `dexterm --spectate-mcp` or `dexterm agent serve
+// --spectate` opens; found through spectator.json, token sent in the hello, loopback only), or a saved recording
+// with --replay (every scene then carries a SAMPLE DATA tag). The PnL scene is the agent's PAPER fills on the coin
+// (stamped PAPER), or with --ledger one round trip of the user's own trade ledger (PAPER or LIVE by wallet mode).
+// Scenes: a loopback page per scene with a single-use ticket → token (overlay/server.ts). No network beyond
+// loopback, no inbound control path: the overlay watches; nothing here can arm, sign, size, trade or raise a cap.
+import { readFileSync } from 'node:fs';
+import { loadSpectatorRecording, sanitizeDetail } from '../../agents/src/index.js';
+import { spectatorInfoPath } from "./spectate-cmd.js";
+import { emptyOverlayState, foldOverlay, activityView, coinView } from "./overlay/model.js";
+import { pnlView, ledgerOverlayInput } from "./overlay/pnl.js";
+import { createOverlayServer, OVERLAY_PAGES, OVERLAY_TICKET_TTL_MS } from "./overlay/server.js";
+import { OVERLAY_THEME_NAMES } from "./overlay/page.js";
+export const OVERLAY_USAGE = `dexterm overlay [options]   streamer overlay: OBS browser-source scenes of the agent's session
+  --scene NAME        activity | coin | pnl | all (repeatable; default: the three scenes)
+  --theme NAME        ${OVERLAY_THEME_NAMES.join(' | ')} (default cyberspace)
+  --replay FILE       play a saved spectator recording instead of the live stream (scenes say SAMPLE DATA)
+  --speed N           replay speed (default 1) · --loop  replay again from the start when it ends
+  --ledger TRADE_ID   PnL scene from your own trade ledger (PAPER or LIVE stamp by wallet mode) instead of the
+                      agent's paper fills · --sol-usd N for a USD-booked trade
+  --port N            fixed loopback port (default random) · --ticket-ttl MIN  minutes a URL stays valid (default 10)
+  --json              print the scene URLs as JSON
+Each URL works ONCE (paste it into an OBS Browser source). Press n for fresh URLs, q to quit.
+Loopback only · read-only · addresses redacted · every scene shows its data age.
+Full docs: https://dexterm.xyz/docs/overlay/`;
+export function parseOverlayArgs(rest) {
+    const o = { scenes: [], theme: 'cyberspace', replay: null, speed: 1, loop: false, ledger: null, solUsd: null, port: undefined, ttlMin: OVERLAY_TICKET_TTL_MS / 60_000, json: false };
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        const val = () => { const v = rest[++i]; return v === undefined || v.startsWith('--') ? null : v; };
+        switch (a) {
+            case '--scene': {
+                const v = val();
+                if (!v || !OVERLAY_PAGES.includes(v))
+                    return `--scene is one of ${OVERLAY_PAGES.join(', ')}`;
+                if (!o.scenes.includes(v))
+                    o.scenes.push(v);
+                break;
+            }
+            case '--theme': {
+                const v = val();
+                if (!v || !OVERLAY_THEME_NAMES.includes(v))
+                    return `--theme is one of ${OVERLAY_THEME_NAMES.join(', ')}`;
+                o.theme = v;
+                break;
+            }
+            case '--replay': {
+                const v = val();
+                if (!v)
+                    return '--replay needs a FILE';
+                o.replay = v;
+                break;
+            }
+            case '--speed': {
+                const n = Number(val());
+                if (!(n > 0 && n <= 100))
+                    return '--speed is a number from 0 to 100';
+                o.speed = n;
+                break;
+            }
+            case '--loop':
+                o.loop = true;
+                break;
+            case '--ledger': {
+                const v = val();
+                if (!v)
+                    return '--ledger needs a TRADE_ID (from `dexterm ledger trades`)';
+                o.ledger = v;
+                break;
+            }
+            case '--sol-usd': {
+                const n = Number(val());
+                if (!(n > 0))
+                    return '--sol-usd is a positive number';
+                o.solUsd = n;
+                break;
+            }
+            case '--port': {
+                const n = Number(val());
+                if (!Number.isInteger(n) || n < 1024 || n > 65535)
+                    return '--port is an integer from 1024 to 65535';
+                o.port = n;
+                break;
+            }
+            case '--ticket-ttl': {
+                const n = Number(val());
+                if (!(n >= 1 && n <= 240))
+                    return '--ticket-ttl is minutes from 1 to 240';
+                o.ttlMin = n;
+                break;
+            }
+            case '--json':
+                o.json = true;
+                break;
+            default: return `unknown option ${JSON.stringify(a)}`;
+        }
+    }
+    if (!o.scenes.length)
+        o.scenes = ['activity', 'coin', 'pnl'];
+    if (o.loop && !o.replay)
+        return '--loop only applies to --replay';
+    return o;
+}
+/**
+ * Folds events into the overlay state and pushes the scene views to the server. Public for the tests (they drive it
+ * with fixture events and a fake clock); the command wires it to the stream or a recording.
+ */
+export class OverlayEngine {
+    state;
+    server;
+    now;
+    pnlInput;
+    pnlEveryMs;
+    lastPnlAt = -Infinity;
+    lastPnlKey = '';
+    constructor(o) {
+        this.state = emptyOverlayState(o.sample);
+        this.server = o.server;
+        this.now = o.now ?? (() => Date.now());
+        this.pnlInput = o.pnlInput;
+        this.pnlEveryMs = o.pnlEveryMs ?? 10_000;
+    }
+    /** Start over (a looped replay): the scenes forget every coin, fill and call. */
+    reset() { Object.assign(this.state, emptyOverlayState(this.state.sample)); }
+    /** Fold one event read off the stream or a recording (untrusted data: the detail is re-validated first). */
+    feed(raw) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return false;
+        const e = raw;
+        if (typeof e.phase !== 'string' || typeof e.t !== 'number' || !Number.isFinite(e.t))
+            return false;
+        // the stream and saved files are redacted (mints are head…tail), so the detail is validated in that shape
+        const ev = { ...e, detail: sanitizeDetail(e.detail, { masked: true }) };
+        foldOverlay(this.state, ev);
+        return true;
+    }
+    /** Push the current views (activity + coin always; the PnL card when its fills changed or it aged). */
+    tick() {
+        const now = this.now();
+        this.server.push('activity', activityView(this.state, now));
+        this.server.push('coin', coinView(this.state, now));
+        const p = this.state.paperCurrent ? this.state.paper.get(this.state.paperCurrent) : undefined;
+        const key = this.pnlInput ? 'ledger' : `${this.state.paperCurrent}:${p?.fills.length ?? 0}:${this.state.coins.get(this.state.paperCurrent ?? '')?.priceUsd?.at ?? 0}`;
+        if (key !== this.lastPnlKey || now - this.lastPnlAt >= this.pnlEveryMs) {
+            this.lastPnlKey = key;
+            this.lastPnlAt = now;
+            let input = null;
+            let note = null;
+            if (this.pnlInput) {
+                try {
+                    input = this.pnlInput();
+                }
+                catch (err) {
+                    note = err.message;
+                }
+            }
+            const view = pnlView(this.state, now, input);
+            this.server.push('pnl', note ? { ...view, note } : view);
+        }
+    }
+}
+function ledgerLoader(io, tradeId, solUsd) {
+    let row = null;
+    let problem = 'reading the trade ledger…';
+    return {
+        async load() {
+            try {
+                const at = await import('../../autotrade/src/index.js');
+                const v = await at.loadLedgerView({ env: io.env, now: Date.now() });
+                const t = v.trades.find((x) => x.tradeId === tradeId);
+                if (!t) {
+                    row = null;
+                    problem = `no trade ${tradeId} in the trade ledger`;
+                    return;
+                }
+                row = t;
+                problem = null;
+            }
+            catch (e) {
+                row = null;
+                problem = `trade ledger: ${e.message}`;
+            }
+        },
+        input() {
+            if (!row)
+                throw new Error(problem ?? 'no ledger trade');
+            return ledgerOverlayInput(row, solUsd ? { usd: solUsd, source: '--sol-usd' } : null);
+        },
+    };
+}
+export async function runOverlay(rest, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    if (rest.includes('--help') || rest.includes('-h')) {
+        out(OVERLAY_USAGE);
+        return 0;
+    }
+    const o = parseOverlayArgs(rest);
+    if (typeof o === 'string') {
+        errOut(`dexterm overlay: ${o}`);
+        errOut(OVERLAY_USAGE);
+        return 2;
+    }
+    let recording = null;
+    if (o.replay) {
+        try {
+            recording = loadSpectatorRecording(o.replay);
+        }
+        catch (e) {
+            errOut(`dexterm overlay: cannot read ${o.replay}: ${e.message}`);
+            return 1;
+        }
+        if (!recording.events.length) {
+            errOut(`dexterm overlay: ${o.replay} has no events`);
+            return 1;
+        }
+    }
+    let server;
+    try {
+        server = await createOverlayServer({
+            port: o.port, ticketTtlMs: o.ttlMin * 60_000,
+            onEvent: (ev) => { if (ev.ev === 'probe.rejected')
+                errOut(`overlay: refused ${ev.method} ${ev.path} (${ev.reason})`); },
+        });
+    }
+    catch (e) {
+        errOut(`dexterm overlay: cannot listen on 127.0.0.1${o.port ? `:${o.port}` : ''}: ${e.message}`);
+        return 1;
+    }
+    const ledger = o.ledger ? ledgerLoader(io, o.ledger, o.solUsd) : null;
+    if (ledger)
+        await ledger.load();
+    const engine = new OverlayEngine({ sample: !!recording, server, ...(ledger ? { pnlInput: () => ledger.input() } : {}) });
+    const printUrls = () => {
+        const urls = o.scenes.map((s) => ({ scene: s, url: server.issueTicket(s, o.theme) }));
+        if (o.json) {
+            out(JSON.stringify({ theme: o.theme, sample: !!recording, ttlMin: o.ttlMin, scenes: urls }));
+            return;
+        }
+        out(`dexterm overlay · theme ${o.theme}${recording ? ' · SAMPLE DATA (replay)' : ''} · each URL works once, for ${o.ttlMin} min`);
+        for (const u of urls)
+            out(`  ${u.scene.padEnd(9)} ${u.url}`);
+    };
+    printUrls();
+    if (!o.json)
+        out(recording ? `replaying ${recording.events.length} event(s) from ${o.replay}` : 'watching the live spectator stream (start one with `dexterm --spectate-mcp` or `dexterm agent serve --spectate`)');
+    const timers = [];
+    let stopped = false;
+    let ws = null;
+    // ---- data source
+    if (recording) {
+        const evs = recording.events;
+        let i = 0;
+        const step = () => {
+            if (stopped)
+                return;
+            if (i >= evs.length) {
+                if (!o.loop)
+                    return;
+                i = 0;
+                engine.reset();
+            }
+            const ev = evs[i];
+            // replayed events are re-timed to the playback clock (a signal's own `at` shifts with them), so their ages
+            // read as "this long ago in the replay"
+            const shift = Date.now() - ev.t;
+            const flags = ev.detail?.liveFlags;
+            engine.feed({ ...ev, t: ev.t + shift, ...(flags ? { detail: { ...ev.detail, liveFlags: flags.map((f) => ({ ...f, at: (typeof f.at === 'number' ? f.at : ev.t) + shift })) } } : {}) });
+            const next = evs[i + 1];
+            i++;
+            // the end of a looped replay holds its final scenes (the PnL card lands last) before it starts again
+            const gap = next ? Math.min(5000, Math.max(0, next.t - ev.t)) / o.speed : 10_000;
+            timers.push(setTimeout(step, gap));
+        };
+        step();
+    }
+    else {
+        const connect = () => {
+            if (stopped)
+                return;
+            let info;
+            try {
+                info = JSON.parse(readFileSync(spectatorInfoPath(io.env), 'utf8'));
+            }
+            catch {
+                timers.push(setTimeout(connect, 3000));
+                return;
+            }
+            if (!Number.isInteger(info.port) || typeof info.token !== 'string') {
+                timers.push(setTimeout(connect, 3000));
+                return;
+            }
+            try {
+                ws = new WebSocket(`ws://127.0.0.1:${info.port}`);
+            }
+            catch {
+                timers.push(setTimeout(connect, 3000));
+                return;
+            }
+            const token = info.token;
+            ws.onopen = () => ws?.send(JSON.stringify({ method: 'hello', token }));
+            ws.onmessage = (m) => {
+                let msg;
+                try {
+                    msg = JSON.parse(String(m.data));
+                }
+                catch {
+                    return;
+                }
+                if (msg && msg.type === 'event')
+                    engine.feed(msg.event);
+            };
+            ws.onclose = () => { ws = null; if (!stopped)
+                timers.push(setTimeout(connect, 3000)); };
+            ws.onerror = () => { };
+        };
+        connect();
+    }
+    const ticker = setInterval(() => engine.tick(), 1000);
+    engine.tick();
+    const ledgerTimer = ledger ? setInterval(() => { void ledger.load(); }, 30_000) : null;
+    return new Promise((resolve) => {
+        const stop = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(ticker);
+            if (ledgerTimer)
+                clearInterval(ledgerTimer);
+            for (const t of timers)
+                clearTimeout(t);
+            try {
+                ws?.close();
+            }
+            catch { /* ignore */ }
+            if (io.stdin.isTTY) {
+                try {
+                    io.stdin.setRawMode(false);
+                }
+                catch { /* ignore */ }
+                io.stdin.pause();
+            }
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+            void server.close().then(() => resolve(0));
+        };
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+        if (io.stdin.isTTY) {
+            io.stdin.setRawMode(true);
+            io.stdin.resume();
+            io.stdin.on('data', (d) => {
+                const k = d.toString();
+                if (k === 'q' || k === '\u0003')
+                    stop();
+                else if (k === 'n')
+                    printUrls();
+            });
+        }
+    });
+}