dexterm-cli 0.1.6 → 0.2.0

package/dist/packages/autotrade/src/chat/config.js

@@ -0,0 +1,95 @@
+// dexterm autotrade chat — connectors.json (task-1527, AUTOTRADE-SPEC §8.3). It never holds a secret.
+//
+// $DEXTERM_HOME/connectors.json (0600):
+//   { schema, telegram: { enabled, bot: {id, username}, secretStore, tiers, allow: [{senderId, chatId, tiers,
+//     pairedAt}], notify: {…per event…}, dailySummaryAt, quietHours, approvals, approvalExpirySec, repriceTolPct,
+//     showAbsoluteBook }, signals: {…} }
+// task-1645: `signals` is the real-mode trade-fire channel setup (signal-channels.ts parses it); it lives here so the
+// Telegram copy and the executor channels are configured in one place. This module only carries it through.
+// Only local commands write it (`dexterm telegram setup|pair|revoke|approvals|notify`). From chat, exactly one
+// field can change: `approvals` from "off" to "on" (safer); everything else, and "off", is local only.
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeJsonAtomic } from "../ledger.js";
+export const CONNECTORS_SCHEMA = 'dexterm-connectors/1';
+export const TIERS_ALL = ['notify', 'control', 'approve'];
+export const DEFAULT_NOTIFY = { candidates: 'digest', entries: true, closes: true, halts: true, spend: true, daily: true };
+export const defaultTelegram = () => ({
+    enabled: false, bot: null, secretStore: null, tiers: [...TIERS_ALL], allow: [], notify: { ...DEFAULT_NOTIFY },
+    dailySummaryAt: '21:00', quietHours: null, approvals: 'off', approvalExpirySec: 90, repriceTolPct: 3, showAbsoluteBook: false,
+});
+export const connectorsPath = (home) => join(home, 'connectors.json');
+const isTier = (x) => x === 'notify' || x === 'control' || x === 'approve';
+const hhmm = (x) => (typeof x === 'string' && /^([01]\d|2[0-3]):[0-5]\d$/.test(x) ? x : null);
+const id = (x) => (typeof x === 'string' && /^-?\d{1,20}$/.test(x) ? x : typeof x === 'number' && Number.isInteger(x) ? String(x) : null);
+/** Read connectors.json; a missing file is the defaults (disabled), a broken one is an error (the bot stays off). */
+export function loadConnectors(home) {
+    const p = connectorsPath(home);
+    if (!existsSync(p))
+        return { ok: true, config: { schema: CONNECTORS_SCHEMA, telegram: defaultTelegram() }, exists: false };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        return { ok: false, error: `${p} is not JSON: ${e.message.slice(0, 120)}` };
+    }
+    const d = raw;
+    if (d.schema !== CONNECTORS_SCHEMA)
+        return { ok: false, error: `${p}: schema is not ${CONNECTORS_SCHEMA}` };
+    const t = d.telegram ?? {};
+    const base = defaultTelegram();
+    const allow = [];
+    for (const a of Array.isArray(t.allow) ? t.allow : []) {
+        const x = a;
+        const s = id(x.senderId);
+        const c = id(x.chatId);
+        if (!s || !c)
+            continue;
+        allow.push({ senderId: s, chatId: c, tiers: Array.isArray(x.tiers) ? x.tiers.filter(isTier) : [], pairedAt: typeof x.pairedAt === 'number' ? x.pairedAt : 0 });
+    }
+    const n = (t.notify ?? {});
+    const bool = (v, dflt) => (typeof v === 'boolean' ? v : dflt);
+    const bot = t.bot && typeof t.bot === 'object' ? t.bot : null;
+    const exp = Number(t.approvalExpirySec);
+    const tol = Number(t.repriceTolPct);
+    const qh = typeof t.quietHours === 'string' && /^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/.test(t.quietHours) ? t.quietHours : null;
+    const telegram = {
+        enabled: t.enabled === true,
+        bot: bot && id(bot.id) && typeof bot.username === 'string' ? { id: id(bot.id), username: String(bot.username).slice(0, 64) } : null,
+        secretStore: t.secretStore === 'keychain' || t.secretStore === 'libsecret' || t.secretStore === 'file' ? t.secretStore : null,
+        tiers: Array.isArray(t.tiers) ? t.tiers.filter(isTier) : base.tiers,
+        allow,
+        notify: {
+            candidates: n.candidates === 'each' || n.candidates === 'off' ? n.candidates : 'digest',
+            entries: bool(n.entries, true), closes: bool(n.closes, true), halts: bool(n.halts, true), spend: bool(n.spend, true), daily: bool(n.daily, true),
+        },
+        dailySummaryAt: t.dailySummaryAt === null ? null : hhmm(t.dailySummaryAt) ?? base.dailySummaryAt,
+        quietHours: qh,
+        approvals: t.approvals === 'on' ? 'on' : 'off',
+        // §8.4: 60 to 120 s, default 90.
+        approvalExpirySec: Number.isFinite(exp) ? Math.min(120, Math.max(60, Math.round(exp))) : 90,
+        repriceTolPct: Number.isFinite(tol) && tol > 0 ? Math.min(10, tol) : 3,
+        showAbsoluteBook: t.showAbsoluteBook === true,
+    };
+    return { ok: true, config: { schema: CONNECTORS_SCHEMA, telegram, ...(d.signals !== undefined ? { signals: d.signals } : {}) }, exists: true };
+}
+export function saveConnectors(home, c) {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    writeJsonAtomic(connectorsPath(home), c);
+}
+/** The allowlist entry for a sender in a chat, or null. A sender paired in one chat is not allowed in another. */
+export function allowed(t, senderId, chatId, tier) {
+    if (!t.tiers.includes(tier))
+        return null;
+    return t.allow.find((a) => a.senderId === senderId && a.chatId === chatId && a.tiers.includes(tier)) ?? null;
+}
+/** True while local time is inside "HH:MM-HH:MM" (wrapping midnight). */
+export function inQuietHours(q, t) {
+    if (!q)
+        return false;
+    const [a, b] = q.split('-').map((x) => { const [h, m] = x.split(':').map(Number); return h * 60 + m; });
+    const d = new Date(t);
+    const now = d.getHours() * 60 + d.getMinutes();
+    return a <= b ? now >= a && now < b : now >= a || now < b;
+}

package/dist/packages/autotrade/src/chat/connector.js

@@ -0,0 +1,24 @@
+// dexterm autotrade chat — the transport-agnostic connector (task-1527, AUTOTRADE-SPEC §8.2).
+//
+// The engine never imports a transport. A connector delivers three things inward and two outward:
+//   inward   commands from a closed list ("/status", "/pause", …), button callbacks (the ONLY thing that can
+//            authorise a trade), and the pairing message "/pair <code>". Free text is never parsed into anything:
+//            it arrives as `text` with its length only and is answered with the help text.
+//   outward  plain-text messages (never markup), PnL card images, and proposals with buttons whose labels and
+//            callback data come from engine state only.
+//
+// Transports: telegram (long poll from the user's machine, telegram.ts) and fake (in memory, fake.ts, every test).
+/** The closed command list (§8.4 tier 2). Anything else is `help`. */
+export const COMMANDS = ['status', 'positions', 'pause', 'resume', 'kill', 'stop', 'flatten', 'strategies', 'use', 'approvals', 'help', 'pair', 'start'];
+/** "/Status@my_bot arg" → {command, args}; null when it is not a slash command. Unknown names map to help. */
+export function parseCommand(text) {
+    const t = text.trim();
+    if (!t.startsWith('/'))
+        return null;
+    const [head, ...rest] = t.split(/\s+/);
+    const name = head.slice(1).split('@')[0].toLowerCase();
+    const command = COMMANDS.includes(name) ? name : 'help';
+    // Args are short tokens only (a preset id, a pairing code, on/off): never prose.
+    const args = rest.slice(0, 3).map((a) => a.slice(0, 40));
+    return { command, args };
+}

package/dist/packages/autotrade/src/chat/control.js

@@ -0,0 +1,104 @@
+// dexterm autotrade chat — tier 2, control (task-1527, AUTOTRADE-SPEC §8.4).
+//
+// The command list is closed; anything else gets the help text. Chat can always make things SAFER and never less
+// safe:
+//   /status /positions /strategies /help   read-only (positions come with a [Sell] button each, bound like a proposal)
+//   /pause                                  no new entries; exits keep running                       always
+//   /resume                                 lifts a PAUSE only; never a kill, panic, breaker halt or guard
+//   /kill (= /stop)                         `autotrade stop`: sessions closed, no entries, exits running  always
+//   /flatten                                sells everything at the next tick, after a [Yes, flatten] button
+//   /use <id>                               an equal-or-tighter validated strategy only, after a [Yes, switch] button;
+//                                           never changes paper/live; a looser one says "change it locally"
+//   /approvals on                           every entry waits for a tap (safer). `off` is local only
+// Not from chat, ever: live mode, looser caps or strategies, approvals off, resuming after a kill or a panic.
+// The router only calls the ControlPort the host gives it; the port writes the same control file the CLI and the
+// Q screen write, so chat is a remote control for the same local engine and adds no path around its fences.
+import { inert, pct, shortMint } from "./format.js";
+export const HELP_LINES = [
+    'dexterm bot · commands:',
+    '/status · /positions · /strategies',
+    '/pause (no new entries) · /resume (lifts a pause only)',
+    '/kill or /stop (stop the runner: no entries, exits keep running)',
+    '/flatten (sell everything, asks first)',
+    '/use <strategy> (equal or tighter only, asks first)',
+    '/approvals on (every entry waits for your tap)',
+    'Trades are approved only with buttons. I never ask for keys or seed phrases.',
+];
+export const NEVER_RATE_LIMITED = ['kill', 'stop', 'pause', 'flatten'];
+export class ControlRouter {
+    port;
+    constructor(port) { this.port = port; }
+    handle(c) {
+        const p = this.port;
+        switch (c.command) {
+            case 'help':
+            case 'start': return { lines: HELP_LINES };
+            case 'pair': return { lines: ['This chat is already paired. Pairing happens on your computer (dexterm telegram pair).'] };
+            case 'status': {
+                const s = p.status();
+                if (!s)
+                    return { lines: ['No runner is running on your computer.'] };
+                return {
+                    lines: [
+                        `STATUS · ${s.state}${s.haltReason ? ` (${inert(s.haltReason, 40)})` : ''}`,
+                        `strategy ${inert(s.strategy.id, 32)} v${inert(s.strategy.version, 12)} (${s.strategy.hash.slice(0, 8)})`,
+                        `open ${s.open} · candidates ${s.candidates} · day P/L ${pct(s.dayPnlPct)}`,
+                        `model spend today $${s.spend.todayUsd.toFixed(2)}${Number.isFinite(s.spend.dayCapUsd) ? ` of $${s.spend.dayCapUsd}` : ''}${s.allowance?.fiveHour !== null && s.allowance?.fiveHour !== undefined ? ` · 5 h window ${Math.round(s.allowance.fiveHour * 100)}%` : ''}`,
+                        `approvals: ${s.approvals}`,
+                        ...(s.real ? [`executor: ${inert(s.real.executor, 160)}`, `limits: ${inert(s.real.limits, 160)}`, ...(s.real.pause ? [`NEW BUYS PAUSED: ${inert(s.real.pause, 120)}`] : [])] : []),
+                    ],
+                };
+            }
+            case 'positions': {
+                const ps = p.positions();
+                if (!ps.length)
+                    return { lines: ['No open positions.'] };
+                const shown = ps.slice(0, 5);
+                return {
+                    lines: [`POSITIONS · ${ps.length} open`, ...ps.slice(0, 10).map((x) => `"${inert(x.symbol, 20)}" ${shortMint(x.mint)} · ${inert(x.profile, 24)} · ${pct(x.pnlPct)}${x.freeBag ? ' · cost back' : ''}${x.next ? ` · ${inert(x.next, 40)}` : ''}`)],
+                    confirm: shown.map((x) => ({ kind: 'sell', lines: [`SELL "${inert(x.symbol, 20)}" ${shortMint(x.mint)} at the next tick? (${pct(x.pnlPct)} now)`], yes: 'Sell', payload: { mint: x.mint } })),
+                };
+            }
+            case 'pause': return { lines: [p.pause().message] };
+            case 'resume': return { lines: [p.resume().message] };
+            case 'kill':
+            case 'stop': return { lines: [p.kill().message] };
+            case 'flatten': {
+                const s = p.status();
+                if (!s)
+                    return { lines: ['No runner is running on your computer.'] };
+                return { lines: [], confirm: [{ kind: 'flatten', lines: [`FLATTEN: stop the runner and sell all ${s.open} position${s.open === 1 ? '' : 's'} at the next tick?`], yes: 'Yes, flatten', payload: { runId: s.runId } }] };
+            }
+            case 'strategies': {
+                const list = p.strategies();
+                if (!list.length)
+                    return { lines: ['No strategies found.'] };
+                return { lines: ['STRATEGIES (✓ = /use allowed: equal or tighter than the running one)', ...list.slice(0, 20).map((x) => `${x.current ? '▶' : x.allowed ? '✓' : '·'} ${inert(x.id, 32)} v${inert(x.version, 12)} (${x.hash.slice(0, 8)})${x.preset ? ' preset' : ''}${x.current ? ' (running)' : x.allowed ? '' : ` · ${inert(x.why, 60)}`}`)] };
+            }
+            case 'use': {
+                const id = c.args[0] ?? '';
+                if (!id)
+                    return { lines: ['Usage: /use <strategy id> (see /strategies)'] };
+                const list = p.strategies();
+                const x = list.find((q) => q.id === id);
+                if (!x)
+                    return { lines: [`No validated strategy "${inert(id, 32)}". See /strategies.`] };
+                if (x.current)
+                    return { lines: [`${inert(id, 32)} is already running.`] };
+                if (!x.allowed)
+                    return { lines: [`Refused: ${inert(id, 32)} is not equal or tighter (${inert(x.why, 80)}). Change it locally.`] };
+                return { lines: [], confirm: [{ kind: 'use', lines: [`SWITCH to ${inert(x.id, 32)} v${inert(x.version, 12)} (${x.hash.slice(0, 8)})? New entries stop now; the switch happens once the open positions have closed.`], yes: 'Yes, switch', payload: { id: x.id, hash: x.hash } }] };
+            }
+            case 'approvals': {
+                const a = (c.args[0] ?? '').toLowerCase();
+                if (a === 'on')
+                    return { lines: [p.approvalsOn().message] };
+                if (a === 'off')
+                    return { lines: ['Approvals can be turned off only on your computer (dexterm telegram approvals off).'] };
+                const s = p.status();
+                return { lines: [`approvals: ${s?.approvals ?? 'unknown'} · /approvals on makes every entry wait for your tap`] };
+            }
+            default: return { lines: HELP_LINES };
+        }
+    }
+}

package/dist/packages/autotrade/src/chat/fake.js

@@ -0,0 +1,100 @@
+// dexterm autotrade chat — the fake transport (task-1527, AUTOTRADE-SPEC §8.2). No network, for every test.
+//
+// An in-memory ChatConnector with a scriptable user: `user(id, chatId).command('/pause')`, `.tap(ref, data)`,
+// `.text('buy it now')`. Every outbound message is kept in `sent` (with its plain text, buttons and edits), so a
+// test can read exactly what a phone would show. Updates get increasing update ids like Telegram's; `redeliver`
+// replays an old update (a duplicate delivery) to test the dedupe.
+import { createHash } from 'node:crypto';
+import { parseCommand } from "./connector.js";
+import { plain } from "./format.js";
+export class FakeConnector {
+    transport = 'fake';
+    sent = [];
+    toasts = [];
+    /** Make the next n sends fail (a Telegram outage, a 429). */
+    failSends = 0;
+    conflict = null;
+    cmdH = [];
+    actH = [];
+    txtH = [];
+    updateSeq = 1000;
+    msgSeq = 1;
+    delivered = [];
+    clock;
+    constructor(o = {}) { this.clock = o.now ?? Date.now; }
+    async start(signal) {
+        if (signal.aborted)
+            return;
+        await new Promise((r) => signal.addEventListener('abort', () => r(), { once: true }));
+    }
+    async send(to, msg) {
+        if (this.failSends > 0) {
+            this.failSends--;
+            throw new Error('fake transport: send failed');
+        }
+        const ref = { chatId: to.chatId, messageId: String(this.msgSeq++) };
+        const lines = msg.kind === 'card' ? [msg.caption] : msg.lines;
+        this.sent.push({ ref, msg, text: plain(msg.badge, lines), buttons: msg.kind === 'proposal' ? msg.buttons.map((b) => ({ ...b })) : [], edits: [], acks: [] });
+        return ref;
+    }
+    async edit(ref, msg) {
+        const s = this.sent.find((x) => x.ref.chatId === ref.chatId && x.ref.messageId === ref.messageId);
+        if (!s)
+            throw new Error('fake transport: no such message');
+        s.edits.push(msg);
+        s.buttons = msg.kind === 'proposal' ? msg.buttons.map((b) => ({ ...b })) : [];
+        s.text = plain(msg.badge, msg.kind === 'card' ? [msg.caption] : msg.lines);
+    }
+    onCommand(h) { this.cmdH.push(h); }
+    onAction(h) { this.actH.push(h); }
+    onText(h) { this.txtH.push(h); }
+    async ackAction(a, toast) {
+        this.toasts.push({ actionId: a.actionId, toast });
+        const s = this.sent.find((x) => x.ref.chatId === a.ref.chatId && x.ref.messageId === a.ref.messageId);
+        s?.acks.push(toast);
+    }
+    health() { return { transport: this.transport, lastPollAt: this.clock(), conflict: this.conflict, rateLimited: 0, errors: 0, lastError: null }; }
+    /** A scripted person in a chat (`sender`: the @username / display name Telegram would report with a command). */
+    user(senderId, chatId = senderId, chatKind = 'private', sender) {
+        const base = () => ({ transport: this.transport, updateId: String(++this.updateSeq), chatId, chatKind, senderId, t: this.clock() });
+        return {
+            /** Send "/cmd args" (or any text: non-commands arrive as text, never parsed). */
+            command: (text) => {
+                const p = parseCommand(text);
+                if (!p) {
+                    this.deliver({ kind: 'text', x: { ...base(), length: text.length, sha256: createHash('sha256').update(text).digest('hex') } });
+                    return;
+                }
+                this.deliver({ kind: 'command', c: { ...base(), ...(sender ? { sender } : {}), command: p.command, args: p.args } });
+            },
+            text: (text) => this.deliver({ kind: 'text', x: { ...base(), length: text.length, sha256: createHash('sha256').update(text).digest('hex') } }),
+            /** Tap a button: by its message ref and data (a forged tap can carry any data). */
+            tap: (ref, data) => this.deliver({ kind: 'action', a: { ...base(), actionId: `cb${this.updateSeq}`, ref, data } }),
+        };
+    }
+    /** The newest message whose text matches, for tests. */
+    last(re) {
+        for (let i = this.sent.length - 1; i >= 0; i--)
+            if (!re || re.test(this.sent[i].text))
+                return this.sent[i];
+        return undefined;
+    }
+    /** Deliver an old update again (Telegram can redeliver; the router dedupes by update id). */
+    redeliver(index = -1) {
+        const u = this.delivered.at(index);
+        if (u)
+            this.dispatch(u);
+    }
+    deliver(u) { this.delivered.push(u); this.dispatch(u); }
+    dispatch(u) {
+        if (u.kind === 'command')
+            for (const h of this.cmdH)
+                h(u.c);
+        else if (u.kind === 'action')
+            for (const h of this.actH)
+                h(u.a);
+        else
+            for (const h of this.txtH)
+                h(u.x);
+    }
+}

package/dist/packages/autotrade/src/chat/format.js

@@ -0,0 +1,71 @@
+// dexterm autotrade chat — inert text and the message templates' small helpers (task-1527, AUTOTRADE-SPEC §8.6).
+//
+// Every token-derived string (symbol, name, the agent's reason, which quotes token text) goes through the app's
+// prompt firewall (`@dexterm/mcp firewall()`: control and bidi characters stripped, whitespace collapsed, links
+// and addresses replaced, length capped), then the chat rules: sent as plain text (no parse_mode, so no markup or
+// link can be injected), quoted, and with the characters Telegram turns into tappable things in plain text
+// (`/command`, `@mention`) swapped for look-alikes, so a token named "/kill" or "@phish" is only ever text.
+// Buttons never carry token text: their labels and data are built from engine state only (approvals.ts).
+import { firewall } from '../../../mcp/src/index.js';
+import { redact } from "./redact.js";
+const UNESCAPE = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"' };
+/**
+ * What chat never shows (§8.6 "Hidden"), replaced before the firewall: a keypair as a JSON byte array, 0x-hex and
+ * long bare hex, API-key-shaped strings (vendor prefixes, `api_key=…`, UUIDs), and file paths (absolute, `~/`,
+ * `./`, Windows). Engine strings (an exit detail, a halt reason, a guard effect) can quote any of these.
+ */
+const HIDDEN = [
+    [/\[\s*\d{1,3}(?:\s*,\s*\d{1,3}){15,}\s*\]/g, '[key]'],
+    [/\b0x[0-9a-fA-F]{8,}\b/g, '[hex]'],
+    [/\b[0-9a-fA-F]{32,}\b/g, '[hex]'],
+    [/\b(?:sk|pk|rk)[-_](?:[A-Za-z0-9]+[-_])*[A-Za-z0-9]{12,}/g, '[key]'],
+    [/\b(?:AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{30,})\b/g, '[key]'],
+    [/\b(api[-_]?key|access[-_]?token|auth[-_]?token|secret[-_]?key|client[-_]?secret|private[-_]?key|password|passwd)(\s*[=:]\s*)[^\s'",;&]+/gi, '$1$2[key]'],
+    [/\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g, '[key]'],
+    // Paths: home- or dot-relative, under a filesystem root, any absolute one ending in a file name, or Windows. A JSON
+    // pointer (`/bankroll/startUsd`, a /strategies reason) and a slash command stay text.
+    [/(^|[\s'"(=:,[])(?:~|\.{1,2})\/[^\s'"()]*/g, '$1[path]'],
+    [/(^|[\s'"(=:,[])\/(?:Users|home|root|var|tmp|private|etc|opt|usr|mnt|media|Volumes|Library|System|Applications|srv|run|dev|proc)\/[^\s'"()]*/g, '$1[path]'],
+    [/(^|[\s'"(=:,[])\/(?:[^\s/'"()]+\/)+[^\s/'"()]*\.[A-Za-z0-9]{1,8}\b/g, '$1[path]'],
+    [/(^|[\s'"(=:,[])[A-Za-z]:\\[^\s'"()]*/g, '$1[path]'],
+];
+/** Secrets, keys and paths taken out of an engine or token string (inert() applies it first). */
+export function hideSecrets(s) {
+    let out = redact(s);
+    for (const [re, to] of HIDDEN)
+        out = out.replace(re, to);
+    return out;
+}
+/** Token-derived text made inert for a chat message: secrets and paths hidden, firewalled, capped, no tappable command or mention. */
+export function inert(text, max = 32, source = 'token') {
+    const fw = firewall(text === null || text === undefined ? '' : hideSecrets(String(text)), source, 'description');
+    if (!fw)
+        return '';
+    const m = fw.match(/^<untrusted [^>]*>([\s\S]*)<\/untrusted>$/);
+    let s = (m ? m[1] : fw).replace(/&(amp|lt|gt|quot);/g, (x) => UNESCAPE[x] ?? x);
+    s = s.replace(/\//g, '∕').replace(/@/g, '＠').replace(/"/g, "'");
+    if (s.length > max)
+        s = `${s.slice(0, Math.max(1, max - 1))}…`;
+    return s;
+}
+/** `abcd…wxyz`: the most of an address a message ever shows. */
+export const shortMint = (m) => (m.length > 10 ? `${m.slice(0, 4)}…${m.slice(-4)}` : m);
+export const pct = (v, digits = 1) => (v === null || v === undefined || !Number.isFinite(v) ? '?' : `${v >= 0 ? '+' : ''}${v.toFixed(digits)}%`);
+export function price(v) {
+    if (v === null || v === undefined || !Number.isFinite(v) || v <= 0)
+        return '?';
+    return v >= 1 ? v.toFixed(4) : v.toPrecision(4);
+}
+export function usdShort(v) {
+    if (v === null || v === undefined || !Number.isFinite(v))
+        return '?';
+    const a = Math.abs(v);
+    return a >= 1e6 ? `$${(v / 1e6).toFixed(2)}M` : a >= 1e3 ? `$${(v / 1e3).toFixed(1)}K` : `$${v.toFixed(2)}`;
+}
+/** Plain text of a message for the fake transport and the audit (lines joined, badge first). */
+export function plain(badge, lines) {
+    return [badge ? `${badge} · ${lines[0] ?? ''}` : lines[0] ?? '', ...lines.slice(1)].join('\n');
+}
+/** Telegram's limit is 4096 characters; stay well under it. */
+export const MAX_MESSAGE = 3500;
+export const clip = (s, max = MAX_MESSAGE) => (s.length > max ? `${s.slice(0, max - 1)}…` : s);

package/dist/packages/autotrade/src/chat/hub.js

@@ -0,0 +1,187 @@
+// dexterm autotrade chat — the hub: one connector, the allowlist, the rate limits, the audit (task-1527, §8.1, §8.6).
+//
+// Inbound, in order, for every update from the connector's own poll:
+//   dedupe by update id (a redelivered update is recorded once and never acted on twice);
+//   audit (update id, sender, chat, the command or the action's record id; free text as length + hash only);
+//   pairing (only while a local pairing window is open: `/pair <code>` from a private chat);
+//   the allowlist: an unknown sender gets NO reply and nothing happens (five in an hour raise a local alert:
+//     "possible token leak"); a paired sender needs the tier the command needs, in the chat it was paired in;
+//   rate limit: 10 commands a minute per sender, except /kill, /stop, /pause and /flatten (never limited);
+//   commands → the ControlRouter; button callbacks → the ApprovalBroker (the only trade authority);
+//   free text → the help text, never parsed.
+// Outbound: notify messages go to every chat paired with the notify tier; replies go to the asking chat only.
+import { allowed } from "./config.js";
+import { ControlRouter, HELP_LINES, NEVER_RATE_LIMITED } from "./control.js";
+export const COMMANDS_PER_MIN = 10;
+export const UNKNOWN_ALERT_PER_HOUR = 5;
+const READ_ONLY = ['status', 'positions', 'strategies', 'help', 'start'];
+export class ChatHub {
+    o;
+    now;
+    seen = new Set();
+    cmdTimes = new Map();
+    unknownTimes = [];
+    lastUnknownAlert = 0;
+    router;
+    pairing = null;
+    inflight = new Set();
+    constructor(o) {
+        this.o = o;
+        this.now = o.now ?? Date.now;
+        this.router = o.port ? new ControlRouter(o.port) : null;
+        o.connector.onCommand((c) => this.track(this.onCommand(c)));
+        o.connector.onAction((a) => this.track(this.onAction(a)));
+        o.connector.onText((t) => this.track(this.onText(t)));
+    }
+    track(p) {
+        const q = p.catch((e) => { this.o.audit.add(this.now(), 'hub_error', { error: e instanceof Error ? e.message.slice(0, 160) : String(e).slice(0, 160) }); }).finally(() => this.inflight.delete(q));
+        this.inflight.add(q);
+    }
+    /** Wait for every inbound handler in flight (tests, shutdown). */
+    async idle() { while (this.inflight.size)
+        await Promise.allSettled([...this.inflight]); }
+    setPort(port) { this.router = port ? new ControlRouter(port) : null; }
+    /** Open a local pairing window: `/pair <code>` from a private chat is checked against it. */
+    openPairing(window, onResult) { this.pairing = { window, onResult }; }
+    closePairing() { this.pairing = null; }
+    dup(updateId) {
+        if (this.seen.has(updateId))
+            return true;
+        this.seen.add(updateId);
+        if (this.seen.size > 5000) {
+            const f = this.seen.values().next().value;
+            if (f !== undefined)
+                this.seen.delete(f);
+        }
+        return false;
+    }
+    unknown(senderId, what) {
+        const now = this.now();
+        this.unknownTimes = this.unknownTimes.filter((t) => now - t < 3600_000);
+        this.unknownTimes.push(now);
+        this.o.audit.add(now, 'in_unknown_sender', { senderId, what });
+        if (this.unknownTimes.length >= UNKNOWN_ALERT_PER_HOUR && now - this.lastUnknownAlert > 3600_000) {
+            this.lastUnknownAlert = now;
+            this.o.alert?.(`telegram: ${this.unknownTimes.length} messages from unknown accounts in the last hour: possible bot token leak. Revoke it with BotFather (/revoke), then run \`dexterm telegram setup\` again.`);
+        }
+    }
+    entry(senderId, chatId, tier) { return allowed(this.o.config(), senderId, chatId, tier); }
+    limited(senderId, command) {
+        if (NEVER_RATE_LIMITED.includes(command))
+            return false;
+        const now = this.now();
+        const ts = (this.cmdTimes.get(senderId) ?? []).filter((t) => now - t < 60_000);
+        const over = ts.length >= COMMANDS_PER_MIN;
+        if (!over)
+            ts.push(now);
+        this.cmdTimes.set(senderId, ts);
+        return over;
+    }
+    async reply(chatId, lines, template) {
+        if (!lines.length)
+            return;
+        try {
+            const ref = await this.o.connector.send({ chatId }, { kind: 'text', badge: this.o.badge, lines });
+            this.o.audit.add(this.now(), 'out', { template, chatId, messageId: ref.messageId });
+        }
+        catch (e) {
+            this.o.audit.add(this.now(), 'out_failed', { template, chatId, error: e.message.slice(0, 160) });
+        }
+    }
+    async onCommand(c) {
+        if (this.dup(c.updateId)) {
+            this.o.audit.add(this.now(), 'in_duplicate', { updateId: c.updateId });
+            return;
+        }
+        this.o.audit.add(this.now(), 'in_command', { updateId: c.updateId, senderId: c.senderId, chatId: c.chatId, chatKind: c.chatKind, command: c.command, args: c.command === 'pair' ? c.args.length : c.args.map((a) => a.slice(0, 32)) });
+        if (c.command === 'pair' && this.pairing) {
+            // Another poller or a webhook on this bot means someone else holds the token and may have read the code:
+            // the window closes for everyone (A-B1). The local side starts over once the token is revoked.
+            const conflict = this.o.connector.health().conflict;
+            const r = conflict ? this.pairing.window.abort() : this.pairing.window.attempt(c.senderId, c.chatId, c.chatKind, c.args);
+            this.o.audit.add(this.now(), 'pairing', { senderId: c.senderId, chatId: c.chatId, result: r.ok ? 'code-accepted' : r.why });
+            this.pairing.onResult(r, c);
+            // The code alone does not pair: the person at the computer confirms the account first (telegram-cmd.ts).
+            if (r.ok)
+                await this.reply(c.chatId, ['Code accepted. Confirm this account on your computer to finish pairing. I never ask for keys or seed phrases.'], 'pair_code_accepted');
+            else if (r.why === 'group-chat')
+                await this.reply(c.chatId, ['Pair from a private chat with the bot, not a group.'], 'pair_refused');
+            return;
+        }
+        // Commands count only in a private chat (the allowlist pins the chat id too; this is the second fence).
+        if (c.chatKind !== 'private') {
+            this.unknown(c.senderId, `command:${c.command}:${c.chatKind}`);
+            return;
+        }
+        const tier = READ_ONLY.includes(c.command) ? 'notify' : 'control';
+        const e = this.entry(c.senderId, c.chatId, tier) ?? (tier === 'notify' ? this.entry(c.senderId, c.chatId, 'control') : null);
+        if (!e) {
+            this.unknown(c.senderId, `command:${c.command}`);
+            return;
+        }
+        if (this.limited(c.senderId, c.command)) {
+            this.o.audit.add(this.now(), 'rate_limited', { senderId: c.senderId, command: c.command });
+            await this.reply(c.chatId, ['Too many commands: wait a minute. /kill and /pause always work.'], 'rate_limited');
+            return;
+        }
+        if (!this.router) {
+            await this.reply(c.chatId, ['No runner is connected right now.'], 'no_runner');
+            return;
+        }
+        const r = this.router.handle(c);
+        this.o.audit.add(this.now(), 'command_result', { updateId: c.updateId, command: c.command, lines: r.lines.length, confirms: r.confirm?.length ?? 0 });
+        await this.reply(c.chatId, r.lines, `cmd_${c.command}`);
+        for (const cf of r.confirm ?? []) {
+            if (!this.o.broker) {
+                await this.reply(c.chatId, ['Confirm buttons are not available here: use dexterm on your computer.'], 'no_broker');
+                break;
+            }
+            await this.o.broker.confirm(cf.kind, { senderId: c.senderId, chatId: c.chatId }, cf.lines, cf.yes, cf.payload);
+        }
+    }
+    async onAction(a) {
+        if (this.dup(a.updateId)) {
+            this.o.audit.add(this.now(), 'in_duplicate', { updateId: a.updateId });
+            return;
+        }
+        const recId = /^[pc]:([A-Za-z0-9_-]{8}):/.exec(a.data)?.[1] ?? null;
+        this.o.audit.add(this.now(), 'in_action', { updateId: a.updateId, senderId: a.senderId, chatId: a.chatId, chatKind: a.chatKind, messageId: a.ref.messageId, record: recId, bytes: a.data.length });
+        // Unknown senders: dropped (counted), no toast beyond the transport's spinner end.
+        if (!this.o.config().allow.some((x) => x.senderId === a.senderId)) {
+            this.unknown(a.senderId, 'action');
+            await this.o.connector.ackAction(a, '');
+            return;
+        }
+        if (!this.o.broker) {
+            await this.o.connector.ackAction(a, 'Not available.');
+            return;
+        }
+        await this.o.broker.handleAction(a);
+    }
+    async onText(t) {
+        if (this.dup(t.updateId))
+            return;
+        this.o.audit.add(this.now(), 'in_text', { updateId: t.updateId, senderId: t.senderId, chatId: t.chatId, length: t.length, sha256: t.sha256.slice(0, 16) });
+        if (!this.entry(t.senderId, t.chatId, 'notify') && !this.entry(t.senderId, t.chatId, 'control')) {
+            this.unknown(t.senderId, 'text');
+            return;
+        }
+        await this.reply(t.chatId, ['I only take /commands and buttons; messages are never read as trades.', ...HELP_LINES.slice(1, 3)], 'text_help');
+    }
+    /** Send to every chat paired with the notify tier. */
+    async broadcast(msg, template) {
+        const t = this.o.config();
+        if (!t.tiers.includes('notify'))
+            return;
+        const chats = [...new Set(t.allow.filter((a) => a.tiers.includes('notify')).map((a) => a.chatId))];
+        for (const chatId of chats) {
+            try {
+                const ref = await this.o.connector.send({ chatId }, msg);
+                this.o.audit.add(this.now(), 'out', { template, chatId, messageId: ref.messageId, kind: msg.kind, lines: msg.kind === 'card' ? 1 : msg.lines.length });
+            }
+            catch (e) {
+                this.o.audit.add(this.now(), 'out_failed', { template, chatId, error: e.message.slice(0, 160) });
+            }
+        }
+    }
+}

package/dist/packages/autotrade/src/chat/index.js

@@ -0,0 +1,18 @@
+// dexterm autotrade chat (task-1527, AUTOTRADE-SPEC §8): notify, control and approve-to-trade through the user's own
+// bot. connector (the interface) · fake (tests) · telegram (long poll) · redact · format · config (connectors.json) ·
+// secrets (keychain / libsecret / 0600 file) · pairing · audit (hash chain) · notify · control · approvals · hub ·
+// service (what a runner host starts).
+export * from "./connector.js";
+export * from "./fake.js";
+export * from "./telegram.js";
+export * from "./redact.js";
+export * from "./format.js";
+export * from "./config.js";
+export * from "./secrets.js";
+export * from "./pairing.js";
+export * from "./audit.js";
+export * from "./notify.js";
+export * from "./control.js";
+export * from "./approvals.js";
+export * from "./hub.js";
+export * from "./service.js";