@blockrun/franklin 3.18.0 → 3.20.0

package/dist/tools/blockrun.js

@@ -0,0 +1,257 @@
+/**
+ * BlockRun primitive — the generic x402-paid gateway capability.
+ *
+ * One tool, every BlockRun endpoint. Replaces the per-API hardcoded pattern
+ * (ImageGen, VideoGen, Phone tools, etc) for new integrations. Skills in
+ * src/skills-bundled/<name>/SKILL.md describe which paths to call for which
+ * user intents; this tool just signs the x402 payment and forwards.
+ *
+ * Why the indirection: BlockRun keeps shipping new partner APIs (Surf,
+ * Phone & Voice, future ML/data partners). Hardcoding each as a fresh
+ * CapabilityHandler means a Franklin npm release per partner and a bigger
+ * tool list for the LLM to reason about. This primitive plus markdown
+ * skill files decouples API expansion from agent releases — new partners
+ * ship as a new SKILL.md, no code change.
+ *
+ * Signing pattern mirrors src/tools/modal.ts and src/phone/client.ts; we
+ * deliberately keep the copy-paste rather than refactor those into a
+ * shared module (out of scope; would touch unrelated tools).
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, USER_AGENT } from '../config.js';
+import { recordUsage } from '../stats/tracker.js';
+import { logger } from '../logger.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 120_000;
+// ─── x402 payment signing (same shape as modal.ts / phone/client.ts) ──────
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.clone().json());
+            if (body.x402 || body.accepts)
+                header = btoa(JSON.stringify(body));
+        }
+        catch { /* not JSON, no header */ }
+    }
+    return header;
+}
+async function signPayment(response, chain, endpoint, resourceDescription) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+            const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+            const feePayer = details.extra?.feePayer || details.recipient;
+            const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || resourceDescription,
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return {
+                headers: { 'PAYMENT-SIGNATURE': payload },
+                amountUsd: Number(details.amount) / 1_000_000,
+            };
+        }
+        else {
+            const wallet = getOrCreateWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired);
+            const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || resourceDescription,
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return {
+                headers: { 'PAYMENT-SIGNATURE': payload },
+                amountUsd: Number(details.amount) / 1_000_000,
+            };
+        }
+    }
+    catch (err) {
+        logger.warn(`[franklin] BlockRun payment error: ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Pull the settlement tx hash from the gateway's X-Payment-Receipt
+ * header. The X-Payment-Response header doesn't carry the amount (only
+ * { success, transaction, network, payer }), so we don't parse it here
+ * — the amount comes from what signPayment authorized in the 402 retry.
+ */
+function extractTxHash(response) {
+    return response.headers.get('x-payment-receipt');
+}
+async function callGateway(url, method, body, resourceDescription, abortSignal, timeoutMs) {
+    const start = Date.now();
+    const chain = loadChain();
+    const headers = {
+        'Accept': 'application/json',
+        'User-Agent': USER_AGENT,
+    };
+    if (method === 'POST')
+        headers['Content-Type'] = 'application/json';
+    const ctrl = new AbortController();
+    const onParentAbort = () => ctrl.abort();
+    abortSignal.addEventListener('abort', onParentAbort, { once: true });
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const payload = method === 'POST' && body !== undefined ? JSON.stringify(body) : undefined;
+        let response = await fetch(url, { method, signal: ctrl.signal, headers, body: payload });
+        let paidUsd = 0;
+        if (response.status === 402) {
+            const signed = await signPayment(response, chain, url, resourceDescription);
+            if (!signed) {
+                return {
+                    ok: false, status: 402,
+                    body: { error: 'payment signing failed' }, raw: '',
+                    paidUsd: 0, txHash: null, latencyMs: Date.now() - start,
+                };
+            }
+            paidUsd = signed.amountUsd;
+            response = await fetch(url, {
+                method, signal: ctrl.signal,
+                headers: { ...headers, ...signed.headers },
+                body: payload,
+            });
+        }
+        const txHash = extractTxHash(response);
+        // If the gateway returned 4xx after we signed, settlement was skipped
+        // server-side (per the route's "Payment was NOT charged" pattern). Don't
+        // claim a paid amount the wallet didn't actually spend.
+        if (!response.ok)
+            paidUsd = 0;
+        const raw = await response.text().catch(() => '');
+        let parsed = {};
+        try {
+            parsed = raw ? JSON.parse(raw) : {};
+        }
+        catch { /* leave as {} */ }
+        return {
+            ok: response.ok, status: response.status, body: parsed, raw,
+            paidUsd, txHash, latencyMs: Date.now() - start,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        abortSignal.removeEventListener('abort', onParentAbort);
+    }
+}
+function buildUrl(path, params) {
+    const chain = loadChain();
+    const base = API_URLS[chain]; // ends in /api
+    const clean = path.startsWith('/') ? path : `/${path}`;
+    const url = `${base}${clean}`;
+    if (!params || Object.keys(params).length === 0)
+        return url;
+    const usp = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                usp.append(key, String(v));
+        }
+        else {
+            usp.append(key, String(value));
+        }
+    }
+    const qs = usp.toString();
+    return qs ? `${url}?${qs}` : url;
+}
+function fmtUsd(n) {
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    return `$${n.toFixed(2)}`;
+}
+export const blockrunCapability = {
+    spec: {
+        name: 'BlockRun',
+        description: 'Call any BlockRun gateway endpoint. Signs an x402 USDC payment from the user wallet, retries on HTTP 402, and returns the response. ' +
+            'Use this for crypto data (Surf — markets, on-chain, social, chat), AI inference (chat / image / video / music), phone numbers and voice calls, ' +
+            'prediction markets, DeFi data, and any other API exposed under https://blockrun.ai/marketplace. ' +
+            'The path must start with "/v1/" or "/.well-known/". ' +
+            'Bundled skills like /surf-market, /surf-chain, /surf-social, /surf-chat document which endpoints to call for common workflows — read those when you are unsure which path serves the user\'s question. ' +
+            'Cost is wallet-charged automatically; the response includes the actual USD paid.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'API path under /api, starting with "/v1/" or "/.well-known/". E.g. "/v1/surf/market/fear-greed", "/v1/phone/numbers/list", "/v1/chat/completions".',
+                },
+                method: {
+                    type: 'string',
+                    enum: ['GET', 'POST'],
+                    description: 'HTTP method. Default: POST if `body` is provided, otherwise GET.',
+                },
+                params: {
+                    type: 'object',
+                    description: 'Query-string parameters. Use for GETs. E.g. { symbol: "BTC" }.',
+                },
+                body: {
+                    type: 'object',
+                    description: 'JSON body. Use for POSTs. E.g. { model: "surf-1.5", messages: [...] }.',
+                },
+                timeoutMs: {
+                    type: 'number',
+                    description: `Optional client-side timeout in ms. Default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS}.`,
+                },
+            },
+            required: ['path'],
+        },
+    },
+    concurrent: true,
+    async execute(input, ctx) {
+        const raw = input;
+        const path = typeof raw.path === 'string' ? raw.path.trim() : '';
+        if (!path) {
+            return { output: 'Error: `path` is required (e.g. "/v1/surf/market/fear-greed").', isError: true };
+        }
+        if (!/^\/(v1|\.well-known)\//.test(path)) {
+            return {
+                output: `Error: path must start with "/v1/" or "/.well-known/". Got: ${path}`,
+                isError: true,
+            };
+        }
+        const params = (raw.params && typeof raw.params === 'object') ? raw.params : undefined;
+        const body = (raw.body && typeof raw.body === 'object') ? raw.body : undefined;
+        // Method resolution: explicit > inferred from body > default GET
+        const explicitMethod = typeof raw.method === 'string' ? raw.method.toUpperCase() : '';
+        const method = explicitMethod === 'POST' || explicitMethod === 'GET'
+            ? explicitMethod
+            : (body ? 'POST' : 'GET');
+        const timeoutMs = Math.min(Math.max(1_000, typeof raw.timeoutMs === 'number' ? raw.timeoutMs : DEFAULT_TIMEOUT_MS), MAX_TIMEOUT_MS);
+        const url = buildUrl(path, method === 'GET' ? params : undefined);
+        const resourceDescription = `BlockRun ${method} ${path}`;
+        const result = await callGateway(url, method, method === 'POST' ? body : undefined, resourceDescription, ctx.abortSignal, timeoutMs);
+        // Telemetry — show in the panel Audit tab regardless of success
+        try {
+            recordUsage(`BlockRun:${path}`, 0, 0, result.paidUsd, result.latencyMs);
+        }
+        catch { /* best-effort */ }
+        if (!result.ok) {
+            const detail = typeof result.body?.error === 'string'
+                ? result.body.error
+                : `HTTP ${result.status}`;
+            const fullOutput = result.raw || JSON.stringify(result.body, null, 2);
+            return {
+                output: `BlockRun ${method} ${path} failed: ${detail} (status ${result.status}). No charge if status is 4xx pre-payment.`,
+                fullOutput,
+                isError: true,
+            };
+        }
+        const head = `BlockRun ${method} ${path} → ${fmtUsd(result.paidUsd)}${result.txHash ? ` · tx ${result.txHash.slice(0, 10)}…` : ''} · ${result.latencyMs}ms`;
+        const payload = typeof result.body === 'object' ? JSON.stringify(result.body, null, 2) : String(result.body);
+        return {
+            output: `${head}\n${payload}`,
+            fullOutput: `${head}\n${payload}`,
+        };
+    },
+};

package/dist/tools/index.js

@@ -32,6 +32,7 @@ import { base0xGaslessSwapCapability } from './zerox-gasless.js';
 import { defiLlamaProtocolsCapability, defiLlamaProtocolCapability, defiLlamaChainsCapability, defiLlamaYieldsCapability, defiLlamaPriceCapability, } from './defillama.js';
 import { predictionMarketCapability } from './prediction.js';
 import { modalCapabilities } from './modal.js';
+import { blockrunCapability } from './blockrun.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -163,6 +164,7 @@ export const allCapabilities = [
     defiLlamaYieldsCapability,
     defiLlamaPriceCapability,
     predictionMarketCapability, // Polymarket / Kalshi / matching / smart money via Predexon
+    blockrunCapability, // Generic x402-paid gateway primitive — Surf, Phone, future partners (see /surf-* skills)
     // Modal GPU sandbox tools — registered but hidden by default (not in
     // CORE_TOOL_NAMES). Agent must `ActivateTool({names:["ModalCreate",...]})`
     // before they appear in its tool inventory. High-cost ($0.40/H100 create)

package/dist/tools/trading-execute.js

@@ -9,7 +9,38 @@
  * The split mirrors OpenBB's router/engine/view layering and keeps every
  * layer testable in isolation.
  */
+import { scoreEntry } from '../trading/journal-quality.js';
+import { renderDisciplineFooter } from '../trading/journal-display.js';
 import { renderOrderBlocked, renderOrderFilled, renderPortfolio, renderPositionClosed, renderTradeHistory, windowToSince, } from './trading-views.js';
+/**
+ * Pull a `rationale` object out of the LLM's input safely. Skips fields
+ * that don't match the expected shape so a half-filled rationale is still
+ * captured (the scorer rewards completeness, doesn't require it).
+ */
+function extractRationale(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const out = {};
+    if (r.direction === 'long' || r.direction === 'short' || r.direction === 'neutral')
+        out.direction = r.direction;
+    if (typeof r.priceTarget === 'number' && r.priceTarget > 0)
+        out.priceTarget = r.priceTarget;
+    if (typeof r.stopLoss === 'number' && r.stopLoss > 0)
+        out.stopLoss = r.stopLoss;
+    if (typeof r.timeHorizon === 'string' && r.timeHorizon.trim())
+        out.timeHorizon = r.timeHorizon.trim();
+    if (typeof r.conviction === 'number' && r.conviction >= 1 && r.conviction <= 5) {
+        out.conviction = Math.round(r.conviction);
+    }
+    if (Array.isArray(r.evidence))
+        out.evidence = r.evidence.filter((x) => typeof x === 'string');
+    if (Array.isArray(r.tags))
+        out.tags = r.tags.filter((x) => typeof x === 'string');
+    if (typeof r.thesis === 'string' && r.thesis.trim())
+        out.thesis = r.thesis.trim();
+    return Object.keys(out).length ? out : undefined;
+}
 function enginePortfolio(engine) {
     return engine.deps.portfolio;
 }
@@ -44,7 +75,15 @@ export function createTradingCapabilities(deps) {
         concurrent: true,
         async execute(_input, _ctx) {
             const snap = await buildPortfolioSnapshot(engine);
-            return { output: renderPortfolio(snap, riskConfig) };
+            const base = renderPortfolio(snap, riskConfig);
+            if (!tradeLog)
+                return { output: base };
+            // Journal discipline footer — last 10 scored entries from the log.
+            // If no entries carry qualityScore yet (pre-v3.20 history or no rationale
+            // ever recorded), renderDisciplineFooter returns null and we skip silently.
+            const recent = tradeLog.recent(10);
+            const footer = renderDisciplineFooter(recent);
+            return { output: footer ? `${base}\n${footer}` : base };
         },
     };
     const tradingOpenPosition = {
@@ -53,7 +92,10 @@ export function createTradingCapabilities(deps) {
             description: 'Open (buy into) a position. Pre-trade risk checks enforce per-position and total ' +
                 'exposure caps; a blocked order returns a normal text result with the reason — the ' +
                 'agent should read it and try again with a smaller qty if appropriate. This is paper ' +
-                'trading: fills are simulated against the provided price.',
+                'trading: fills are simulated against the provided price. ' +
+                'Optionally pass a `rationale` object documenting why — direction, price target, stop, ' +
+                'time horizon, conviction, evidence, tags, thesis. The journal scores entries on ' +
+                'rationale completeness (not P&L) and surfaces the discipline trend in TradingPortfolio.',
             input_schema: {
                 type: 'object',
                 required: ['symbol', 'qty', 'priceUsd'],
@@ -61,6 +103,21 @@ export function createTradingCapabilities(deps) {
                     symbol: { type: 'string', description: 'Ticker (e.g., "BTC", "ETH")' },
                     qty: { type: 'number', description: 'Quantity in base units (e.g., 0.01 for 0.01 BTC)' },
                     priceUsd: { type: 'number', description: 'Price at which to execute, in USD' },
+                    rationale: {
+                        type: 'object',
+                        description: 'Optional — why you are opening this position. Captured in the trade journal and scored on discipline (verifiability, evidence, specificity, novelty, review).',
+                        properties: {
+                            direction: { type: 'string', enum: ['long', 'short', 'neutral'], description: 'Trade direction. For paper-trade longs use "long".' },
+                            priceTarget: { type: 'number', description: 'Expected exit price (USD).' },
+                            stopLoss: { type: 'number', description: 'Forced exit floor (USD).' },
+                            timeHorizon: { type: 'string', description: 'How long you expect to hold: "1h", "1d", "1w", "1m", "3m", etc.' },
+                            conviction: { type: 'number', description: 'How sure are you, 1 (low) to 5 (high).' },
+                            evidence: { type: 'array', items: { type: 'string' }, description: 'Sources, links, or indicator names supporting the thesis.' },
+                            tags: { type: 'array', items: { type: 'string' }, description: 'Categorization: "momentum", "macro", "mean-reversion", etc.' },
+                            thesis: { type: 'string', description: 'Free-text reasoning (≥200 chars scores best).' },
+                        },
+                        additionalProperties: false,
+                    },
                 },
                 additionalProperties: false,
             },
@@ -84,7 +141,8 @@ export function createTradingCapabilities(deps) {
                 return { output: `No-op: ${outcome.reason}` };
             }
             if (tradeLog) {
-                tradeLog.append({
+                const rationale = extractRationale(input.rationale);
+                const draftEntry = {
                     timestamp: Date.now(),
                     symbol,
                     side: 'buy',
@@ -92,7 +150,11 @@ export function createTradingCapabilities(deps) {
                     priceUsd: outcome.fill.priceUsd,
                     feeUsd: outcome.fill.feeUsd,
                     realizedPnlUsd: 0,
-                });
+                    rationale,
+                };
+                const history = tradeLog.all();
+                draftEntry.qualityScore = scoreEntry(draftEntry, history);
+                tradeLog.append(draftEntry);
             }
             if (onStateChange)
                 await onStateChange();
@@ -110,7 +172,9 @@ export function createTradingCapabilities(deps) {
             name: 'TradingClosePosition',
             description: 'Close (sell) an open position, realizing P&L against the average entry price. ' +
                 "Omit qty to flatten the position entirely; pass qty to partially reduce. Uses the " +
-                "exchange's current mark — no manual price required.",
+                "exchange's current mark — no manual price required. " +
+                'Optionally pass a `review` note documenting whether the trade hit its plan; that ' +
+                'boosts the journal discipline score for this entry.',
             input_schema: {
                 type: 'object',
                 required: ['symbol'],
@@ -120,6 +184,10 @@ export function createTradingCapabilities(deps) {
                         type: 'number',
                         description: 'Optional — partial size. Omit to close the full position.',
                     },
+                    review: {
+                        type: 'string',
+                        description: 'Optional post-trade note: did the trade hit its target / stop / hypothesis? Boosts the journal "review" score component.',
+                    },
                 },
                 additionalProperties: false,
             },
@@ -145,7 +213,8 @@ export function createTradingCapabilities(deps) {
             }
             const tradeRealized = portfolio.realizedPnlUsd - priorRealized;
             if (tradeLog) {
-                tradeLog.append({
+                const review = typeof input.review === 'string' && input.review.trim() ? input.review.trim() : undefined;
+                const draftEntry = {
                     timestamp: Date.now(),
                     symbol,
                     side: 'sell',
@@ -153,7 +222,10 @@ export function createTradingCapabilities(deps) {
                     priceUsd: outcome.fill.priceUsd,
                     feeUsd: outcome.fill.feeUsd,
                     realizedPnlUsd: tradeRealized,
-                });
+                    review,
+                };
+                draftEntry.qualityScore = scoreEntry(draftEntry, tradeLog.all());
+                tradeLog.append(draftEntry);
             }
             if (onStateChange)
                 await onStateChange();

package/dist/trading/journal-display.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Markdown footer for `TradingPortfolio` — the discipline mirror.
+ *
+ * Shows the last-N trades' average quality score and flags any component
+ * that scored below 3.0 (the threshold AI-Trader uses too). The footer
+ * is the only place the discipline metric surfaces today; future
+ * releases can drop it into the panel Audit tab too.
+ *
+ * Pure formatting; takes AggregateScore from journal-quality.ts.
+ */
+import type { TradeLogEntry } from './trade-log.js';
+/**
+ * Build the discipline footer markdown for an existing portfolio output.
+ * Returns `null` when there's nothing to show (no scored entries yet).
+ */
+export declare function renderDisciplineFooter(entries: TradeLogEntry[]): string | null;

package/dist/trading/journal-display.js

@@ -0,0 +1,53 @@
+/**
+ * Markdown footer for `TradingPortfolio` — the discipline mirror.
+ *
+ * Shows the last-N trades' average quality score and flags any component
+ * that scored below 3.0 (the threshold AI-Trader uses too). The footer
+ * is the only place the discipline metric surfaces today; future
+ * releases can drop it into the panel Audit tab too.
+ *
+ * Pure formatting; takes AggregateScore from journal-quality.ts.
+ */
+import { aggregateScores } from './journal-quality.js';
+const COMPONENT_WARN_THRESHOLD = 3.0; // out of 5
+function fmt(n) {
+    return (Math.round(n * 100) / 100).toFixed(2);
+}
+function flagFor(component) {
+    switch (component) {
+        case 'averageVerifiability': return 'most trades missing direction or price target';
+        case 'averageEvidence': return 'most trades missing thesis or sources';
+        case 'averageSpecificity': return 'few tags — trades feel generic';
+        case 'averageNovelty': return 'repeating same symbol/direction';
+        case 'averageReview': return 'no post-trade notes';
+    }
+}
+/**
+ * Build the discipline footer markdown for an existing portfolio output.
+ * Returns `null` when there's nothing to show (no scored entries yet).
+ */
+export function renderDisciplineFooter(entries) {
+    const agg = aggregateScores(entries);
+    if (!agg)
+        return null;
+    const lines = [];
+    lines.push('');
+    lines.push('### Journal discipline');
+    lines.push(`Last ${agg.count} scored trade${agg.count === 1 ? '' : 's'}: ` +
+        `**${fmt(agg.averageTotal)} / 5**`);
+    lines.push('');
+    // Each component scaled to 0–5 for display (internal is 0–1).
+    const components = [
+        { key: 'averageVerifiability', label: 'verifiability', value: agg.averageVerifiability * 5 },
+        { key: 'averageEvidence', label: 'evidence', value: agg.averageEvidence * 5 },
+        { key: 'averageSpecificity', label: 'specificity', value: agg.averageSpecificity * 5 },
+        { key: 'averageNovelty', label: 'novelty', value: agg.averageNovelty * 5 },
+        { key: 'averageReview', label: 'review', value: agg.averageReview * 5 },
+    ];
+    for (const c of components) {
+        const flagged = c.value < COMPONENT_WARN_THRESHOLD;
+        const flagText = flagged ? `  ←  ${flagFor(c.key)}` : '';
+        lines.push(`- ${c.label.padEnd(14)} ${fmt(c.value).padStart(5)}${flagText}`);
+    }
+    return lines.join('\n');
+}

package/dist/trading/journal-quality.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Journal quality scorer — non-outcome trade discipline metric.
+ *
+ * Scores each journal entry on how well it was *justified*, not whether
+ * it made money. The five components are weighted to reward the same
+ * habits a discretionary trader's playbook teaches:
+ *
+ *   verifiability (30%)  did the entry name a direction and a price target?
+ *   evidence       (25%)  did it cite sources / thesis / indicators?
+ *   specificity    (20%)  symbol, tags — not vague vibes?
+ *   novelty        (15%)  not the 4th identical revenge-trade this week?
+ *   review         (10%)  did the user write a post-trade note?
+ *
+ * The total is on a 0–5 scale, presented in the portfolio footer so the
+ * agent and the user can see the discipline curve over time.
+ *
+ * Pure function — no I/O, no clock, deterministic given inputs. Used at
+ * append time (TradeLog) and at render time (TradingPortfolio).
+ */
+import type { TradeLogEntry, QualityScore } from './trade-log.js';
+/**
+ * Score one journal entry against the prior history (used for novelty).
+ * `history` should contain entries chronologically before `entry`.
+ */
+export declare function scoreEntry(entry: TradeLogEntry, history?: TradeLogEntry[]): QualityScore;
+export interface AggregateScore {
+    count: number;
+    averageTotal: number;
+    averageVerifiability: number;
+    averageEvidence: number;
+    averageSpecificity: number;
+    averageNovelty: number;
+    averageReview: number;
+}
+/**
+ * Average the qualityScore fields across a set of entries — used by the
+ * portfolio footer to show "your last 10 trades scored 3.2 / 5 on average".
+ *
+ * Entries without a persisted qualityScore are skipped (back-compat with
+ * pre-v3.20 trades). Returns null when there's nothing scored to average.
+ */
+export declare function aggregateScores(entries: TradeLogEntry[]): AggregateScore | null;

package/dist/trading/journal-quality.js

@@ -0,0 +1,109 @@
+/**
+ * Journal quality scorer — non-outcome trade discipline metric.
+ *
+ * Scores each journal entry on how well it was *justified*, not whether
+ * it made money. The five components are weighted to reward the same
+ * habits a discretionary trader's playbook teaches:
+ *
+ *   verifiability (30%)  did the entry name a direction and a price target?
+ *   evidence       (25%)  did it cite sources / thesis / indicators?
+ *   specificity    (20%)  symbol, tags — not vague vibes?
+ *   novelty        (15%)  not the 4th identical revenge-trade this week?
+ *   review         (10%)  did the user write a post-trade note?
+ *
+ * The total is on a 0–5 scale, presented in the portfolio footer so the
+ * agent and the user can see the discipline curve over time.
+ *
+ * Pure function — no I/O, no clock, deterministic given inputs. Used at
+ * append time (TradeLog) and at render time (TradingPortfolio).
+ */
+const NOVELTY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const NOVELTY_PENALTY = 0.2; // per duplicate within window
+const EVIDENCE_KEYWORD_REGEX = /\b(rsi|macd|bollinger|sma|ema|volatility|funding|liquidation|etf|on[-\s]?chain|catalyst|earnings|tvl|because|since|due to|supports?|resistance|breakout|breakdown|divergence|oversold|overbought)\b/i;
+function clamp01(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    if (n >= 1)
+        return 1;
+    return n;
+}
+function hasIndicatorKeyword(text) {
+    if (!text)
+        return 0;
+    return EVIDENCE_KEYWORD_REGEX.test(text) ? 1 : 0;
+}
+/**
+ * Score one journal entry against the prior history (used for novelty).
+ * `history` should contain entries chronologically before `entry`.
+ */
+export function scoreEntry(entry, history = []) {
+    const r = entry.rationale;
+    // ─ verifiability: direction + priceTarget each contribute half ─
+    const verifiability = (r?.direction ? 0.5 : 0) +
+        (typeof r?.priceTarget === 'number' && r.priceTarget > 0 ? 0.5 : 0);
+    // ─ evidence: array length, thesis length, indicator keyword presence ─
+    const evidenceArrLen = Array.isArray(r?.evidence) ? r.evidence.length : 0;
+    const thesisLen = (r?.thesis ?? '').trim().length;
+    const evidence = clamp01(0.4 * Math.min(1, evidenceArrLen / 3) +
+        0.4 * Math.min(1, thesisLen / 200) +
+        0.2 * hasIndicatorKeyword(r?.thesis));
+    // ─ specificity: symbol present + tags present ─
+    const tagCount = Array.isArray(r?.tags) ? r.tags.length : 0;
+    const specificity = (entry.symbol ? 0.5 : 0) +
+        Math.min(1, tagCount / 2) * 0.5;
+    // ─ novelty: penalize same symbol + direction within 7d ─
+    const sinceCutoff = entry.timestamp - NOVELTY_WINDOW_MS;
+    const recentSameCount = history.filter((e) => e.timestamp >= sinceCutoff &&
+        e.timestamp < entry.timestamp &&
+        e.symbol === entry.symbol &&
+        (e.rationale?.direction ?? null) === (r?.direction ?? null)).length;
+    const novelty = clamp01(1 - NOVELTY_PENALTY * recentSameCount);
+    // ─ review: did the user (or the agent in a follow-up turn) annotate? ─
+    const review = entry.review && entry.review.trim().length > 0 ? 1 : 0;
+    const total = 5 * (verifiability * 0.30 +
+        evidence * 0.25 +
+        specificity * 0.20 +
+        novelty * 0.15 +
+        review * 0.10);
+    return {
+        total: Math.round(total * 100) / 100, // 2 decimal places
+        verifiability,
+        evidence,
+        specificity,
+        novelty,
+        review,
+    };
+}
+/**
+ * Average the qualityScore fields across a set of entries — used by the
+ * portfolio footer to show "your last 10 trades scored 3.2 / 5 on average".
+ *
+ * Entries without a persisted qualityScore are skipped (back-compat with
+ * pre-v3.20 trades). Returns null when there's nothing scored to average.
+ */
+export function aggregateScores(entries) {
+    const scored = entries.filter((e) => e.qualityScore != null);
+    if (scored.length === 0)
+        return null;
+    const sum = scored.reduce((acc, e) => {
+        const q = e.qualityScore;
+        return {
+            total: acc.total + q.total,
+            v: acc.v + q.verifiability,
+            e: acc.e + q.evidence,
+            s: acc.s + q.specificity,
+            n: acc.n + q.novelty,
+            r: acc.r + q.review,
+        };
+    }, { total: 0, v: 0, e: 0, s: 0, n: 0, r: 0 });
+    const n = scored.length;
+    return {
+        count: n,
+        averageTotal: sum.total / n,
+        averageVerifiability: sum.v / n,
+        averageEvidence: sum.e / n,
+        averageSpecificity: sum.s / n,
+        averageNovelty: sum.n / n,
+        averageReview: sum.r / n,
+    };
+}