dexterm-cli 0.1.6 → 0.2.0

package/dist/packages/autotrade/src/report.js

@@ -0,0 +1,168 @@
+// dexterm autotrade — the daily / weekly digest (task-1654, 0.2.0 card E). Read-only over the run ledgers.
+//
+// Per strategy and mode (paper | real) over a period: closed trades, the win rate with its 95% interval (Wilson),
+// net PnL, the max drawdown of the closed-trade curve, refusals, the limits that were hit, and for real mode the
+// executor's health and the paper-vs-real fill divergence from receipts. Every digest ends with an honest sample
+// note: a handful of trades says almost nothing, and the interval shows how little.
+//
+// `dexterm autotrade report` prints it (or --json, or --telegram through the user's own bot). A run with the
+// Telegram bot on sends it by itself when the user turned a schedule on (`report --schedule daily|weekly|off`,
+// saved in $DEXTERM_HOME/autotrade/digest.json; off by default).
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readLedgerFile, runsDir, writeJsonAtomic } from "./ledger.js";
+import { localDay } from "./chat/audit.js";
+import { allOutboxSignals } from "./outbox.js";
+import { divergenceReport, readReceipts } from "./receipts.js";
+const r2 = (v) => Math.round(v * 100) / 100;
+/** The 95% Wilson score interval of k wins in n, in %. */
+export function wilson(k, n, z = 1.96) {
+    if (n <= 0)
+        return null;
+    const p = k / n;
+    const d = 1 + (z * z) / n;
+    const c = (p + (z * z) / (2 * n)) / d;
+    const h = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / d;
+    return [Math.round(Math.max(0, c - h) * 1000) / 10, Math.round(Math.min(1, c + h) * 1000) / 10];
+}
+export function periodBounds(period, now) {
+    return { from: now - (period === 'day' ? 1 : 7) * 86_400_000, to: now };
+}
+/** The digest of every run ledger with events in [from, to]. */
+export function buildDigest(home, o) {
+    const b = periodBounds(o.period, o.now);
+    const from = o.from ?? b.from;
+    const to = o.to ?? b.to;
+    const by = new Map();
+    const dir = runsDir(home);
+    const files = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.jsonl')) : [];
+    let anyReal = false;
+    for (const f of files) {
+        let ev;
+        try {
+            ev = readLedgerFile(join(dir, f));
+        }
+        catch {
+            continue;
+        }
+        const start = ev.find((e) => e.kind === 'run_start');
+        if (!start || typeof start.strategy !== 'string')
+            continue;
+        if (o.strategyId && start.strategy !== o.strategyId)
+            continue;
+        const inPeriod = ev.filter((e) => e.t >= from && e.t <= to);
+        if (!inPeriod.length)
+            continue;
+        const mode = start.mode === 'real' || start.tag === 'real-signal' ? 'real' : 'paper';
+        if (mode === 'real')
+            anyReal = true;
+        const key = `${start.strategy}|${mode}`;
+        let d = by.get(key);
+        if (!d) {
+            d = { strategyId: start.strategy, mode, runs: 0, trades: 0, wins: 0, winRatePct: null, winRateCi: null, netUsd: 0, maxDrawdownUsd: 0, refusals: 0, limitsHit: {}, clamped: {}, receipts: 0, closes: [] };
+            by.set(key, d);
+        }
+        d.runs++;
+        for (const e of inPeriod) {
+            if (e.kind === 'trade_closed') {
+                const pnl = Number(e.trade?.pnlUsd);
+                if (Number.isFinite(pnl)) {
+                    d.trades++;
+                    if (pnl > 0)
+                        d.wins++;
+                    d.netUsd += pnl;
+                    d.closes.push({ t: e.t, pnl });
+                }
+            }
+            else if (e.kind === 'refused') {
+                d.refusals++;
+                const rule = String(e.rule ?? '');
+                const m = /^(?:fill-)?(real-[a-z-]+)/.exec(rule);
+                if (m)
+                    d.limitsHit[m[1]] = (d.limitsHit[m[1]] ?? 0) + 1;
+            }
+            else if (e.kind === 'fill' && Array.isArray(e.limitClamps)) {
+                for (const c of e.limitClamps)
+                    d.clamped[c] = (d.clamped[c] ?? 0) + 1;
+            }
+            else if (e.kind === 'receipt')
+                d.receipts++;
+        }
+    }
+    const strategies = [...by.values()].map(({ closes, ...d }) => {
+        closes.sort((a, b2) => a.t - b2.t);
+        let cum = 0;
+        let peak = 0;
+        let dd = 0;
+        for (const c of closes) {
+            cum += c.pnl;
+            peak = Math.max(peak, cum);
+            dd = Math.max(dd, peak - cum);
+        }
+        return { ...d, netUsd: r2(d.netUsd), maxDrawdownUsd: r2(dd), winRatePct: d.trades ? Math.round((d.wins / d.trades) * 1000) / 10 : null, winRateCi: wilson(d.wins, d.trades) };
+    }).sort((a, b2) => a.strategyId.localeCompare(b2.strategyId) || a.mode.localeCompare(b2.mode));
+    let divergence = null;
+    if (anyReal) {
+        const sig = allOutboxSignals(home).filter((s) => s.issuedAt >= from && s.issuedAt <= to);
+        const d = divergenceReport(sig, readReceipts(home).receipts);
+        const { rows: _rows, ...rest } = d;
+        divergence = rest;
+    }
+    const n = strategies.reduce((a, s) => a + s.trades, 0);
+    const note = n === 0 ? 'no closed trades in this period'
+        : n < 30 ? `${n} closed trade(s) in total: a small sample. The win-rate intervals show how wide the truth may be; read no trend into it.`
+            : `${n} closed trades: still check the interval before trusting a win rate, and past results do not predict future ones`;
+    return { period: o.period, from, to, strategies, divergence, executor: o.executor ?? null, note };
+}
+const usd = (v) => `${v < 0 ? '-' : '+'}$${Math.abs(v).toFixed(2)}`;
+/** Plain lines (CLI and Telegram; no token text: strategy ids and engine numbers only). */
+export function digestLines(d) {
+    const out = [`dexterm ${d.period === 'day' ? 'daily' : 'weekly'} digest · ${new Date(d.from).toISOString().slice(0, 16).replace('T', ' ')} to ${new Date(d.to).toISOString().slice(0, 16).replace('T', ' ')} UTC · not financial advice`];
+    if (!d.strategies.length)
+        out.push('  no runs in this period');
+    for (const s of d.strategies) {
+        out.push(`${s.mode === 'real' ? 'REAL' : 'paper'} ${s.strategyId} · ${s.runs} run(s) · ${s.trades} trade(s)${s.trades ? ` · win ${s.winRatePct}% (95% interval ${s.winRateCi[0]}-${s.winRateCi[1]}%)` : ''} · net ${usd(s.netUsd)} · max drawdown $${s.maxDrawdownUsd.toFixed(2)}`);
+        const hit = Object.entries(s.limitsHit).map(([k, v]) => `${k} ×${v}`).join(', ');
+        const cl = Object.entries(s.clamped).map(([k, v]) => `${k} ×${v}`).join(', ');
+        out.push(`  refusals ${s.refusals}${hit ? ` · limits hit: ${hit}` : ''}${cl ? ` · clamped by: ${cl}` : ''}${s.mode === 'real' ? ` · receipts ${s.receipts}` : ''}`);
+    }
+    if (d.divergence) {
+        const v = d.divergence;
+        out.push(`paper vs real fills: ${v.receipted}/${v.trades} receipted · executed ${v.executed} · rejected ${v.rejected} · failed ${v.failed} · partial ${v.partial}${v.slippage.n ? ` · slippage vs paper median ${v.slippage.medianPct}% (p90 ${v.slippage.p90Pct}%)` : ''}${v.latency.n ? ` · latency median ${Math.round((v.latency.medianMs ?? 0) / 100) / 10} s` : ''}`);
+        out.push(`  ${v.note}`);
+    }
+    if (d.executor)
+        out.push(`executor: ${d.executor.alive === false ? 'SILENT' : d.executor.alive ? 'alive' : d.executor.lastSeenAt ? 'seen' : 'never seen'}${d.executor.silentSec !== null ? ` · last heard ${Math.round(d.executor.silentSec / 60)} min ago` : ''}${d.executor.lastReceipt ? ` · last receipt #${d.executor.lastReceipt.nonce} ${d.executor.lastReceipt.status}` : ''}`);
+    out.push(d.note);
+    return out;
+}
+// ───────────────────────────── the schedule (opt-in) ─────────────────────────────
+export const DIGEST_SCHEMA = 'dexterm-digest/1';
+export const digestStatePath = (home) => join(home, 'autotrade', 'digest.json');
+export function loadDigestState(home) {
+    try {
+        const d = JSON.parse(readFileSync(digestStatePath(home), 'utf8'));
+        if (d.schema === DIGEST_SCHEMA && ['off', 'daily', 'weekly'].includes(d.schedule))
+            return d;
+    }
+    catch { /* none */ }
+    return { schema: DIGEST_SCHEMA, schedule: 'off', lastSentDay: null, lastSentAt: null };
+}
+export function saveDigestState(home, s) {
+    mkdirSync(join(home, 'autotrade'), { recursive: true, mode: 0o700 });
+    writeJsonAtomic(digestStatePath(home), s);
+}
+/**
+ * Is a scheduled digest due? Daily: once per local day, for the day before (first check after midnight). Weekly: on
+ * a Monday, for the week before. Never twice for the same day.
+ */
+export function digestDue(s, now) {
+    if (s.schedule === 'off')
+        return null;
+    const today = localDay(now);
+    if (s.lastSentDay === today)
+        return null;
+    if (s.schedule === 'weekly' && new Date(now).getDay() !== 1)
+        return null;
+    return s.schedule === 'daily' ? 'day' : 'week';
+}

package/dist/packages/autotrade/src/runner-config.js

@@ -0,0 +1,99 @@
+// dexterm autotrade — the machine-local runner config (task-1505 AT-3, AUTOTRADE-SPEC §7.3).
+//
+// $DEXTERM_HOME/autotrade/runner.json, schema dexterm-runner/1. It says WHICH Claude account the sessions use and
+// the runner's own day caps and allowance guard. It is user data, never part of a strategy or a pack, so a
+// shared strategy can never pick an account or raise a cap. The stricter of the runner caps and the strategy
+// caps applies (`effectiveCaps`).
+//
+// The file names how to FETCH a credential (a helper command or an OS keychain item), never the credential.
+// A missing file means: the user's own default login (`native`) and the default caps below.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validate } from '../../custom/src/index.js';
+export const RUNNER_CONFIG_SCHEMA = 'dexterm-runner/1';
+export const runnerConfigPath = (home) => join(home, 'autotrade', 'runner.json');
+export const ACCOUNT_KINDS = ['native', 'oauth-token', 'config-dir', 'api-key'];
+/** §10 Q7 defaults. */
+export const DEFAULT_RUNNER_CONFIG = {
+    schema: RUNNER_CONFIG_SCHEMA,
+    account: { kind: 'native' },
+    caps: { candidateSessionsPerDay: 48, positionSessionsPerDay: 48, modelUsdPerDay: 20, turnsPerDay: 2000 },
+    allowanceGuard: { fiveHourMax: 0.6, sevenDayMax: 0.8, onLimit: 'pause-until-reset' },
+};
+const num = (min, max, int = false) => ({ type: 'number', min, max, int });
+const argv = { type: 'array', max: 16, items: { type: 'string', max: 400 } };
+const source = { oneOf: [
+        { type: 'object', additional: false, required: ['command'], props: { command: argv } },
+        { type: 'object', additional: false, required: ['keychain'], props: { keychain: { type: 'object', additional: false, required: ['service'], props: { service: { type: 'string', max: 200 }, account: { type: 'string', max: 200 } } } } },
+    ] };
+const expect = { type: 'array', max: 8, items: { type: 'string', max: 40 } };
+const SCHEMA = {
+    type: 'object', additional: false, required: ['schema'],
+    props: {
+        schema: { type: 'string', enum: [RUNNER_CONFIG_SCHEMA] },
+        account: { oneOf: [
+                { type: 'object', additional: false, required: ['kind'], props: { kind: { type: 'string', enum: ['native'] }, expectApiKeySource: expect } },
+                { type: 'object', additional: false, required: ['kind', 'source'], props: { kind: { type: 'string', enum: ['oauth-token'] }, source, expectApiKeySource: expect } },
+                { type: 'object', additional: false, required: ['kind', 'dir'], props: { kind: { type: 'string', enum: ['config-dir'] }, dir: { type: 'string', max: 500 }, expectApiKeySource: expect } },
+                { type: 'object', additional: false, required: ['kind', 'source'], props: { kind: { type: 'string', enum: ['api-key'] }, source, expectApiKeySource: expect } },
+            ] },
+        caps: { type: 'object', additional: false, props: {
+                candidateSessionsPerDay: num(0, 10_000, true), positionSessionsPerDay: num(0, 10_000, true), modelUsdPerDay: num(0, 10_000), turnsPerDay: num(0, 1_000_000, true),
+            } },
+        allowanceGuard: { type: 'object', additional: false, props: {
+                fiveHourMax: num(0, 1), sevenDayMax: num(0, 1), onLimit: { type: 'string', enum: ['pause-until-reset'] },
+            } },
+        load: { type: 'object', additional: false, props: {
+                pauseAboveLoad1m: num(0, 1000), resumeBelowLoad1m: num(0, 1000), sustainSec: num(0, 86_400, true),
+                busyProcs: { type: 'array', max: 32, items: { type: 'string', max: 200 } },
+            } },
+        disk: { type: 'object', additional: false, props: { minFreeGb: num(0, 100_000) } },
+    },
+};
+/** Validate a parsed runner.json and fill the defaults. */
+export function parseRunnerConfig(doc, path = 'runner.json') {
+    const errs = validate(SCHEMA, doc, '');
+    if (errs.length)
+        return { ok: false, errors: errs.map((e) => `${e.path || '/'} ${e.msg}`), path };
+    const d = doc;
+    const errors = [];
+    if (d.account?.kind === 'config-dir' && !d.account.dir.startsWith('/'))
+        errors.push('/account/dir must be an absolute path');
+    if (d.account && 'source' in d.account && 'command' in d.account.source && d.account.source.command.length === 0)
+        errors.push('/account/source/command is empty');
+    if (errors.length)
+        return { ok: false, errors, path };
+    const config = {
+        schema: RUNNER_CONFIG_SCHEMA,
+        account: d.account ?? DEFAULT_RUNNER_CONFIG.account,
+        caps: { ...DEFAULT_RUNNER_CONFIG.caps, ...d.caps },
+        allowanceGuard: { ...DEFAULT_RUNNER_CONFIG.allowanceGuard, ...d.allowanceGuard },
+        ...(d.load ? { load: d.load } : {}),
+        ...(d.disk ? { disk: d.disk } : {}),
+    };
+    return { ok: true, config, source: 'file', path };
+}
+export function loadRunnerConfig(home) {
+    const path = runnerConfigPath(home);
+    if (!existsSync(path))
+        return { ok: true, config: DEFAULT_RUNNER_CONFIG, source: 'default', path };
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        return { ok: false, errors: [`not JSON: ${e.message}`], path };
+    }
+    return parseRunnerConfig(doc, path);
+}
+export function effectiveCaps(s, c) {
+    return {
+        maxSessions: s.agent.maxSessions,
+        budgetUsdPerSession: s.agent.budgetUsdPerSession,
+        modelUsdPerDay: Math.min(s.agent.budgetUsdPerDay, c.caps.modelUsdPerDay),
+        candidateSessionsPerDay: c.caps.candidateSessionsPerDay,
+        positionSessionsPerDay: c.caps.positionSessionsPerDay,
+        turnsPerDay: c.caps.turnsPerDay,
+        maxTurnsPerSession: s.agent.maxTurns,
+    };
+}