dexterm-cli 0.1.2 → 0.1.4

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

@@ -3,7 +3,7 @@
 //   dexterm mcp                         run the read-only MCP server on stdio (what the analyst uses and
 //                                       what `claude mcp add dexterm -- dexterm mcp` wires up)
 //   dexterm mcp install <client>        write/print the MCP config for a client (claude-code, claude-desktop,
-//                                       cursor, codex, openclaw, generic). Shows the exact change, asks first,
+//                                       cursor, codex, generic). Shows the exact change, asks first,
 //                                       is idempotent, and backs the file up before editing.
 //   dexterm mcp doctor                  spawn the server over stdio, do the MCP handshake, and list the tools,
 //                                       prompts and resources the agent sees — proof the connection works.
@@ -60,15 +60,10 @@ export const CLIENTS = [
         path: (env) => join(env.CODEX_HOME || join(home(env), '.codex'), 'config.toml'),
         note: 'Codex reads MCP servers from the [mcp_servers.*] tables in ~/.codex/config.toml.',
     },
-    {
-        id: 'openclaw', label: 'OpenClaw / generic agent', format: 'print', keyPath: 'mcpServers',
-        path: () => null,
-        note: 'OpenClaw and most agents take a standard mcpServers entry; paste this where your agent reads MCP servers, or pass --config FILE to write a JSON file.',
-    },
     {
         id: 'generic', label: 'Generic (print the snippet)', format: 'print', keyPath: 'mcpServers',
         path: () => null,
-        note: 'the standard stdio MCP server entry; add it to your client\'s MCP config.',
+        note: 'the standard stdio mcpServers entry most agents take; paste it where your agent reads MCP servers, or pass --config FILE to write a JSON file.',
     },
 ];
 export function clientById(id) { return CLIENTS.find((c) => c.id === id); }

package/dist/packages/cli/src/mcp-follow.js

@@ -0,0 +1,225 @@
+// `dexterm` TUI — follow an agent that is driving over MCP (task-1421, "see what your agent is doing").
+//
+// The running terminal can WATCH and visibly FOLLOW an agent connected through `dexterm mcp` (Claude Code,
+// Cursor, Codex, Claude Desktop, …). That MCP server is a separate process the external client spawned, so
+// the app cannot set its env; instead this session, while it is open, writes the ~/.dexterm rendezvous the
+// server reads (packages/mcp spectator-sink) and tails the JSONL channel the server appends to. Each record
+// is folded into a SpectatorHub → a FollowController (the AGENT ACTIVITY panel + a SCREEN model) and, for
+// navigation calls, moved into the REAL terminal through the caller's onNav hook (open a token, switch
+// screen/feed/filter, highlight). Owner's own machine → follow mode is unredacted; the optional read-only
+// stream (SpectatorServer) redacts every copy that leaves the hub, exactly as in task-1406.
+//
+// It adds NO power. A record only DESCRIBES a read/navigation call the gate already allowed; there is no
+// inbound path from here to anything that can arm, sign, confirm, send or raise a cap. "pause / take over /
+// kill" are local follow controls: pause/take-over stop the terminal mirroring the agent (the external agent
+// keeps running — we simply stop moving the screen), and kill removes the rendezvous so the server stops
+// emitting. Any user keypress during an agent move takes control, so the human and the agent never fight.
+import { writeFileSync, readFileSync, rmSync, mkdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { SpectatorHub, FollowController, SpectatorServer, } from '../../agents/src/index.js';
+import { rendezvousPath } from '../../mcp/src/index.js';
+function navLabel(agent, nav) {
+    const coin = nav.mint ? ` ${nav.mint.length > 10 ? nav.mint.slice(0, 4) + '…' + nav.mint.slice(-4) : nav.mint}` : '';
+    if (nav.screen === 'token')
+        return `agent ${agent}: opened${coin}`;
+    if (nav.screen === 'ticket')
+        return `agent ${agent}: opened the ${nav.side ?? ''} ticket${coin}`;
+    if (nav.screen === 'watchlist')
+        return `agent ${agent}: watchlisted${coin}`;
+    if (nav.feed)
+        return `agent ${agent}: switched the feed to ${nav.feed}`;
+    if (nav.filter)
+        return `agent ${agent}: filtered ${nav.filter}`;
+    if (nav.highlight)
+        return `agent ${agent}: highlighted ${nav.highlight.length > 10 ? nav.highlight.slice(0, 4) + '…' + nav.highlight.slice(-4) : nav.highlight}`;
+    if (nav.screen)
+        return `agent ${agent}: switched to ${nav.screen}`;
+    return `agent ${agent}: navigated`;
+}
+/**
+ * A follow session for one running terminal. Call start() to arm the rendezvous and begin tailing, pump()
+ * to process new records (the timer does this for you), the controls to pause/take-over/kill, userKey() when
+ * the human presses any key, and stop() to tear everything down. Never throws into the key loop.
+ */
+export class McpFollowSession {
+    hub;
+    follow;
+    opts;
+    rvPath;
+    channelPath;
+    token;
+    agentLabel;
+    currentAgent;
+    offset = 0;
+    timer = null;
+    stream = null;
+    armed = false;
+    paused = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.agentLabel = opts.agentLabel || 'mcp-agent';
+        this.currentAgent = this.agentLabel;
+        this.rvPath = rendezvousPath(opts.env);
+        this.channelPath = this.rvPath.replace(/\.json$/, '.jsonl');
+        this.token = randomBytes(24).toString('hex');
+        this.hub = new SpectatorHub({ cap: Math.max(1, opts.activityCap ?? 200) });
+        const controls = {
+            pauseAgent: () => true,
+            resumeAgent: () => { this.rearm(); return true; },
+            kickAgent: () => { this.disarm(); return 1; },
+        };
+        this.follow = new FollowController({ controls, activityCap: Math.max(1, opts.activityCap ?? 200) });
+        this.hub.on((ev) => this.follow.apply(ev));
+    }
+    /** Arm the rendezvous (so a `dexterm mcp` server starts emitting) and begin tailing. Idempotent. */
+    async start() {
+        this.rearm();
+        if (this.opts.stream) {
+            try {
+                this.stream = new SpectatorServer({ hub: this.hub, env: this.opts.env });
+                await this.stream.start();
+            }
+            catch {
+                this.stream = null;
+            }
+        }
+        if (!this.timer) {
+            this.timer = setInterval(() => this.pump(), Math.max(30, this.opts.pollMs ?? 150));
+            this.timer.unref?.();
+        }
+    }
+    /** Write (or re-write) the channel + rendezvous so the server emits here. */
+    rearm() {
+        try {
+            mkdirSync(dirname(this.rvPath), { recursive: true });
+            if (!this.armed) {
+                writeFileSync(this.channelPath, '', { mode: 0o600 });
+                this.offset = 0;
+            }
+            writeFileSync(this.rvPath, JSON.stringify({ file: this.channelPath, token: this.token, agent: this.agentLabel }) + '\n', { mode: 0o600 });
+            this.armed = true;
+        }
+        catch { /* best-effort local channel */ }
+    }
+    /** Remove the rendezvous so the server stops emitting (the external agent keeps running; we stop seeing it). */
+    disarm() {
+        try {
+            // A second follow surface may have replaced the rendezvous after this session started.  Never remove
+            // another surface's live handle when this one pauses, is killed, or exits.
+            const current = JSON.parse(readFileSync(this.rvPath, 'utf8'));
+            if (current.token === this.token)
+                rmSync(this.rvPath, { force: true });
+        }
+        catch { /* absent/malformed/another surface owns it */ }
+        this.armed = false;
+    }
+    /** Read and fold any records appended since the last pump. Public so tests can drive it without timers. */
+    pump() {
+        let text;
+        try {
+            const st = statSync(this.channelPath);
+            if (st.size <= this.offset) {
+                if (st.size < this.offset)
+                    this.offset = 0;
+                else
+                    return;
+            }
+            text = readFileSync(this.channelPath, 'utf8');
+        }
+        catch {
+            return;
+        }
+        const slice = text.slice(this.offset);
+        const nl = slice.lastIndexOf('\n');
+        if (nl < 0)
+            return; // no complete line yet
+        this.offset += nl + 1;
+        for (const line of slice.slice(0, nl).split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(t);
+            }
+            catch {
+                continue;
+            }
+            this.ingest(rec);
+        }
+    }
+    /** Fold one record: verify its token, strip it, emit into the hub, and move the terminal for a nav call. */
+    ingest(rec) {
+        if (typeof rec.phase !== 'string')
+            return;
+        // Only accept records written by the server we handed our token to (local 0600 file; defence in depth).
+        if (rec.token !== this.token)
+            return;
+        this.currentAgent = typeof rec.agent === 'string' && rec.agent ? rec.agent : this.agentLabel;
+        // The token NEVER enters the hub / activity / stream — fold only the observable fields.
+        const ev = this.hub.emit({
+            phase: rec.phase,
+            agent: this.currentAgent,
+            transport: 'mcp',
+            tool: rec.tool ?? null,
+            summary: rec.summary,
+            ms: rec.ms ?? null,
+            dataAgeSec: rec.dataAgeSec ?? null,
+            nav: rec.nav ?? null,
+            ok: rec.ok ?? true,
+            t: typeof rec.t === 'number' ? rec.t : undefined,
+        });
+        // Move the real terminal ONLY while the agent has control (a user keypress / take-over / kill flips this).
+        if (ev.phase === 'nav' && ev.ok !== false && ev.nav && this.canFollow()) {
+            const label = navLabel(this.currentAgent, ev.nav);
+            try {
+                this.opts.onNav?.(ev.nav, label);
+            }
+            catch { /* a bad hook never breaks the tail */ }
+            try {
+                this.opts.onStatus?.(label);
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            this.opts.onEvent?.();
+        }
+        catch { /* ignore */ }
+    }
+    /** True when the terminal should mirror the agent: the agent still has control and is active. */
+    canFollow() {
+        if (this.follow.controlState !== 'agent')
+            return false;
+        const st = this.follow.view().agents.find((a) => a.name === this.currentAgent);
+        return !st || st.status === 'active';
+    }
+    // ----- the owner's controls. Each returns a short line to toast. -----
+    pause() { const l = this.follow.pause(this.currentAgent); this.paused = l.startsWith('paused '); this.opts.onStatus?.(l); return l; }
+    takeOver() { const l = this.follow.takeOver(this.currentAgent); this.paused = false; this.opts.onStatus?.(l); return l; }
+    resume() { const l = this.follow.resume(this.currentAgent); this.paused = false; this.opts.onStatus?.(l); return l; }
+    kill() { const l = this.follow.kill(this.currentAgent); this.paused = false; this.opts.onStatus?.(l); return l; }
+    /** Any physical keypress while the agent is driving: the human takes over (no fight over the screen). */
+    userKey() { if (this.follow.controlState === 'agent')
+        this.takeOver(); }
+    get controlState() { return this.follow.controlState; }
+    get isPaused() { return this.paused; }
+    get screenModel() { return this.follow.screenModel; }
+    get streamPort() { return this.stream?.port ?? 0; }
+    view() { return this.follow.view(); }
+    /** Tear down: stop the timer, remove the rendezvous, close the stream. Safe to call more than once. */
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.disarm();
+        if (this.stream) {
+            try {
+                await this.stream.close();
+            }
+            catch { /* ignore */ }
+            this.stream = null;
+        }
+    }
+}

package/dist/packages/cli/src/pnl-app.js

@@ -0,0 +1,221 @@
+// dexterm — PNL CARD glue for the app (task-1407). `H` on the token, positions and followed-wallets screens opens a
+// preview of the coin's PnL card built from dexterm's own records:
+//   token      → that coin: LIVE when the signer's ledger has fills for it, else PAPER
+//   positions  → every coin with fills (newest activity first; ← → cycle), LIVE or PAPER as above
+//   follows    → the selected followed wallet's coins (TRACKED), newest first
+// In the preview: x share to X · t copy as text · s save only · a show/hide wallet · z exact size/band ·
+// f 16:9 ⇄ 1:1 · ← → other coin · esc close. Share = save + clipboard image + X compose intent in the user's own
+// browser (pnl-card.ts shareCard); dexterm posts nothing. Nothing here trades, signs or edits a number.
+import { mix } from '../../tui/src/index.js';
+import { computeCard, renderCard, previewCanvas, cardText, paperCardInput, liveCardInput, trackedCardInput, CardError, } from "./pnl-card.js";
+const MARK_VIA = 'dexscreener';
+function coinMeta(state, mint) {
+    const tv = state.live?.token?.view;
+    if (tv && tv.mint === mint)
+        return { symbol: tv.symbol, name: tv.name, image: tv.image };
+    const row = state.screener.rows.find((r) => r.mint === mint);
+    return { symbol: row?.symbol ?? null, name: row?.name ?? null, image: row?.image ?? null };
+}
+function imageOf(state, url) {
+    if (!url || !state.images)
+        return null;
+    const st = state.images.get(url, 2);
+    return st.state === 'ready' ? st.img : null;
+}
+/** The newest price mark for a mint: the positions mark pass, else the open token's market panel ÷ SOL/USD. */
+export function markFor(state, mint) {
+    const pos = state.live?.positions;
+    const p = pos?.markOf(mint) ?? null, at = pos?.markAt(mint) ?? null;
+    if (p !== null && at !== null)
+        return { priceSol: p, at, via: MARK_VIA };
+    const tv = state.live?.token?.view;
+    const solUsd = pos?.solUsd() ?? null;
+    const m = tv?.panels.market;
+    if (tv && tv.mint === mint && tv.price && solUsd && m?.fetchedAt)
+        return { priceSol: tv.price / solUsd, at: m.fetchedAt, via: `${m.via ?? 'market'} ÷ SOL/USD` };
+    return null;
+}
+/** Coins with paper or live fills, newest activity first. */
+function tradedCoins(state) {
+    const live = state.live;
+    if (!live)
+        return [];
+    const last = new Map();
+    const see = (mint, t, symbol) => { const e = last.get(mint); if (!e || t > e.t)
+        last.set(mint, { t, symbol }); };
+    for (const r of live.wallet.trades(1000))
+        see(r.mint, r.t, r.symbol);
+    for (const r of live.livePositions?.records(1000) ?? [])
+        see(r.mint, r.t, r.symbol);
+    return [...last.entries()].sort((a, b) => b[1].t - a[1].t).map(([mint, v]) => ({ mint, symbol: v.symbol }));
+}
+/** Open the preview for the current screen. Returns a reason when there is nothing to card. */
+export function openPnl(state) {
+    if (!state.live)
+        return 'PnL cards are made from recorded fills: run dexterm live (not --fixtures / --replay)';
+    const base = { idx: 0, stats: null, error: null, busy: false, notice: null, opts: { aspect: 'wide', showWallet: false, exactSize: false } };
+    if (state.screen === 'follows') {
+        const follows = state.copy?.follows() ?? [];
+        const f = follows[Math.max(0, Math.min(follows.length - 1, state.copyUi?.selected ?? 0))];
+        if (!f)
+            return 'follow a wallet first (i), then H cards its coins';
+        const seen = new Set();
+        const choices = [];
+        for (const tr of [...(state.copy?.trades(f.addr) ?? [])].sort((a, b) => b.t - a.t)) {
+            if (seen.has(tr.mint) || tr.side === 'transfer')
+                continue;
+            seen.add(tr.mint);
+            choices.push({ mint: tr.mint, symbol: coinMeta(state, tr.mint).symbol ?? tr.mint.slice(0, 4) });
+        }
+        if (!choices.length)
+            return 'no decoded swaps for this wallet yet (r polls now)';
+        state.pnl = { origin: 'follows', choices, wallet: f.addr, ...base };
+    }
+    else if (state.screen === 'token') {
+        const mint = state.live.token?.view?.mint ?? state.token?.mint ?? null;
+        if (!mint)
+            return 'open a coin first';
+        const has = (state.live.livePositions?.records(1, mint).length ?? 0) > 0 || state.live.wallet.trades(1000).some((r) => r.mint === mint);
+        if (!has)
+            return 'no paper or live fills for this coin yet: PnL cards come from your own recorded trades';
+        state.pnl = { origin: 'token', choices: [{ mint, symbol: coinMeta(state, mint).symbol ?? mint.slice(0, 4) }], wallet: null, ...base };
+    }
+    else if (state.screen === 'positions') {
+        const choices = tradedCoins(state);
+        if (!choices.length)
+            return 'no paper or live fills yet: B / S on a token to trade, then H here';
+        state.pnl = { origin: 'positions', choices, wallet: null, ...base };
+    }
+    else
+        return 'PnL cards open from the token, positions (P) or followed wallets (U) screens';
+    state.overlay = 'pnl';
+    return null;
+}
+/** The card input for the current choice, from the right ledger. Async only for a tracked coin that needs decimals / a price. */
+export async function pnlInput(state, ui) {
+    const live = state.live;
+    if (!live)
+        throw new CardError('no live context');
+    const ch = ui.choices[ui.idx];
+    const meta = coinMeta(state, ch.mint);
+    const image = imageOf(state, meta.image);
+    if (ui.origin === 'follows' && ui.wallet && state.copy) {
+        const copy = state.copy;
+        const st = copy.status();
+        const stats = copy.stats(ui.wallet);
+        let mark = markFor(state, ch.mint);
+        let decimals = null;
+        // decimals + a price for a public mint: the same keyless reads the mirror checks make (no wallet, no user data)
+        const m = await copy.mirrorMarket(ch.mint, { symbol: meta.symbol });
+        decimals = m.decimals;
+        const solUsd = live.positions.solUsd();
+        if (!mark && m.priceUsd && m.priceAt && solUsd)
+            mark = { priceSol: m.priceUsd / solUsd, at: m.priceAt, via: `${MARK_VIA} ÷ SOL/USD` };
+        return trackedCardInput(copy.trades(ui.wallet), {
+            wallet: ui.wallet, mint: ch.mint, symbol: meta.symbol ?? m.symbol ?? ch.symbol, name: meta.name, decimals, mark,
+            historyAt: st.lastPollAt, complete: stats.sample.complete, image,
+        });
+    }
+    const liveRows = live.livePositions?.fills(ch.mint) ?? [];
+    if (liveRows.length) {
+        return liveCardInput(liveRows, { mint: ch.mint, symbol: meta.symbol ?? undefined, name: meta.name, wallet: live.linkedWallet?.publicKey ?? null, mark: markFor(state, ch.mint), image });
+    }
+    return paperCardInput(live.wallet.trades(1000), { mint: ch.mint, symbol: meta.symbol ?? undefined, name: meta.name, mark: markFor(state, ch.mint), image });
+}
+/** (Re)build the card for the current choice; on refusal the preview shows the reason instead of a card. */
+export async function loadPnl(state, now = Date.now()) {
+    const ui = state.pnl;
+    if (!ui)
+        return;
+    try {
+        ui.stats = computeCard(await pnlInput(state, ui), now);
+        ui.error = null;
+    }
+    catch (e) {
+        ui.stats = null;
+        ui.error = e instanceof Error ? e.message : String(e);
+    }
+}
+/** Keys while the preview is open. Pure: the loop performs reload / share. */
+export function pnlKey(ui, key) {
+    if (key.name === 'esc' || (key.name === 'char' && key.ch === 'q'))
+        return { kind: 'close' };
+    if (ui.busy)
+        return { kind: 'none' };
+    const ch = key.name === 'char' && !key.ctrl ? key.ch : undefined;
+    if (key.name === 'right' || ch === ']' || ch === 'l') {
+        if (ui.choices.length > 1) {
+            ui.idx = (ui.idx + 1) % ui.choices.length;
+            return { kind: 'reload' };
+        }
+        return { kind: 'none' };
+    }
+    if (key.name === 'left' || ch === '[' || ch === 'h') {
+        if (ui.choices.length > 1) {
+            ui.idx = (ui.idx - 1 + ui.choices.length) % ui.choices.length;
+            return { kind: 'reload' };
+        }
+        return { kind: 'none' };
+    }
+    if (ch === 'a') {
+        ui.opts.showWallet = !ui.opts.showWallet;
+        ui.notice = ui.opts.showWallet ? 'wallet + tx signatures SHOWN on the card' : 'wallet hidden';
+        return { kind: 'none' };
+    }
+    if (ch === 'z') {
+        ui.opts.exactSize = !ui.opts.exactSize;
+        ui.notice = ui.opts.exactSize ? 'exact SOL size SHOWN on the card' : 'size shown as a band';
+        return { kind: 'none' };
+    }
+    if (ch === 'f') {
+        ui.opts.aspect = ui.opts.aspect === 'wide' ? 'square' : 'wide';
+        return { kind: 'none' };
+    }
+    if (!ui.stats)
+        return { kind: 'none' };
+    if (ch === 'x')
+        return { kind: 'share', action: 'x' };
+    if (ch === 't')
+        return { kind: 'share', action: 'text' };
+    if (ch === 's')
+        return { kind: 'share', action: 'save' };
+    return { kind: 'none' };
+}
+const HINTS = 'x share to X · t copy text · s save · a wallet · z size · f 16:9/1:1 · ←→ coin · esc';
+/** The preview overlay: the card itself at cell size when the terminal fits it, else its text; then the keys. */
+export function renderPnlOverlay(c, state) {
+    const ui = state.pnl;
+    if (!ui)
+        return;
+    const t = c.theme;
+    c.noRain(0, 0, c.w, c.h);
+    c.fill(0, 0, c.w, c.h, ' ', { bg: mix(t.bg, '#000000', 0.5) });
+    const ch = ui.choices[ui.idx];
+    const head = `PnL CARD · $${ch?.symbol ?? '?'}${ui.choices.length > 1 ? ` (${ui.idx + 1}/${ui.choices.length})` : ''} · ${ui.opts.aspect === 'wide' ? '16:9' : '1:1'} · wallet ${ui.opts.showWallet ? 'SHOWN' : 'hidden'} · size ${ui.opts.exactSize ? 'EXACT' : 'band'}`;
+    c.text(1, 0, head, { fg: t.text, bg: t.headBg, b: true }, c.w - 2);
+    c.fill(0, c.h - 1, c.w, 1, ' ', { bg: t.headBg });
+    c.text(1, c.h - 1, ui.busy ? 'working… (esc closes)' : (ui.notice ?? HINTS), { fg: ui.notice ? t.warn : t.muted, bg: t.headBg }, c.w - 2);
+    const area = { x: 0, y: 1, w: c.w, h: c.h - 2 };
+    if (!ui.stats) {
+        c.text(2, 3, ui.error ? `no card: ${ui.error}` : 'building the card…', { fg: ui.error ? t.warn : t.muted, bg: c.bg[c.idx(2, 3)] }, c.w - 4);
+        return;
+    }
+    const r = renderCard(ui.stats, ui.opts);
+    const pv = previewCanvas(r);
+    if (pv.w <= area.w && pv.h <= area.h) {
+        const ox = area.x + Math.floor((area.w - pv.w) / 2), oy = area.y + Math.floor((area.h - pv.h) / 2);
+        for (let y = 0; y < pv.h; y++)
+            for (let x = 0; x < pv.w; x++) {
+                const i = pv.idx(x, y), j = c.idx(ox + x, oy + y);
+                c.ch[j] = pv.ch[i];
+                c.fg[j] = pv.fg[i];
+                c.bg[j] = pv.bg[i];
+                c.at[j] = pv.at[i];
+            }
+        return;
+    }
+    // too small for the card grid: the same facts as text (the PNG is still full size)
+    const lines = cardText(ui.stats, ui.opts).trimEnd().split('\n');
+    lines.forEach((l, k) => { if (2 + k < c.h - 1)
+        c.text(2, 2 + k, l, { fg: k === 0 ? t.warn : t.text, bg: c.bg[c.idx(2, 2 + k)] }, c.w - 4); });
+}