dexterm-cli 0.2.1 → 0.2.2

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

@@ -0,0 +1,530 @@
+// dexterm autotrade chat — the read-only data commands /check, /top and /signals (task-1426).
+//
+// Three commands that only READ, for the paired account in its private chat (the hub's allowlist, chat binding and
+// rate limit apply as for /status):
+//   /check <CA>    one coin: the LARP score (the `larp_check` tool's 0-100 sum of named flags) and the key risk facts
+//                  (authorities, holder concentration, LP lock, liquidity), each with the age of its data
+//   /top [N]       the first N (default 5, 1..10) of the screener's trending list, marking the runner's own coins
+//   /signals [N]   the last N (default 5, 1..20) signals the runner raised: screen matches, safety refusals, the drain
+//                  guard, stuck bags, guards, halts and fills
+// Every answer says "data, not advice". No write path: the router is built from a ReadOnlyPort only (it never sees
+// the ControlPort or the approval broker, and it returns lines, never a confirm button), and the host's port can
+// call only the read tools in READ_TOOLS. Token text (symbol, name) is untrusted: inert() makes it plain text with no
+// tappable command, mention or link; a CA is shown only after it validated as base58, and only shortened.
+import { hostname, userInfo } from 'node:os';
+import { hideSecrets, inert, pct, shortMint, usdShort } from "./format.js";
+/** The read-only commands (also in the connector's closed list). */
+export const READ_COMMANDS = ['check', 'top', 'signals'];
+/** The only data tools the host's port may call (the MCP tool layer's read tools). */
+export const READ_TOOLS = ['get_token', 'larp_check', 'screener_query'];
+export const TOP_DEFAULT = 5;
+export const TOP_MAX = 10;
+export const SIGNALS_DEFAULT = 5;
+export const SIGNALS_MAX = 20;
+/** Signals the bot keeps in memory (newest last). */
+export const SIGNAL_LOG_KEEP = 200;
+/** A Solana mint: base58 (no 0, O, I, l), 32 to 44 characters. */
+export const MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+/** task-2146: one answer stays short (Telegram's own cap is 4096; the transport clips at 3500 as a last fence). */
+export const READ_REPLY_MAX_CHARS = 1800;
+export const READ_REPLY_MAX_LINES = 26;
+/** task-2146: an answer that takes longer than this says so instead of hanging (the per-call limits are shorter). */
+export const READ_TIMEOUT_MS = 45_000;
+/** task-2146: answers that call the data sources, per chat per minute (the hub's 10 a minute per sender also applies). */
+export const READS_PER_MIN = 5;
+export const NOT_ADVICE = 'data, not advice';
+export const USAGE_CHECK = "Usage: /check <CA> (the coin's mint address: 32 to 44 base58 characters). Read-only; data, not advice.";
+export const USAGE_TOP = `Usage: /top [N] (N from 1 to ${TOP_MAX}, default ${TOP_DEFAULT}). Read-only; data, not advice.`;
+export const USAGE_SIGNALS = `Usage: /signals [N] (N from 1 to ${SIGNALS_MAX}, default ${SIGNALS_DEFAULT}). Read-only; data, not advice.`;
+const isUnavailable = (v) => !!v && typeof v === 'object' && typeof v.unavailable === 'string';
+/** "45s", "12m", "3h", "2d". */
+export function ageShort(ms) {
+    if (ms === null || ms === undefined || !Number.isFinite(ms))
+        return '?';
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.round(s / 60)}m`;
+    if (s < 48 * 3600)
+        return `${Math.round(s / 3600)}h`;
+    return `${Math.round(s / 86400)}d`;
+}
+const old = (at, now) => (at === null ? 'age unknown' : `${ageShort(now - at)} old`);
+/** `[]` → def, `['7']` → 7 clamped to 1..max, anything else → null (the usage line). */
+export function parseCount(args, def, max) {
+    if (args.length === 0)
+        return def;
+    if (args.length > 1 || !/^\d{1,4}$/.test(args[0]))
+        return null;
+    return Math.min(max, Math.max(1, Number(args[0])));
+}
+const yesNo = (v, on, off) => (v === null ? `${off.split(' ')[0]} authority unknown` : v ? on : off);
+const pctPlain = (v) => (v === null || !Number.isFinite(v) ? '?' : `${v.toFixed(1)}%`);
+// ───────────────────────────── outgoing text (task-2146) ─────────────────────────────
+/**
+ * Characters that render as nothing (or flip text direction) and that the prompt firewall does not strip: soft hyphen,
+ * combining grapheme joiner, Arabic letter mark, Hangul fillers, Mongolian separators, word joiners and invisible
+ * operators, the deprecated format characters, interlinear annotation marks and the tag block.
+ */
+const INVISIBLE = /[\u00AD\u034F\u061C\u115F\u1160\u17B4\u17B5\u180B-\u180F\u2060-\u2064\u206A-\u206F\u3164\uFFA0\uFFF9-\uFFFB]|[\u{E0000}-\u{E007F}]/gu;
+/** Half of a surrogate pair (a cut emoji): Telegram refuses the whole message when one is in it. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/**
+ * On top of inert(): what Telegram still turns into a tappable thing in a plain-text message. A bare domain
+ * ("claim-now.xyz", "t.me") gets a one-dot leader instead of its dot, a #hashtag and a $CASHTAG get look-alikes.
+ */
+export function defuse(s) {
+    return s
+        .replace(INVISIBLE, '')
+        .replace(/([\p{L}\p{N}_-])\.(?=\p{L})/gu, '$1\u2024')
+        .replace(/#/g, '\uFF03')
+        .replace(/\$(?=\p{L})/gu, '\uFF04')
+        .replace(LONE_SURROGATE, '');
+}
+/** Token or engine text for a read-only answer: inert() (secrets, paths, the prompt firewall, the cap) then defuse(). */
+export const tx = (text, max = 32, source = 'token') => defuse(inert(text, max, source));
+/** This computer's names (host, short host, login), which a read-only answer never shows. */
+export function localNames() {
+    const out = [];
+    try {
+        const h = hostname();
+        out.push(h, h.split('.')[0]);
+    }
+    catch { /* no host name */ }
+    try {
+        out.push(userInfo().username);
+    }
+    catch { /* no user */ }
+    return [...new Set(out.filter((x) => typeof x === 'string' && x.length >= 4 && !/^(localhost|root|user)$/i.test(x)))];
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Cut at a code point, never inside a surrogate pair. */
+function cut(s, max) {
+    if (s.length <= max)
+        return s;
+    let end = Math.max(1, max - 1);
+    if (/[\uD800-\uDBFF]/.test(s[end - 1] ?? ''))
+        end--;
+    return `${s.slice(0, end)}…`;
+}
+/**
+ * task-2180: dexterm's own fixed wording in the read-only answers. A computer name can be a plain word the bot itself
+ * uses (GitHub's runners log in as `runner`; a login `data` or `check` is possible too). Only for such a name, an
+ * exact fragment below that stands between prose boundaries is left as written, so "the runner holds this coin now"
+ * stays readable. Everywhere else (token text, engine and source text, errors, paths, host names) the name is hidden
+ * as before, in every case variant; a name that is not part of this wording is hidden everywhere, unchanged.
+ * A fragment missing here only means the bot's own word shows as [host]: it never shows a name.
+ */
+export const OWN_WORDING = [
+    NOT_ADVICE, 'Data, not advice', USAGE_CHECK, USAGE_TOP, USAGE_SIGNALS,
+    'The LARP score is evidence, not a verdict, and not a safety check',
+    'Too many data requests: up to', 'a minute in this chat', '/kill and /pause always work',
+    'A /check is still running: wait for its answer',
+    'Could not read this coin right now', 'Could not read the ranking right now', 'Could not read the signals right now',
+    'Nothing was guessed; try again in a minute',
+    'CHECK', 'LARP score', 'LARP score: could not be read', 'checks unread', 'check unread', 'checked',
+    'risk:', 'risk: could not be read', 'risk: the sources reported no holder/authority data for this coin',
+    'mint authority ON', 'mint authority revoked', 'mint authority unknown', 'freeze authority ON', 'freeze authority revoked', 'freeze authority unknown',
+    'top-10 holders', 'LP locked', 'rug score', 'age unknown',
+    'market: mcap', 'market: could not be read', 'liquidity', 'holders', 'coin age',
+    'the runner holds this coin now (/positions)', 'a candidate of the runner now',
+    'TOP', 'Nothing ranked right now', '/check <CA> for one coin', '1h vol', 'HELD', 'candidate',
+    'SIGNALS', 'newest first', 'No signals yet: nothing matched the screen or tripped a check since the bot came on',
+    "the screener's trending list", 'the screener returned nothing: offline, or the sources did not answer',
+    'the screener did not answer', 'no live screener here', "the runner's own coins instead", 'No ranking right now',
+    'No signals: no run has started since the bot came on',
+    'SCREEN', 'SAFETY', 'DRAIN', 'STUCK', 'WRITTEN OFF', 'GUARD', 'HALT', 'SELL', 'BUY',
+    'matched the screen', 'refused by', 'cannot sell', 'closed at realizable value', 'halted', '(paper book)',
+];
+// NO_LIVE_DATA is declared with the host side below, so the wording list is completed on first use.
+let ownWording = null;
+let ownRe = null;
+const allOwnWording = () => (ownWording ??= [...OWN_WORDING, NO_LIVE_DATA]);
+function ownWordingRe() {
+    // Prose boundaries only: a fragment glued to a host or path character ("runner.local", "runner-box", "∕runner∕")
+    // is not the bot's wording.
+    ownRe ??= new RegExp(`(?<=^|[\\s(\\["'·])(?:${[...allOwnWording()].sort((a, b) => b.length - a.length).map(escapeRe).join('|')})(?=$|[\\s)\\],;!?"'·…]|[.:](?:\\s|$))`, 'gu');
+    return ownRe;
+}
+/** `re` replaced with [host] everywhere in `s` except inside the bot's own wording (OWN_WORDING). */
+function hideOutsideOwnWording(s, re) {
+    let out = '';
+    let at = 0;
+    for (const m of s.matchAll(ownWordingRe())) {
+        out += s.slice(at, m.index).replace(re, '[host]') + m[0];
+        at = m.index + m[0].length;
+    }
+    return out + s.slice(at).replace(re, '[host]');
+}
+/**
+ * The last fence on every read-only answer: secrets and paths hidden again (an error text from a source can carry
+ * either), this computer's names replaced, invisible characters and cut surrogates dropped, and the answer capped
+ * in lines and characters (a "(cut)" line says so).
+ */
+export function finalizeReply(lines, names) {
+    const nameRes = names.filter((n) => typeof n === 'string' && n.length > 0).map((n) => ({
+        re: new RegExp(escapeRe(n), 'gi'),
+        own: allOwnWording().some((w) => w.toLowerCase().includes(n.toLowerCase())),
+    }));
+    const clean = lines.map((l) => {
+        let s = hideSecrets(String(l)).replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, '[url]');
+        for (const { re, own } of nameRes)
+            s = own ? hideOutsideOwnWording(s, re) : s.replace(re, '[host]');
+        return cut(defuse(s), 400);
+    });
+    const out = [];
+    let used = 0;
+    for (const l of clean) {
+        if (out.length >= READ_REPLY_MAX_LINES - 1 || used + l.length + 1 > READ_REPLY_MAX_CHARS - 40) {
+            out.push('(cut: the answer was too long for one message)');
+            break;
+        }
+        out.push(l);
+        used += l.length + 1;
+    }
+    return out;
+}
+export class ReadOnlyRouter {
+    port;
+    now;
+    names;
+    timeoutMs;
+    /** Chats with a /check in flight (one at a time per chat). */
+    checking = new Set();
+    readTimes = new Map();
+    limitTold = new Map();
+    constructor(port, now = Date.now, opts = {}) {
+        this.port = port;
+        this.now = now;
+        this.names = opts.hideNames ?? localNames();
+        this.timeoutMs = opts.timeoutMs ?? READ_TIMEOUT_MS;
+    }
+    /**
+     * Lines only: a read-only command never produces a button or a confirm. Every answer goes through finalizeReply.
+     * `limited`: the chat was over READS_PER_MIN (no data was read; `lines` is the once-a-minute notice, or empty).
+     */
+    async handle(c) {
+        const r = await this.route(c);
+        const lines = finalizeReply(r.lines, this.names);
+        return { ...r, lines, ...(r.failed ? { failed: lines[0] ?? '' } : {}) };
+    }
+    /** Count one data read for the chat; the answer when the chat is over its limit (null = go ahead). */
+    overLimit(chatId) {
+        const now = this.now();
+        const ts = (this.readTimes.get(chatId) ?? []).filter((t) => now - t < 60_000);
+        if (ts.length < READS_PER_MIN) {
+            ts.push(now);
+            this.readTimes.set(chatId, ts);
+            return null;
+        }
+        this.readTimes.set(chatId, ts);
+        if (now - (this.limitTold.get(chatId) ?? -Infinity) < 60_000)
+            return { lines: [], limited: true };
+        this.limitTold.set(chatId, now);
+        return { lines: [`Too many data requests: up to ${READS_PER_MIN} a minute in this chat. /kill and /pause always work.`], limited: true };
+    }
+    route(c) {
+        switch (c.command) {
+            case 'check': return this.check(c);
+            case 'top': return this.top(c);
+            case 'signals': return this.signals(c);
+            default: return Promise.resolve({ lines: [USAGE_CHECK] });
+        }
+    }
+    /** A port answer within the router's limit; a late or failed one becomes an Unavailable that says what was not read. */
+    async ask(what, p) {
+        try {
+            return await within(Promise.resolve().then(p), this.timeoutMs, what);
+        }
+        catch (e) {
+            return { unavailable: `Could not read ${what} right now (${errOf(e)}). Nothing was guessed; try again in a minute.`, failed: true };
+        }
+    }
+    async check(c) {
+        // The CA is never echoed unless it validated; an invalid one gets the usage line only.
+        if (c.args.length !== 1 || !MINT_RE.test(c.args[0]))
+            return { lines: [USAGE_CHECK] };
+        const mint = c.args[0];
+        if (this.checking.has(c.chatId))
+            return { lines: ['A /check is still running: wait for its answer.'] };
+        const lim = this.overLimit(c.chatId);
+        if (lim)
+            return lim;
+        this.checking.add(c.chatId);
+        let v;
+        try {
+            v = await this.ask('this coin', () => this.port.check(mint));
+        }
+        finally {
+            this.checking.delete(c.chatId);
+        }
+        if (isUnavailable(v))
+            return { lines: [v.unavailable], ...(v.failed ? { failed: v.unavailable } : {}) };
+        const now = this.now();
+        const sym = v.symbol ? `"${tx(v.symbol, 20)}" ` : '';
+        const name = v.name ? ` · "${tx(v.name, 32)}"` : '';
+        const lines = [`CHECK ${sym}${shortMint(v.mint)}${name} · ${NOT_ADVICE}`];
+        if (v.larp) {
+            const range = v.larp.hi !== null && v.larp.hi > v.larp.score ? ` · up to ${v.larp.hi} with ${v.larp.unread} check${v.larp.unread === 1 ? '' : 's'} unread` : '';
+            lines.push(`LARP score ${v.larp.score}/100 (${tx(v.larp.band, 12, 'engine')})${range} · checked ${ageShort(now - v.at)} ago`);
+            for (const f of v.larp.flags.slice(0, 3))
+                lines.push(`  · ${tx(f.label, 70, 'engine')} (+${f.points})`);
+        }
+        else
+            lines.push(`LARP score: could not be read${v.larpError ? ` (${tx(v.larpError, 80, 'engine')})` : ''}`);
+        if (v.audit) {
+            const a = v.audit;
+            lines.push(`risk: ${yesNo(a.mintAuth, 'mint authority ON', 'mint authority revoked')} · ${yesNo(a.freezeAuth, 'freeze authority ON', 'freeze authority revoked')} · top-10 holders ${pctPlain(a.top10Pct)} · dev ${pctPlain(a.devPct)} · LP locked ${pctPlain(a.lpLockedPct)}${a.rugScore !== null ? ` · rug score ${Math.round(a.rugScore)}` : ''} (${old(a.fetchedAt, now)})`);
+        }
+        else
+            lines.push(v.dataError ? `risk: could not be read (${tx(v.dataError, 80, 'engine')})` : 'risk: the sources reported no holder/authority data for this coin');
+        if (v.market) {
+            const m = v.market;
+            lines.push(`market: mcap ${usdShort(m.mcap)} · liquidity ${usdShort(m.liq)}${m.holders !== null ? ` · ${m.holders} holders` : ''}${m.tokenAgeSec !== null ? ` · coin age ${ageShort(m.tokenAgeSec * 1000)}` : ''} (${old(m.fetchedAt, now)})`);
+        }
+        else
+            lines.push(`market: could not be read${v.dataError ? ` (${tx(v.dataError, 80, 'engine')})` : ''}`);
+        if (v.engine)
+            lines.push(v.engine === 'held' ? 'the runner holds this coin now (/positions)' : 'a candidate of the runner now');
+        lines.push('The LARP score is evidence, not a verdict, and not a safety check. Data, not advice.');
+        return { lines };
+    }
+    async top(c) {
+        const n = parseCount(c.args, TOP_DEFAULT, TOP_MAX);
+        if (n === null)
+            return { lines: [USAGE_TOP] };
+        const lim = this.overLimit(c.chatId);
+        if (lim)
+            return lim;
+        const v = await this.ask('the ranking', () => this.port.top(n));
+        if (isUnavailable(v))
+            return { lines: [v.unavailable], ...(v.failed ? { failed: v.unavailable } : {}) };
+        if (!v.rows.length)
+            return { lines: [`Nothing ranked right now (${tx(v.source, 80, 'engine')}).`] };
+        const now = this.now();
+        const ages = v.rows.map((r) => r.fetchedAt).filter((x) => x !== null);
+        const oldest = ages.length ? Math.min(...ages) : null;
+        const rows = v.rows.slice(0, n);
+        return {
+            lines: [
+                `TOP ${rows.length} · ${tx(v.source, 80, 'engine')} (${old(oldest, now)}) · ${NOT_ADVICE}`,
+                ...rows.map((r, i) => `${i + 1}. ${r.symbol ? `"${tx(r.symbol, 16)}" ` : ''}${shortMint(r.mint)} · mcap ${usdShort(r.mcap)} · liq ${usdShort(r.liq)}${r.volH1 !== null ? ` · 1h vol ${usdShort(r.volH1)}` : ''}${r.chgH1 !== null ? ` · 1h ${pct(r.chgH1)}` : ''}${r.tokenAgeSec !== null ? ` · age ${ageShort(r.tokenAgeSec * 1000)}` : ''}${r.engine === 'held' ? ' · HELD' : r.engine === 'candidate' ? ' · candidate' : ''}`),
+                '/check <CA> for one coin.',
+            ],
+        };
+    }
+    async signals(c) {
+        const n = parseCount(c.args, SIGNALS_DEFAULT, SIGNALS_MAX);
+        if (n === null)
+            return { lines: [USAGE_SIGNALS] };
+        const lim = this.overLimit(c.chatId);
+        if (lim)
+            return lim;
+        const v = await this.ask('the signals', () => this.port.signals(n));
+        if (isUnavailable(v))
+            return { lines: [v.unavailable], ...(v.failed ? { failed: v.unavailable } : {}) };
+        if (!v.rows.length)
+            return { lines: ['No signals yet: nothing matched the screen or tripped a check since the bot came on.'] };
+        const now = this.now();
+        const rows = v.rows.slice(0, n);
+        return {
+            lines: [
+                `SIGNALS · last ${rows.length} of ${v.total} · newest first · ${NOT_ADVICE}`,
+                ...rows.map((s) => `${ageShort(now - s.at)} ago · ${tx(s.title, 14, 'engine')}${s.strategy ? ` · ${tx(s.strategy, 24, 'engine')}` : ''} · ${s.symbol ? `"${tx(s.symbol, 16)}" ` : ''}${s.mint && MINT_RE.test(s.mint) ? `${shortMint(s.mint)} ` : ''}${tx(s.text, 120, 'engine')}`),
+            ],
+        };
+    }
+}
+// ───────────────────────────── the host side ─────────────────────────────
+/** Narrow a tool layer (the MCP tools a run already has) to the read tools; any other name throws. */
+export function readOnlyCall(tools) {
+    return (tool, args) => {
+        if (!READ_TOOLS.includes(tool))
+            return Promise.reject(new Error(`not a read tool: ${String(tool).slice(0, 32)}`));
+        return tools.call(tool, args);
+    };
+}
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const bool = (v) => (typeof v === 'boolean' ? v : null);
+const rec = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null);
+const str = (v) => (typeof v === 'string' && v ? v : null);
+/** The tool layer wraps token text as `<untrusted …>text</untrusted>` (escaped): back to the raw (still untrusted) text. */
+export function untrustedText(v) {
+    const s = str(v);
+    if (!s)
+        return null;
+    const m = s.match(/^<untrusted [^>]*>([\s\S]*)<\/untrusted>$/);
+    if (!m)
+        return s;
+    return m[1].replace(/&(amp|lt|gt|quot);/g, (x) => ({ '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"' })[x] ?? x);
+}
+async function within(p, ms, what) {
+    // A plain (ref'd) timer, cleared in finally: a check that never answers still settles.
+    let timer;
+    try {
+        return await Promise.race([p, new Promise((_, rej) => { timer = setTimeout(() => rej(new Error(`${what}: no answer in ${Math.round(ms / 1000)} s`)), ms); })]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** An error as chat may show it: secrets and paths hidden, links and addresses replaced, capped (task-2146). */
+const errOf = (e) => tx(e instanceof Error ? e.message : String(e), 120, 'engine');
+/** The signals the runner raised, from its ledger as it is written (the bot's own copy, in memory). */
+export class SignalLog {
+    rows = [];
+    symbols = new Map();
+    seen = 0;
+    keep;
+    constructor(keep = SIGNAL_LOG_KEEP) { this.keep = keep; }
+    get total() { return this.seen; }
+    push(s) {
+        this.rows.push(s);
+        this.seen++;
+        if (this.rows.length > this.keep)
+            this.rows.splice(0, this.rows.length - this.keep);
+    }
+    /** Newest first. */
+    recent(n) { return this.rows.slice(-Math.max(0, n)).reverse(); }
+    /** One run ledger event → a signal when it is one (screen match, safety refusal, drain, stuck, guard, halt, fill). */
+    onLedger(e) {
+        const mint = str(e.mint);
+        const sym = str(e.symbol);
+        if (mint && sym)
+            this.symbols.set(mint, sym);
+        if (this.symbols.size > 2000) {
+            const f = this.symbols.keys().next().value;
+            if (f !== undefined)
+                this.symbols.delete(f);
+        }
+        const symbol = sym ?? (mint ? this.symbols.get(mint) ?? null : null);
+        const strategy = str(e.strategyId);
+        const s = (level, title, text) => this.push({ at: e.t, level, title, text, mint, symbol, strategy });
+        const detail = (k) => { const v = e[k]; return v === undefined || v === null ? '' : String(v); };
+        switch (e.kind) {
+            case 'candidate': {
+                const m = Array.isArray(e.matched) ? e.matched.map(String).join(', ') : '';
+                s('info', 'SCREEN', `matched the screen${m ? `: ${m}` : ''}`);
+                break;
+            }
+            case 'refused':
+                if (e.stage === 'vet')
+                    s('warn', 'SAFETY', `refused by ${detail('rule')}${detail('detail') ? `: ${detail('detail')}` : ''}`);
+                break;
+            case 'drain_guard':
+                s('alert', 'DRAIN', `${detail('reason')}${detail('detail') ? `: ${detail('detail')}` : ''}`);
+                break;
+            case 'stuck':
+                s('warn', 'STUCK', `cannot sell${detail('why') ? ` (${detail('why')})` : ''}`);
+                break;
+            case 'written_off':
+                s('warn', 'WRITTEN OFF', detail('why') || 'closed at realizable value');
+                break;
+            case 'guard':
+                s('warn', 'GUARD', `${detail('state')}${detail('effect') ? `: ${detail('effect')}` : ''}`);
+                break;
+            case 'halt':
+                s('alert', 'HALT', detail('reason') || 'halted');
+                break;
+            case 'fill': {
+                const side = detail('side');
+                const usd = num(e.usd);
+                s('info', side === 'sell' ? 'SELL' : 'BUY', `${side || 'fill'}${usd !== null ? ` ${usdShort(usd)}` : ''}${detail('reason') ? ` · ${detail('reason')}` : ''} (paper book)`);
+                break;
+            }
+            default: break;
+        }
+    }
+}
+const NO_LIVE_DATA = 'No live data here: the bot is not attached to a run on live data (no run, a replay, the stub, or offline). Start one with `dexterm autotrade run <id> --paper`.';
+/** The ReadOnlyPort of a runner host: the run's read tools and its state, nothing else. */
+export class HostReadPort {
+    d;
+    now;
+    constructor(d) { this.d = d; this.now = d.now ?? Date.now; }
+    mark(mint) {
+        const st = this.d.state();
+        if (!st)
+            return null;
+        if (st.positions.some((p) => p.mint === mint))
+            return 'held';
+        if (st.candidates.some((c) => c.mint === mint))
+            return 'candidate';
+        return null;
+    }
+    async check(mint) {
+        if (!MINT_RE.test(mint))
+            return { unavailable: USAGE_CHECK };
+        const call = this.d.call();
+        if (!call)
+            return { unavailable: NO_LIVE_DATA };
+        const t = this.d.timeoutMs ?? {};
+        const [tok, larp] = await Promise.all([
+            within(call('get_token', { mint }), t.token ?? 15_000, 'token data').catch((e) => ({ error: errOf(e) })),
+            within(call('larp_check', { mint }), t.larp ?? 25_000, 'LARP check').catch((e) => ({ error: errOf(e) })),
+        ]);
+        const at = this.now();
+        const tk = rec(tok.token);
+        const pair = rec(tok.pair);
+        const stats = rec(tok.stats);
+        const audit = rec(tok.audit);
+        const ls = rec(larp.larp_score);
+        const score = num(larp.score);
+        const flagsSrc = Array.isArray(ls?.top) && ls.top.length ? ls.top : Array.isArray(ls?.flags) ? ls.flags : [];
+        const flags = flagsSrc.map(rec).filter((x) => !!x && typeof x.label === 'string' && num(x.points) !== null).map((x) => ({ label: String(x.label), points: num(x.points) })).sort((a, b) => b.points - a.points);
+        const range = rec(ls?.range);
+        const created = num(tk?.createdAt) ?? num(pair?.createdAt);
+        const mcapRes = rec(pair?.mcapResolved);
+        return {
+            mint, at,
+            symbol: untrustedText(tk?.symbol), name: untrustedText(tk?.name),
+            larp: score === null ? null : { score, band: str(larp.band) ?? '?', hi: num(range?.hi), unread: Array.isArray(ls?.missing) ? ls.missing.length : 0, flags },
+            larpError: score === null ? str(larp.error) ?? 'no score came back' : null,
+            market: pair ? { mcap: num(mcapRes?.value) ?? num(pair.mcap), liq: num(pair.liquidityUsd), holders: num(stats?.holderCount), tokenAgeSec: created !== null ? Math.max(0, Math.round((at - created) / 1000)) : null, fetchedAt: num(pair.fetchedAt) } : null,
+            audit: audit ? { mintAuth: bool(audit.mintAuthority), freezeAuth: bool(audit.freezeAuthority), top10Pct: num(audit.top10Pct), devPct: num(audit.devPct), lpLockedPct: num(audit.lpLockedPct), rugScore: num(audit.rugScore), fetchedAt: num(audit.fetchedAt) } : null,
+            dataError: pair ? null : str(tok.error) ?? 'the sources did not answer',
+            engine: this.mark(mint),
+        };
+    }
+    async top(n) {
+        const k = Math.min(TOP_MAX, Math.max(1, Math.floor(n) || TOP_DEFAULT));
+        const call = this.d.call();
+        let why = '';
+        if (call) {
+            try {
+                const r = await within(call('screener_query', { preset: 'trending', limit: k }), this.d.timeoutMs?.top ?? 20_000, 'screener');
+                const rows = Array.isArray(r.rows) ? r.rows.map(rec).filter((x) => !!x && typeof x.mint === 'string' && MINT_RE.test(x.mint)) : [];
+                if (rows.length) {
+                    return {
+                        source: "the screener's trending list", at: this.now(),
+                        rows: rows.slice(0, k).map((x) => ({
+                            mint: String(x.mint), symbol: untrustedText(x.symbol), mcap: num(x.mcap), liq: num(x.liquidityUsd), volH1: num(x.volH1), chgH1: num(rec(x.priceChange)?.h1),
+                            tokenAgeSec: num(x.tokenAgeSec), fetchedAt: num(x.fetchedAt), engine: this.mark(String(x.mint)),
+                        })),
+                    };
+                }
+                why = 'the screener returned nothing: offline, or the sources did not answer';
+            }
+            catch (e) {
+                why = `the screener did not answer (${errOf(e)})`;
+            }
+        }
+        // No live screener: the runner's own candidates and holdings, which it ranks by nothing but time.
+        const st = this.d.state();
+        const own = st ? [...st.positions.map((p) => ({ mint: p.mint, symbol: p.symbol, engine: 'held' })), ...st.candidates.map((c) => ({ mint: c.mint, symbol: c.symbol, engine: 'candidate' }))] : [];
+        if (own.length) {
+            return {
+                source: `${why || 'no live screener here'}; the runner's own coins instead`, at: this.now(),
+                rows: own.slice(0, k).map((x) => ({ mint: x.mint, symbol: x.symbol, mcap: null, liq: null, volH1: null, chgH1: null, tokenAgeSec: null, fetchedAt: st.t, engine: x.engine })),
+            };
+        }
+        return { unavailable: why ? `No ranking right now: ${why}.` : NO_LIVE_DATA };
+    }
+    signals(n) {
+        const log = this.d.signals;
+        if (!log.total && !this.d.state())
+            return { unavailable: 'No signals: no run has started since the bot came on.' };
+        return { at: this.now(), total: log.total, rows: log.recent(Math.min(SIGNALS_MAX, Math.max(1, Math.floor(n) || SIGNALS_DEFAULT))) };
+    }
+}

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

@@ -7,6 +7,8 @@
 //   NotifyBus       the run ledger as it is written → messages
 //   HostControlPort the router's actions, through the SAME control file the CLI and the Q screen write
 //                   (autotrade/control.json, by: "chat"), the runner's live state, and the strategy store
+//   HostReadPort    task-1426: /check /top /signals from the run's read tools (setReadTools) and the signals the
+//                   runner raised (SignalLog, fed by the ledger tap); read-only, separate from HostControlPort
 // The runner never waits on chat: the bus queues, the broker answers when a tap lands, and a dead connection means
 // no entries that need an approval (UNDELIVERED = skip), never a blocked exit.
 import { riskDelta } from '../../../mcp/src/index.js';
@@ -20,6 +22,7 @@ import { ChatAudit } from "./audit.js";
 import { defaultTelegram, loadConnectors, saveConnectors } from "./config.js";
 import { ChatHub } from "./hub.js";
 import { NotifyBus } from "./notify.js";
+import { HostReadPort, SignalLog } from "./readonly.js";
 /** connectors.json re-read when it changes (a local `dexterm telegram approvals off` lands without a restart). */
 export class ConfigView {
     cached = null;
@@ -175,6 +178,10 @@ export class TelegramService {
     audit;
     config;
     port;
+    /** task-1426: the read-only data commands' port and the runner's signals. */
+    reads;
+    signals = new SignalLog();
+    readTools = null;
     o;
     now;
     ac = new AbortController();
@@ -190,7 +197,8 @@ export class TelegramService {
         const cfg = this.config.get;
         this.broker = new ApprovalBroker({ connector: o.connector, store: this.store, audit: this.audit, port: o.port, config: cfg, now: this.now, maxOpen: o.maxOpen, timers: o.timers, alert: o.alert });
         this.port = new HostControlPort({ home: o.home, runId: o.runId, state: o.state, strategy: o.strategy, config: this.config, broker: () => this.broker, onSwitch: o.onSwitch ?? (() => { }) });
-        this.hub = new ChatHub({ connector: o.connector, config: cfg, audit: this.audit, badge: badgeOf(o.port.network), broker: this.broker, port: this.port, now: this.now, alert: o.alert });
+        this.reads = new HostReadPort({ call: () => this.readTools, state: o.state, signals: this.signals, now: this.now });
+        this.hub = new ChatHub({ connector: o.connector, config: cfg, audit: this.audit, badge: badgeOf(o.port.network), broker: this.broker, port: this.port, reads: this.reads, now: this.now, alert: o.alert });
         const delays = o.retryDelaysMs ?? [1000, 4000];
         this.bus = new NotifyBus({
             badge: badgeOf(o.port.network), config: cfg, now: this.now, card: o.card, approvalCounts: (since) => this.store.countsSince(since),
@@ -229,9 +237,12 @@ export class TelegramService {
         await this.broker.sweep();
         await this.bus.tick();
     }
+    /** task-1426: the read tools of the run on live data (null when it ends, or on a replay): /check and /top read them. */
+    setReadTools(call) { this.readTools = call; }
     /** The run ledger tap: every event, as it is written. */
     onLedger = (e) => {
         this.bus.onEvent(e);
+        this.signals.onLedger(e);
         if (e.kind === 'fill' && typeof e.proposalId === 'string')
             this.broker.filled(e.proposalId);
     };