dexterm-cli 0.1.4 → 0.1.6

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

@@ -1,12 +1,14 @@
 // @dexterm/mcp — read-only MCP server over stdio (SPEC §5, D-09 / task-1302).
 // Every tool is read-only and schema-described; nothing in this package may build,
 // sign or send a transaction (SPEC §5.2, §6.3).
-export { runStdioServer, selfTest, McpTools, TOOLS, READ_ONLY_TOOLS, appHelpAnswer, firewall, listPrompts, getPrompt, resourceList, resourceRead, overlayCounts, userSkillPreamble, BUNDLED_KB_DIR, BUNDLED_SKILLS_DIR } from "./server.js";
+export { runStdioServer, selfTest, McpTools, TOOLS, READ_ONLY_TOOLS, PAPER_WRITE_TOOLS, PAPER_READ_TOOLS, appHelpAnswer, firewall, listPrompts, getPrompt, resourceList, resourceRead, overlayCounts, userSkillPreamble, BUNDLED_KB_DIR, BUNDLED_SKILLS_DIR } from "./server.js";
+// task-1443: resolve the paper agent desk from the running app's rendezvous (null when agent paper trading is off).
+export { resolvePaperAgentDesk, paperAgentDeskDb } from "./paper-agent.js";
 export { OverlayStore, mergeOverlay, loadBundled, checkKb, checkSkill, moneyToolMentions, isMoneyToolName, parseFrontmatter, dextermHome, userKbDir, userSkillsDir, userDir, contentJournalPath, journalContent, writeOverlayFile, resetOverlayFile, templateFor, KB_LIMITS, SKILL_LIMITS, KB_ID, SKILL_NAME, KB_RULE, MONEY_TOOLS, } from "./user-content.js";
 export { buildDossier } from "./dossier.js";
 // task-1406 + task-1421: the spectator sink the tool-call path writes to when a spectator surface is open
 // (via DEXTERM_SPECTATOR_FILE, or the ~/.dexterm rendezvous an external `dexterm mcp` client uses).
-export { recordForToolCall, maxAgeSec, fileSpectatorSinkFromEnv, resolveSpectatorSink, rendezvousPath, MCP_SPECTATOR_RENDEZVOUS, } from "./spectator-sink.js";
+export { recordForToolCall, maxAgeSec, fileSpectatorSinkFromEnv, resolveSpectatorSink, rendezvousPath, MCP_SPECTATOR_RENDEZVOUS, MCP_FOLLOW_SCREEN, FOLLOW_NAV_ACTIONS, followScreenPath, readFollowScreen, writeFollowScreen, clearFollowScreen, } from "./spectator-sink.js";
 export { loadAppHelp, searchAppHelp, getAppHelp, APP_HELP_DIR, loadDocsKb, searchDocs, getDocs, searchHelp, DOCS_KB_DIR, helpIntent } from "./app-help.js";
 /** Tool names served in v1 (SPEC §5.2 core + the task-1293 KB/case tools + the task-1314 dossier). */
 export const PLANNED_TOOLS = [
@@ -20,6 +22,7 @@ export const PLANNED_TOOLS = [
     'get_candles',
     'rugcheck',
     'get_dev_history',
+    'dev_history',
     'kb_lookup',
     'kb_search',
     'case_lookup',

package/dist/packages/mcp/src/paper-agent.js

@@ -0,0 +1,93 @@
+// task-1443 — the MCP side of agent paper trading. When the running dexterm has the spectator view open and the
+// user named an armed mandate for agent paper trading, it writes a rendezvous under ~/.dexterm; this resolves it
+// into a PaperAgentDesk the paper tools dispatch to. When the rendezvous is absent the resolver returns null and
+// the tools refuse — so agent paper trading is OFF by default and nothing here ever signs, sends or touches a
+// wallet/key.
+//
+// The desk books into the SAME paper wallet SQLite file the app uses (WAL, concurrent-safe). Its caps are
+// REPLAYED from the app's hash-chained plans journal (never read from the rendezvous), re-checked on every call
+// (mtime-cached), so a revoke or panic in the app halts the agent. It prices the mandate's USD caps from a
+// keyless SOL/USD read (fail-closed when older than 60 s), reads the control file on every mutating call
+// (pause / take-over / stop), and journals every call to its own hash chain. The only trade op it can reach is
+// the keyless swap-QUOTE + the PAPER executor (see paper-desk.ts).
+import { PaperAgentDesk, PaperWallet, PaperExecutor, SharedJournal, systemClock, readPaperAgentRendezvous, readDeskControl, rendezvousMtimeMs, fileMtimeMs, loadMandateFromJournal, plansJournalPathFor, paperAgentJournalPath, withPriority, } from '../../data/src/index.js';
+const WSOL = 'So11111111111111111111111111111111111111112';
+/** A SOL/USD read older than this prices no cap (same freshness rule as the signer's resolveSolUsd). */
+export const PAPER_SOL_USD_MAX_AGE_MS = 60_000;
+const SOL_USD_REFRESH_MS = 20_000;
+let cache = null;
+let sol = null;
+let mandateCache = null;
+function teardown() {
+    if (cache) {
+        try {
+            cache.wallet.close();
+        }
+        catch { /* ignore */ }
+        cache = null;
+    }
+    mandateCache = null;
+}
+/** Replay the mandate from the plans journal, re-read whenever the journal changes (revoke / panic / expiry). */
+function currentMandate(env, id) {
+    const path = plansJournalPathFor(env);
+    const mtimeMs = fileMtimeMs(path);
+    if (mandateCache && mandateCache.id === id && mandateCache.mtimeMs === mtimeMs)
+        return mandateCache.m;
+    const r = loadMandateFromJournal(path, id, systemClock);
+    mandateCache = { id, mtimeMs, m: r.mandate };
+    return r.mandate;
+}
+/** Keep the SOL/USD read fresh enough to price the USD caps; a failed read leaves the old one to age out. */
+async function refreshSolUsd(data) {
+    const now = Date.now();
+    if (sol && now - sol.at < SOL_USD_REFRESH_MS)
+        return;
+    try {
+        const p = (await data.jupiter.price([WSOL])).get(WSOL)?.usdPrice;
+        if (typeof p === 'number' && Number.isFinite(p) && p > 0)
+            sol = { price: p, at: Date.now() };
+    }
+    catch { /* keep the last value; it ages out */ }
+}
+/**
+ * Resolve the paper agent desk for this `dexterm mcp` process, or null when agent paper trading is disabled.
+ * Re-reads the rendezvous (mtime-cached) so enabling/disabling in the running app is picked up; the mandate
+ * and the control state are re-read inside the desk on every call, not cached across journal changes.
+ */
+export async function resolvePaperAgentDesk(data, env = process.env, opts = {}) {
+    const mtimeMs = rendezvousMtimeMs(env);
+    if (mtimeMs === 0) {
+        teardown();
+        return null;
+    } // not enabled
+    const rv = readPaperAgentRendezvous(env);
+    if (!rv) {
+        teardown();
+        return null;
+    } // present but unreadable → off (fail closed)
+    await refreshSolUsd(data);
+    if (cache && cache.mtimeMs === mtimeMs && cache.db === rv.db && cache.mandateId === rv.mandateId)
+        return cache.desk;
+    // The rendezvous changed (or first use): rebuild on the current wallet + mandate.
+    teardown();
+    const wallet = new PaperWallet({ path: rv.db, clock: systemClock });
+    const executor = new PaperExecutor(wallet, { clock: systemClock });
+    const desk = new PaperAgentDesk({
+        mandate: () => currentMandate(env, rv.mandateId),
+        wallet,
+        executor,
+        // 'high', like the human ticket (task-1387): a paper exit must not queue behind the agent's own read polling on
+        // the shared keyless `jupiter` bucket (task-1443 live run: a scale-out was refused on a 429 mid-poll).
+        quote: (req, signal) => withPriority('high', () => (opts.quoteData?.() ?? data).jupiterSwap.quote(req, signal)),
+        ...(opts.onQuoteRetry ? { onQuoteRetry: opts.onQuoteRetry } : {}),
+        solUsd: () => (sol && Date.now() - sol.at <= PAPER_SOL_USD_MAX_AGE_MS ? sol.price : null),
+        control: () => readDeskControl(env),
+        journal: new SharedJournal(paperAgentJournalPath(env), systemClock),
+        agent: rv.agent ?? 'mcp-agent',
+    });
+    cache = { mtimeMs, db: rv.db, mandateId: rv.mandateId, wallet, desk };
+    return desk;
+}
+/** Exported for tests: the current cached rendezvous db, if any. */
+export function paperAgentDeskDb() { return cache?.db ?? null; }