dexterm-cli 0.1.5 → 0.1.7

package/dist/packages/agents/src/index.js

@@ -18,3 +18,5 @@ export * from "./bus.js";
 export * from "./spectator.js";
 export * from "./follow.js";
 export * from "./spectator-server.js";
+// task-1466 spectator v2: the agent story (phase rail, heartbeat, timeline, thoughts, PAPER trade arc).
+export * from "./story.js";

package/dist/packages/agents/src/schema.js

@@ -1,15 +1,36 @@
 // @dexterm/agents — a small, total JSON-schema checker for tool arguments (task-1345).
 //
 // Covers the subset the dexterm tool table uses: object/string/integer/number/boolean, enum, minimum,
-// maximum, maxLength, required, additionalProperties:false, nested objects. Anything the schema does
+// maximum, maxLength, required, additionalProperties:false, nested objects, and (task-1507) `free` JSON values. Anything the schema does
 // not mention is an error (schemas are closed: `additionalProperties` defaults to false for agent
 // calls even when a schema omits it). Pure and never throws.
+const FREE_DEPTH = 12;
+function freeError(v, path, depth = 0) {
+    if (depth > FREE_DEPTH)
+        return `${path}: too deeply nested`;
+    if (typeof v === 'string')
+        return /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/.test(v) ? `${path}: control characters are not allowed` : null;
+    if (v === null || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)))
+        return null;
+    if (typeof v !== 'object')
+        return `${path}: not a JSON value`;
+    for (const [k, x] of Array.isArray(v) ? v.entries() : Object.entries(v)) {
+        if (k === '__proto__' || k === 'constructor' || k === 'prototype')
+            return `${path}.${String(k)}: not allowed`;
+        const err = freeError(x, `${path}.${String(k)}`, depth + 1);
+        if (err)
+            return err;
+    }
+    return null;
+}
 const MAX_STRING = 2000;
 const MAX_DEPTH = 6;
 const MAX_KEYS = 32;
 export function validateArgs(schema, value, path = 'args', depth = 0) {
     if (depth > MAX_DEPTH)
         return `${path}: too deeply nested`;
+    if (schema?.free)
+        return value === undefined ? null : freeError(value, path);
     if (!schema)
         return value === undefined || (typeof value === 'object' && value !== null && !Array.isArray(value) && Object.keys(value).length === 0) ? null : `${path}: this tool takes no arguments`;
     const t = schema.type ?? (schema.properties ? 'object' : undefined);

package/dist/packages/agents/src/spectator.js

@@ -84,8 +84,62 @@ export function redactSpectatorEvent(ev) {
         if (out.nav.side)
             out.nav.side = redactString(out.nav.side);
     }
+    // task-1466: the detail carries mints and symbols; every string in it is scrubbed (addresses masked).
+    if (ev.detail)
+        out.detail = redactDeep(ev.detail);
     return out;
 }
+const finiteOr = (x, d = null) => (typeof x === 'number' && Number.isFinite(x) ? x : d);
+// eslint-disable-next-line no-control-regex
+const UNSAFE_RE = /[\u0000-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/g;
+const shortStr = (x, max) => (typeof x === 'string' ? x.replace(UNSAFE_RE, '').slice(0, max) : '');
+const isMintish = (x) => typeof x === 'string' && /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(x);
+/**
+ * task-1466: re-validate a detail read off the local channel (shape, types, lengths). The channel is our own
+ * server's 0600 file and token-checked, but the viewer still treats it as data: anything malformed is dropped,
+ * strings are stripped of control/bidi characters and capped, numbers must be finite. Returns null when empty.
+ */
+export function sanitizeDetail(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const r = raw;
+    const out = {};
+    if (Array.isArray(r.rows)) {
+        const rows = r.rows.slice(0, 12).flatMap((x) => {
+            const o = x;
+            return o && isMintish(o.mint) ? [{ mint: o.mint, symbol: shortStr(o.symbol, 16) || '?', chg: finiteOr(o.chg) }] : [];
+        });
+        if (rows.length)
+            out.rows = rows;
+    }
+    const c = r.coin;
+    if (c && isMintish(c.mint))
+        out.coin = { mint: c.mint, symbol: shortStr(c.symbol, 16) || null, priceUsd: finiteOr(c.priceUsd) };
+    const v = r.verdict;
+    if (v && typeof v.label === 'string' && v.label)
+        out.verdict = { label: shortStr(v.label, 18), rug: finiteOr(v.rug) };
+    const l = r.larp;
+    if (l && finiteOr(l.flags) !== null)
+        out.larp = { flags: Math.max(0, Math.min(99, Math.round(l.flags))), items: Array.isArray(l.items) ? l.items.slice(0, 6).map((s) => shortStr(s, 60)).filter(Boolean) : [] };
+    const side = (s) => (s === 'buy' || s === 'sell' ? s : null);
+    const tk = r.ticket;
+    if (tk && side(tk.side) && isMintish(tk.mint))
+        out.ticket = { side: side(tk.side), symbol: shortStr(tk.symbol, 16) || '?', mint: tk.mint, usd: finiteOr(tk.usd), fraction: finiteOr(tk.fraction) };
+    const f = r.fill;
+    if (f && side(f.side) && isMintish(f.mint) && finiteOr(f.sol) !== null && finiteOr(f.qty) !== null) {
+        out.fill = { side: side(f.side), symbol: shortStr(f.symbol, 16) || '?', mint: f.mint, sol: f.sol, qty: f.qty, priceUsd: finiteOr(f.priceUsd), impactPct: finiteOr(f.impactPct), realizedSol: finiteOr(f.realizedSol) };
+    }
+    const p = r.position;
+    if (p && isMintish(p.mint) && finiteOr(p.qty) !== null && finiteOr(p.costSol) !== null) {
+        out.position = { mint: p.mint, symbol: shortStr(p.symbol, 16) || '?', qty: p.qty, costSol: p.costSol, realizedSol: finiteOr(p.realizedSol, 0) };
+    }
+    const cp = r.caps;
+    if (cp && finiteOr(cp.perTradeUsd) !== null && finiteOr(cp.totalUsd) !== null)
+        out.caps = { perTradeUsd: cp.perTradeUsd, totalUsd: cp.totalUsd, maxPriceImpactPct: finiteOr(cp.maxPriceImpactPct) };
+    if (typeof r.refusal === 'string' && r.refusal)
+        out.refusal = shortStr(r.refusal, 40);
+    return Object.keys(out).length ? out : null;
+}
 // ---------------------------------------------------------------------------------------------------
 // Freshness: the oldest/largest `ageSec` anywhere in a tool result, so the activity panel can show a
 // "data age" like the terminal does. Deterministic, bounded depth; returns null when nothing is dated.

package/dist/packages/agents/src/story.js

@@ -0,0 +1,532 @@
+// @dexterm/agents — the agent STORY (task-1466, spectator v2). Folds the spectator event stream into what a
+// person watching an agent drive dexterm should FEEL: a phase state machine (SCANNING > VETTING > SIZING >
+// EXECUTING > HOLDING > EXITING), a heartbeat that speeds up with the call rate, a timeline of calls with result
+// chips, a short thought ribbon, the rows the agent touched, the coin in focus (verdict, LARP evidence) and the
+// PAPER trade arc (ticket → fill → hold with a live mark → exit → result card).
+//
+// Pure and deterministic: every method takes the time it should use, nothing reads a clock or does I/O, so the
+// terminal HUD, the popup and tests all see the same story. Every number is copied from an app-computed detail
+// (SpectatorDetail) or from the app's own mark price; agent text only ever reaches the thought ribbon, scrubbed.
+// Like follow.ts it has no action path: it cannot arm, sign, size, confirm or raise a cap.
+import { fmtCap, knownSupply } from '../../data/src/basis.js';
+import { maskAddress } from "./spectator.js";
+/** The rail, in the order a trade moves through it (idle is not on the rail). */
+export const STORY_RAIL = ['scanning', 'vetting', 'sizing', 'executing', 'holding', 'exiting'];
+/** How long EXECUTING / EXITING stay lit after the fill lands (the execution moment). */
+export const EXEC_HOLD_MS = 2400;
+/** A call slower than this gets an amber chip. */
+export const SLOW_MS = 2500;
+const TOUCH_TTL_MS = 30_000;
+const MAX_NODES = 48;
+const MAX_THOUGHTS = 32;
+const MAX_DECISIONS = 24;
+const MAX_TRACE = 240;
+const SCAN_TOOLS = new Set(['screener_query', 'show_in_screener', 'switch_feed', 'switch_screen', 'screen_state', 'narrative_board', 'app_state', 'set_scan']);
+const VET_TOOLS = new Set(['open_token', 'get_token', 'get_dossier', 'analyze_token', 'get_holders', 'get_trades', 'get_candles', 'rugcheck', 'get_dev_history', 'dev_history', 'larp_check', 'get_links', 'fetch_page', 'check_domain', 'check_github', 'check_x', 'chart_popup', 'rug_backtest', 'kb_lookup', 'kb_search', 'case_lookup']);
+const SIZE_TOOLS = new Set(['paper_open_ticket', 'paper_size_ticket', 'open_ticket']);
+const CHECK_OF = { get_trades: 'tape', get_candles: 'chart', get_holders: 'holders', rugcheck: 'rug', get_dev_history: 'dev', dev_history: 'dev', larp_check: 'larp', analyze_token: 'verdict', get_dossier: 'dossier', get_token: 'price' };
+const LABEL_OF = {
+    screener_query: 'scan', show_in_screener: 'screen', switch_feed: 'feed', switch_screen: 'switch', screen_state: 'look', narrative_board: 'narrative',
+    open_token: 'open', get_token: 'price', get_dossier: 'dossier', analyze_token: 'verdict', get_holders: 'holders', get_trades: 'tape', get_candles: 'chart',
+    rugcheck: 'rug', get_dev_history: 'dev', dev_history: 'dev', larp_check: 'larp', get_links: 'links', fetch_page: 'site', check_domain: 'domain', check_github: 'github', check_x: 'x',
+    paper_open_ticket: 'TICKET', paper_size_ticket: 'SIZE', paper_confirm: 'FILL', paper_close: 'CLOSE', paper_positions: 'pos', paper_pnl: 'pnl',
+};
+// eslint-disable-next-line no-control-regex
+const UNSAFE_RE = /[\u0000-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/g;
+const ADDR_RE = /[1-9A-HJ-NP-Za-km-z]{32,44}/g;
+/**
+ * Make one line of agent text fit to SHOW: strip control / bidi / zero-width characters, mask addresses, drop
+ * markdown noise, collapse whitespace and clip at a word boundary (≤ max). Returns '' for nothing worth showing.
+ * Display only: the result is never parsed, executed or fed back to anything.
+ */
+export function ribbonText(raw, max = 120) {
+    let s = String(raw ?? '').replace(UNSAFE_RE, ' ').replace(/[`*_#>|]+/g, '').replace(/\s+/g, ' ').trim();
+    s = s.replace(/[1-9A-HJ-NP-Za-km-z]{45,}/g, '[key]').replace(ADDR_RE, (m) => maskAddress(m));
+    if (!s)
+        return '';
+    if (s.length <= max)
+        return s;
+    const cut = s.slice(0, max - 1);
+    const sp = cut.lastIndexOf(' ');
+    return (sp > max * 0.6 ? cut.slice(0, sp) : cut).replace(/[,;:.\s]+$/, '') + '…';
+}
+/** Split agent prose into short, punchy ribbon lines (first sentences first). */
+export function ribbonLines(raw, max = 120, limit = 2) {
+    const flat = String(raw ?? '').replace(/\s+/g, ' ').trim();
+    if (!flat)
+        return [];
+    const parts = flat.split(/(?<=[.!?])\s+(?=[A-Z$0-9])/).map((p) => ribbonText(p, max)).filter((p) => p.length >= 3);
+    return parts.slice(0, limit);
+}
+/** One ribbon line for a whole agent message: as many leading sentences as fit in `max`, else the first clipped. */
+export function ribbonSummary(raw, max = 170) {
+    const parts = ribbonLines(raw, max, 8);
+    if (!parts.length)
+        return '';
+    let out = parts[0];
+    for (const p of parts.slice(1)) {
+        if (out.length + 1 + p.length > max)
+            break;
+        out += ' ' + p;
+    }
+    return out;
+}
+const fmtUsd = (n) => (n >= 100 ? `$${n.toFixed(0)}` : `$${n.toFixed(2)}`);
+const fmtSol = (n) => `${n >= 0 ? '+' : '−'}${Math.abs(n).toFixed(4)} SOL`;
+const pct = (n) => `${n >= 0 ? '+' : '−'}${Math.abs(n * 100).toFixed(1)}%`;
+export class AgentStory {
+    agent;
+    phase = 'idle';
+    phaseSince = 0;
+    sub = null;
+    control = 'running';
+    controlAt = 0;
+    lastCallAt = null;
+    calls = 0;
+    callTimes = [];
+    nodes = [];
+    thoughts = [];
+    touched = new Map();
+    cursor = null;
+    focus = null;
+    arc = null;
+    lastResult = null;
+    arcSeq = 0;
+    caps = null;
+    holdUntil = 0; // executing / exiting stay lit until this time
+    beats = { scanAt: null, openAt: null, fillAt: null, exitAt: null, refusedAt: null, larpAt: null };
+    symbols = new Map();
+    decisions = [];
+    score = { attempts: 0, entries: 0, closed: 0, wins: 0, realizedSol: 0 };
+    /** The agent's last words while the current focus coin was in focus. */
+    focusSaid = null;
+    constructor(agent = 'agent') { this.agent = agent; }
+    /** Fold one spectator event (raw, local). Unknown tools still land on the timeline. */
+    apply(ev) {
+        if (ev.agent)
+            this.agent = ev.agent;
+        if (ev.phase === 'control') {
+            const tool = ev.tool ?? '';
+            if (tool === 'pause')
+                this.setControl('paused', ev.t);
+            else if (tool === 'resume')
+                this.setControl('running', ev.t);
+            else if (tool === 'kick')
+                this.setControl('killed', ev.t);
+            return;
+        }
+        if (ev.phase === 'connect' || ev.phase === 'disconnect' || ev.phase === 'subscribe')
+            return;
+        if (ev.phase === 'note') {
+            if (ev.summary)
+                this.thought(ev.summary, ev.t, 'agent');
+            return;
+        }
+        const tool = ev.tool ?? '';
+        if (!tool)
+            return;
+        const t = ev.t;
+        const d = ev.detail ?? {};
+        this.calls++;
+        this.lastCallAt = t;
+        this.callTimes.push(t);
+        while (this.callTimes.length && this.callTimes[0] < t - 30_000)
+            this.callTimes.shift();
+        const refused = ev.ok === false;
+        const paper = tool.startsWith('paper_');
+        const status = refused ? (ev.phase === 'refused' || paper ? 'refused' : 'fail') : (ev.ms ?? 0) > SLOW_MS ? 'slow' : 'ok';
+        // ---- learn names
+        for (const r of d.rows ?? [])
+            this.symbols.set(r.mint, r.symbol);
+        if (d.coin?.symbol)
+            this.symbols.set(d.coin.mint, d.coin.symbol);
+        if (d.ticket)
+            this.symbols.set(d.ticket.mint, d.ticket.symbol);
+        if (d.fill)
+            this.symbols.set(d.fill.mint, d.fill.symbol);
+        if (d.caps)
+            this.caps = { ...d.caps };
+        // ---- the phase this call implies
+        let next = this.phase === 'idle' ? 'scanning' : this.phase;
+        if (SCAN_TOOLS.has(tool))
+            next = 'scanning';
+        else if (VET_TOOLS.has(tool))
+            next = 'vetting';
+        else if (SIZE_TOOLS.has(tool))
+            next = 'sizing';
+        else if (tool === 'paper_confirm')
+            next = d.fill?.side === 'sell' ? 'exiting' : 'executing';
+        else if (tool === 'paper_close')
+            next = 'exiting';
+        else if (tool === 'paper_positions' || tool === 'paper_pnl')
+            next = this.arc?.stage === 'open' ? 'holding' : this.phase === 'idle' ? 'scanning' : this.phase;
+        // ---- rows the agent looked at (the screen glows them, top to bottom)
+        if (!refused && d.rows?.length) {
+            d.rows.forEach((r, i) => this.touch(r.mint, r.symbol, t + i * 70, 'scan'));
+            this.beats.scanAt = t;
+        }
+        // ---- the coin in focus
+        const coinMint = d.coin?.mint ?? ev.nav?.mint ?? d.ticket?.mint ?? d.fill?.mint ?? null;
+        if (!refused && coinMint && (VET_TOOLS.has(tool) || paper)) {
+            const sym = this.symbols.get(coinMint) ?? maskAddress(coinMint);
+            if (!this.focus || this.focus.mint !== coinMint) {
+                if (this.focus)
+                    this.leaveFocus(t);
+                this.focus = { mint: coinMint, symbol: sym, since: t, verdict: null, larp: null, checks: [] };
+                this.focusSaid = null;
+                this.score.attempts += 1;
+            }
+            else
+                this.focus.symbol = sym;
+            const chk = CHECK_OF[tool];
+            if (chk && !this.focus.checks.includes(chk))
+                this.focus.checks.push(chk);
+            if (d.verdict)
+                this.focus.verdict = { label: d.verdict.label, rug: d.verdict.rug ?? null, at: t };
+            if (d.larp) {
+                this.focus.larp = { flags: d.larp.flags, items: [...d.larp.items], at: t };
+                this.beats.larpAt = t;
+            }
+            if (tool !== 'open_token')
+                this.touch(coinMint, sym, t, paper ? 'trade' : 'vet');
+            if (d.coin?.priceUsd != null && this.arc && this.arc.mint === coinMint && this.arc.stage === 'open')
+                this.mark(coinMint, d.coin.priceUsd, t);
+        }
+        if (tool === 'open_token' && !refused && coinMint) {
+            const sym = this.symbols.get(coinMint) ?? maskAddress(coinMint);
+            this.cursor = { mint: coinMint, symbol: sym, at: t };
+            this.touch(coinMint, sym, t, 'open');
+            this.beats.openAt = t;
+        }
+        // ---- the PAPER trade arc
+        if (paper)
+            this.foldPaper(tool, d, refused, t);
+        // ---- holding: the position stays the headline; other work shows as a sub-activity
+        const holding = this.arc?.stage === 'open';
+        if (d.ticket?.side === 'sell' && !refused)
+            next = 'exiting'; // a sell ticket is the exit being prepared
+        if ((tool === 'paper_confirm' || tool === 'paper_close') && !refused)
+            this.holdUntil = t + EXEC_HOLD_MS; // the execution moment
+        else if (refused && (next === 'executing' || next === 'exiting'))
+            next = holding ? 'holding' : 'sizing';
+        if (t < this.holdUntil && !(tool === 'paper_confirm' || tool === 'paper_close')) {
+            if (next === 'scanning' || next === 'vetting')
+                this.sub = next;
+            next = this.phase; // never cut the execution moment short
+        }
+        else if (holding && (next === 'scanning' || next === 'vetting')) {
+            this.sub = next;
+            next = 'holding';
+        }
+        else if (!holding || next === 'holding')
+            this.sub = null;
+        this.setPhase(next, t);
+        // ---- the timeline node (a repeat of the same ok read within 15 s folds into the last node: `price ×14`)
+        const lastNode = this.nodes[this.nodes.length - 1];
+        if (lastNode && lastNode.tool === tool && !paper && !SIZE_TOOLS.has(tool) && status === 'ok' && lastNode.status === 'ok' && t - lastNode.t < 15_000 && tool !== 'open_token') {
+            lastNode.count += 1;
+            lastNode.t = t;
+            lastNode.seq = ev.seq;
+            lastNode.ms = ev.ms ?? null;
+            lastNode.phase = this.phase;
+        }
+        else
+            this.nodes.push({ seq: ev.seq, t, tool, label: nodeLabel(tool, d, refused), ms: ev.ms ?? null, status, phase: this.phase, paper, count: 1 });
+        if (this.nodes.length > MAX_NODES)
+            this.nodes.splice(0, this.nodes.length - MAX_NODES);
+        // ---- the narration line (dexterm's words, shown when the agent's own thoughts are quiet)
+        const line = narrate(tool, d, ev, this.symbols, refused);
+        if (line)
+            this.thought(line, t, 'dexterm');
+    }
+    foldPaper(tool, d, refused, t) {
+        if (refused) {
+            if (tool === 'paper_open_ticket' || tool === 'paper_size_ticket' || tool === 'paper_confirm' || tool === 'paper_close') {
+                if (this.arc && this.arc.stage !== 'open' && this.arc.stage !== 'closed') {
+                    this.arc.stage = 'refused';
+                    this.arc.refusal = d.refusal ?? 'refused';
+                }
+                else if (this.arc)
+                    this.arc.refusal = d.refusal ?? 'refused';
+                this.beats.refusedAt = t;
+                const m = d.ticket?.mint ?? d.fill?.mint ?? this.arc?.mint ?? this.focus?.mint ?? null;
+                this.decide(t, 'refused', m ? this.symbols.get(m) ?? maskAddress(m) : '?', `desk refused ${tool.slice(6).replace('_', ' ')} · ${d.refusal ?? 'refused'}`);
+            }
+            return;
+        }
+        if (d.ticket) {
+            const tk = d.ticket;
+            if (tk.side === 'buy' && (!this.arc || this.arc.stage === 'closed' || this.arc.stage === 'refused' || this.arc.mint !== tk.mint)) {
+                if (this.arc?.stage === 'closed')
+                    this.lastResult = this.arc;
+                this.arc = newArc(++this.arcSeq, tk.mint, tk.symbol, t);
+            }
+            if (this.arc && this.arc.mint === tk.mint) {
+                if (tk.side === 'buy') {
+                    if (tk.usd != null) {
+                        this.arc.sizeUsd = tk.usd;
+                        if (this.arc.stage === 'ticket')
+                            this.arc.stage = 'sized';
+                    }
+                }
+                else
+                    this.arc.sellFraction = tk.fraction ?? this.arc.sellFraction;
+                this.arc.refusal = null;
+            }
+        }
+        if (d.fill) {
+            const f = d.fill;
+            if (!this.arc || this.arc.mint !== f.mint || (this.arc.stage === 'closed' && f.side === 'buy')) {
+                if (this.arc?.stage === 'closed')
+                    this.lastResult = this.arc;
+                this.arc = newArc(++this.arcSeq, f.mint, f.symbol, t);
+            }
+            const a = this.arc;
+            a.fills.push({ t, side: f.side, sol: f.sol, qty: f.qty, priceUsd: f.priceUsd, impactPct: f.impactPct, realizedSol: f.realizedSol });
+            a.refusal = null;
+            if (f.side === 'buy') {
+                const buys = a.fills.filter((x) => x.side === 'buy');
+                const priced = buys.filter((x) => x.priceUsd != null && x.qty > 0);
+                const qty = priced.reduce((s, x) => s + x.qty, 0);
+                a.entryUsd = qty > 0 ? priced.reduce((s, x) => s + x.priceUsd * x.qty, 0) / qty : null;
+                a.spentSol = buys.reduce((s, x) => s + Math.abs(x.sol), 0);
+                if (a.stage !== 'open') {
+                    this.score.entries += 1;
+                    this.decide(t, 'enter', a.symbol, `entered · ${Math.abs(f.sol).toFixed(4)} SOL${a.sizeUsd != null ? ` ($${a.sizeUsd.toFixed(2)})` : ''}${f.priceUsd != null ? ` @ ${fillAt(f.mint, f.priceUsd)}` : ''}`);
+                }
+                a.stage = 'open';
+                a.filledAt = a.filledAt ?? t;
+                this.beats.fillAt = t;
+                if (f.priceUsd != null)
+                    this.mark(f.mint, f.priceUsd, t);
+            }
+            else {
+                this.beats.exitAt = t;
+                if (f.priceUsd != null)
+                    this.mark(f.mint, f.priceUsd, t);
+                this.decide(t, 'exit', a.symbol, `sold ${fmtQty(f.qty)} → ${fmtSol(f.sol)}${f.realizedSol != null ? ` · realized ${fmtSol(f.realizedSol)}` : ''}`);
+            }
+            if (d.position && d.position.mint === f.mint)
+                a.position = { qty: d.position.qty, costSol: d.position.costSol, realizedSol: d.position.realizedSol };
+            if (f.side === 'sell' && (!d.position || d.position.qty <= 1e-12))
+                this.closeArc(t);
+        }
+    }
+    closeArc(t) {
+        const a = this.arc;
+        if (!a)
+            return;
+        a.stage = 'closed';
+        a.closedAt = t;
+        const exits = a.fills.filter((x) => x.side === 'sell');
+        const realized = a.position?.realizedSol ?? exits.reduce((s, x) => s + (x.realizedSol ?? 0), 0);
+        a.result = { realizedSol: realized, pct: a.spentSol > 0 ? realized / a.spentSol : null, holdMs: a.filledAt != null ? t - a.filledAt : 0, exits: exits.length };
+        this.score.closed += 1;
+        if (realized >= 0)
+            this.score.wins += 1;
+        this.score.realizedSol += realized;
+    }
+    /** The focus moves off a coin: log what became of it (traded coins are logged by their fills). */
+    leaveFocus(t) {
+        const f = this.focus;
+        if (!f)
+            return;
+        if (this.arc && this.arc.mint === f.mint)
+            return; // its ticket / fill / refusal is already in the log
+        if (this.decisions.some((d) => d.symbol === f.symbol && (d.kind === 'enter' || d.kind === 'exit') && d.t >= f.since))
+            return;
+        const v = f.verdict;
+        let kind = 'pass';
+        let why = f.checks.length ? `no entry after ${f.checks.length} check${f.checks.length === 1 ? '' : 's'}` : 'no entry';
+        if (v && /AVOID/i.test(v.label)) {
+            kind = 'reject';
+            why = `verdict ${v.label}${v.rug != null ? ` · rug heuristic ${(v.rug * 100).toFixed(0)}%` : ''}`;
+        }
+        else if (f.larp && f.larp.flags >= 3) {
+            kind = 'reject';
+            why = `${f.larp.flags} LARP flags${f.larp.items[0] ? ` · ${f.larp.items[0]}` : ''}`;
+        }
+        else if (v)
+            why = `verdict ${v.label}${v.rug != null ? ` · rug ${(v.rug * 100).toFixed(0)}%` : ''} · no entry`;
+        this.decide(t, kind, f.symbol, why, this.focusSaid);
+    }
+    decide(t, kind, symbol, text, said = null) {
+        this.decisions.push({ t, kind, symbol, text: ribbonText(text, 90), said: said ? ribbonText(said, 90) : null });
+        if (this.decisions.length > MAX_DECISIONS)
+            this.decisions.splice(0, this.decisions.length - MAX_DECISIONS);
+    }
+    /** The app's own mark price for a held coin (the followed terminal's live token view, or a tool result). */
+    mark(mint, priceUsd, t) {
+        const a = this.arc;
+        if (!a || a.mint !== mint || !Number.isFinite(priceUsd) || priceUsd <= 0)
+            return;
+        if (a.stage !== 'open' && a.stage !== 'closed')
+            return;
+        if (a.stage === 'closed' && a.closedAt != null && t > a.closedAt)
+            return;
+        a.mark = { priceUsd, at: t };
+        if (a.entryUsd != null && a.entryUsd > 0) {
+            const p = priceUsd / a.entryUsd - 1;
+            a.pnlPct = p;
+            if (a.peakPct === null || p > a.peakPct) {
+                a.peakPct = p;
+                a.peakAt = t;
+            }
+            const last = a.trace[a.trace.length - 1];
+            if (!last || t - last.t >= 250) {
+                a.trace.push({ t, pct: p });
+                if (a.trace.length > MAX_TRACE)
+                    a.trace.splice(0, a.trace.length - MAX_TRACE);
+            }
+            else
+                last.pct = p;
+        }
+    }
+    /** A line of the agent's own reasoning (from a thoughts feed) or a narration line. Scrubbed + clipped. */
+    thought(raw, t, source = 'agent', demo = false) {
+        const lines = [source === 'agent' ? ribbonSummary(raw, 170) : ribbonText(raw, 120)].filter(Boolean);
+        for (const text of lines) {
+            const last = this.thoughts[this.thoughts.length - 1];
+            if (last && last.text === text)
+                continue;
+            this.thoughts.push({ t, text, source, phase: this.phase, ...(demo ? { demo: true } : {}) });
+            if (source === 'agent' && this.focus)
+                this.focusSaid = text;
+        }
+        if (this.thoughts.length > MAX_THOUGHTS)
+            this.thoughts.splice(0, this.thoughts.length - MAX_THOUGHTS);
+    }
+    /** The owner's control changed (pause / take over / resume / kill). */
+    setControl(c, t) {
+        if (this.control === 'killed' && c !== 'killed')
+            return; // a kill is final for this run
+        if (this.control === c)
+            return;
+        this.control = c;
+        this.controlAt = t;
+    }
+    /** Caps the app knows from the mandate the user armed (USD). */
+    setCaps(caps) { this.caps = caps ? { ...caps } : null; }
+    touch(mint, symbol, at, kind) {
+        const prev = this.touched.get(mint);
+        const rank = { scan: 0, vet: 1, open: 2, trade: 3 };
+        if (prev && rank[prev.kind] > rank[kind] && at - prev.at < 8000) {
+            prev.at = Math.max(prev.at, at);
+            return;
+        }
+        this.touched.set(mint, { mint, symbol, at, kind });
+    }
+    setPhase(p, t) {
+        if (p !== this.phase) {
+            this.phase = p;
+            this.phaseSince = t;
+        }
+    }
+    /** Heartbeat in beats per minute: 48 at rest, faster with the call rate and in the execution moment. */
+    bpm(now) {
+        const recent = this.callTimes.filter((x) => x > now - 30_000).length;
+        let b = 48 + recent * 6;
+        if (this.phase === 'executing' || this.phase === 'exiting')
+            b += 40;
+        else if (this.phase === 'holding')
+            b += 14;
+        if (this.control !== 'running')
+            b = 0;
+        return Math.max(0, Math.min(168, Math.round(b)));
+    }
+    /** The story at `now` (phase settles after the execution moment; stale touches drop). */
+    view(now) {
+        let phase = this.phase;
+        if ((phase === 'executing' || phase === 'exiting') && now >= this.holdUntil) {
+            phase = this.arc?.stage === 'open' ? 'holding' : this.lastCallAt !== null && now - this.lastCallAt > 60_000 ? 'idle' : 'scanning';
+        }
+        const phaseSince = phase === this.phase ? this.phaseSince : this.holdUntil;
+        const touched = [...this.touched.values()].filter((r) => r.kind === 'trade' || now - r.at < TOUCH_TTL_MS);
+        const cloneArc = (a) => (a ? { ...a, fills: a.fills.map((f) => ({ ...f })), trace: a.trace.map((x) => ({ ...x })), position: a.position ? { ...a.position } : null, mark: a.mark ? { ...a.mark } : null, result: a.result ? { ...a.result } : null } : null);
+        return {
+            agent: this.agent, phase, phaseSince, sub: phase === 'holding' ? this.sub : null,
+            control: this.control, controlAt: this.controlAt, bpm: this.bpm(now), lastCallAt: this.lastCallAt, calls: this.calls,
+            nodes: this.nodes.map((n) => ({ ...n })), thoughts: this.thoughts.map((x) => ({ ...x })), touched,
+            cursor: this.cursor ? { ...this.cursor } : null,
+            focus: this.focus ? { ...this.focus, checks: [...this.focus.checks], verdict: this.focus.verdict ? { ...this.focus.verdict } : null, larp: this.focus.larp ? { ...this.focus.larp, items: [...this.focus.larp.items] } : null } : null,
+            arc: cloneArc(this.arc), lastResult: cloneArc(this.lastResult), caps: this.caps ? { ...this.caps } : null,
+            decisions: this.decisions.map((d) => ({ ...d })), score: { ...this.score }, beats: { ...this.beats },
+        };
+    }
+    /** The mint of the open PAPER position (for the app to feed its mark price), or null. */
+    get heldMint() { return this.arc?.stage === 'open' ? this.arc.mint : null; }
+}
+function newArc(id, mint, symbol, t) {
+    return { id, mint, symbol, stage: 'ticket', openedAt: t, sizeUsd: null, sellFraction: null, fills: [], position: null, entryUsd: null, spentSol: 0, mark: null, pnlPct: null, peakPct: null, peakAt: null, trace: [], filledAt: null, closedAt: null, refusal: null, result: null };
+}
+function nodeLabel(tool, d, refused) {
+    if (refused && tool.startsWith('paper_'))
+        return 'REFUSED';
+    if (tool === 'paper_confirm' && d.fill?.side === 'sell')
+        return 'SELL';
+    return (LABEL_OF[tool] ?? tool.replace(/^get_/, '').replace(/_/g, ' ')).slice(0, 10);
+}
+/** dexterm's own one-line narration of a call (numbers from the detail only). */
+function narrate(tool, d, ev, names, refused) {
+    const sym = (m) => (m ? `$${names.get(m) ?? maskAddress(m)}` : '');
+    if (refused) {
+        if (tool.startsWith('paper_'))
+            return `PAPER ${tool.slice(6).replace('_', ' ')} refused by the desk · ${d.refusal ?? 'refused'}`;
+        return `${LABEL_OF[tool] ?? tool} failed`;
+    }
+    if (d.rows?.length) {
+        const movers = d.rows.filter((r) => (r.chg ?? 0) > 0).length;
+        return `scanning ${d.rows.length} rows · ${movers} moving up`;
+    }
+    if (tool === 'open_token')
+        return `opens ${sym(d.coin?.mint ?? ev.nav?.mint)}`;
+    if (d.verdict)
+        return `verdict ${d.verdict.label}${d.verdict.rug != null ? ` · rug heuristic ${(d.verdict.rug * 100).toFixed(0)}%` : ''}`;
+    if (d.larp)
+        return `LARP evidence · ${d.larp.flags} flag${d.larp.flags === 1 ? '' : 's'}${d.larp.items[0] ? ` · ${d.larp.items[0]}` : ''}`;
+    if (d.fill) {
+        const f = d.fill;
+        if (f.side === 'buy')
+            return `PAPER FILL · ${Math.abs(f.sol).toFixed(4)} SOL → ${fmtQty(f.qty)} ${sym(f.mint)}${f.priceUsd != null ? ` @ ${fillAt(f.mint, f.priceUsd)}` : ''}`;
+        return `PAPER SELL · ${fmtQty(f.qty)} ${sym(f.mint)} → ${fmtSol(f.sol)}${f.realizedSol != null ? ` · realized ${fmtSol(f.realizedSol)}` : ''}`;
+    }
+    if (d.ticket) {
+        const tk = d.ticket;
+        if (tk.side === 'buy')
+            return tk.usd != null ? `PAPER ticket · BUY ${sym(tk.mint)} ${fmtUsd(tk.usd)}` : `PAPER ticket · BUY ${sym(tk.mint)}`;
+        return tk.fraction != null ? `PAPER ticket · SELL ${(tk.fraction * 100).toFixed(0)}% of ${sym(tk.mint)}` : `PAPER ticket · SELL ${sym(tk.mint)}`;
+    }
+    const chk = CHECK_OF[tool];
+    if (chk && d.coin)
+        return `checks ${sym(d.coin.mint)} · ${chk}`;
+    return '';
+}
+/** Compact token quantity (1.2M, 34.5K). */
+export function fmtQty(n) {
+    const a = Math.abs(n);
+    if (a >= 1e9)
+        return `${(n / 1e9).toFixed(2)}B`;
+    if (a >= 1e6)
+        return `${(n / 1e6).toFixed(2)}M`;
+    if (a >= 1e3)
+        return `${(n / 1e3).toFixed(1)}K`;
+    return n.toFixed(a >= 10 ? 0 : 2);
+}
+/**
+ * task-1537: a fill level in narration: the market cap it filled at when the supply is known without a guess (pump.fun's
+ * fixed 1B), the price beside it; else the price alone. Both numbers, so either basis reads it.
+ */
+export function fillAt(mint, priceUsd) {
+    const sup = knownSupply({ mint });
+    return sup ? `${fmtCap(priceUsd * sup.tokens)} mcap ($${fmtPx(priceUsd)})` : `$${fmtPx(priceUsd)}`;
+}
+/** A price in USD with enough significant digits for a micro-cap (0.0000531). */
+export function fmtPx(n) {
+    if (!Number.isFinite(n))
+        return '—';
+    if (n >= 1)
+        return n.toFixed(4);
+    const s = n.toPrecision(3);
+    return s.includes('e') ? n.toFixed(10).replace(/0+$/, '') : s;
+}
+export { pct as fmtSignedPct };