@blockrun/franklin 3.7.10 → 3.8.0

package/dist/trading/portfolio.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Paper-trading Portfolio.
+ *
+ * Tracks cash, positions, and P&L as the agent executes trades. Pure in-memory
+ * math — an Exchange (mock or real) produces Fill events; Portfolio applies
+ * them. Persistence is handled separately in store.ts so tests don't touch disk.
+ *
+ * This is the execution substrate for Franklin's Trading Agent vertical —
+ * the first place where "the AI agent with a wallet" actually makes autonomous
+ * economic decisions and carries real P&L. No live-exchange integration here
+ * yet; MockExchange (mock-exchange.ts) gives deterministic fills for testing,
+ * and a real ExchangeClient adapter can be dropped in later against the same
+ * Fill contract.
+ */
+export type Side = 'buy' | 'sell';
+export interface Fill {
+    symbol: string;
+    side: Side;
+    qty: number;
+    priceUsd: number;
+    feeUsd?: number;
+}
+export interface Position {
+    symbol: string;
+    qty: number;
+    avgPriceUsd: number;
+}
+export interface PortfolioOptions {
+    startingCashUsd: number;
+}
+export interface MarketSnapshot {
+    equityUsd: number;
+    cashUsd: number;
+    unrealizedPnlUsd: number;
+    realizedPnlUsd: number;
+    positions: Array<Position & {
+        markUsd: number;
+        unrealizedPnlUsd: number;
+    }>;
+}
+export declare class Portfolio {
+    cashUsd: number;
+    realizedPnlUsd: number;
+    private positions;
+    constructor(opts: PortfolioOptions);
+    getPosition(symbol: string): Position | undefined;
+    listPositions(): Position[];
+    /** Serializable snapshot for persistence; paired with `restore()`. */
+    snapshot(): {
+        cashUsd: number;
+        realizedPnlUsd: number;
+        positions: Position[];
+    };
+    /** Rehydrate state from a prior snapshot; overwrites all current fields. */
+    restore(snap: {
+        cashUsd: number;
+        realizedPnlUsd: number;
+        positions: Position[];
+    }): void;
+    applyFill(fill: Fill): void;
+    /**
+     * Value the portfolio against a live price table. Callers supply the marks
+     * (e.g. from TradingSignal or a live feed) so this stays pure and testable.
+     * Symbols with no mark are valued at avgPriceUsd (zero unrealized P&L).
+     */
+    markToMarket(priceTable: Record<string, number>): MarketSnapshot;
+}

package/dist/trading/portfolio.js

@@ -0,0 +1,106 @@
+/**
+ * Paper-trading Portfolio.
+ *
+ * Tracks cash, positions, and P&L as the agent executes trades. Pure in-memory
+ * math — an Exchange (mock or real) produces Fill events; Portfolio applies
+ * them. Persistence is handled separately in store.ts so tests don't touch disk.
+ *
+ * This is the execution substrate for Franklin's Trading Agent vertical —
+ * the first place where "the AI agent with a wallet" actually makes autonomous
+ * economic decisions and carries real P&L. No live-exchange integration here
+ * yet; MockExchange (mock-exchange.ts) gives deterministic fills for testing,
+ * and a real ExchangeClient adapter can be dropped in later against the same
+ * Fill contract.
+ */
+export class Portfolio {
+    cashUsd;
+    realizedPnlUsd = 0;
+    positions = new Map();
+    constructor(opts) {
+        this.cashUsd = opts.startingCashUsd;
+    }
+    getPosition(symbol) {
+        return this.positions.get(symbol);
+    }
+    listPositions() {
+        return [...this.positions.values()];
+    }
+    /** Serializable snapshot for persistence; paired with `restore()`. */
+    snapshot() {
+        return {
+            cashUsd: this.cashUsd,
+            realizedPnlUsd: this.realizedPnlUsd,
+            positions: this.listPositions().map((p) => ({ ...p })),
+        };
+    }
+    /** Rehydrate state from a prior snapshot; overwrites all current fields. */
+    restore(snap) {
+        this.cashUsd = snap.cashUsd;
+        this.realizedPnlUsd = snap.realizedPnlUsd;
+        this.positions.clear();
+        for (const p of snap.positions)
+            this.positions.set(p.symbol, { ...p });
+    }
+    applyFill(fill) {
+        const fee = fill.feeUsd ?? 0;
+        const notional = fill.qty * fill.priceUsd;
+        if (fill.side === 'buy') {
+            const existing = this.positions.get(fill.symbol);
+            if (!existing) {
+                this.positions.set(fill.symbol, {
+                    symbol: fill.symbol,
+                    qty: fill.qty,
+                    avgPriceUsd: fill.priceUsd,
+                });
+            }
+            else {
+                // Weighted-average price update.
+                const totalQty = existing.qty + fill.qty;
+                const totalCost = existing.qty * existing.avgPriceUsd + notional;
+                existing.qty = totalQty;
+                existing.avgPriceUsd = totalCost / totalQty;
+            }
+            this.cashUsd -= notional + fee;
+        }
+        else {
+            // sell: close or reduce existing position, realize P&L against avg price
+            const existing = this.positions.get(fill.symbol);
+            if (!existing) {
+                throw new Error(`Cannot sell ${fill.symbol}: no open position`);
+            }
+            if (fill.qty > existing.qty + 1e-12) {
+                throw new Error(`Cannot sell ${fill.qty} ${fill.symbol}: only ${existing.qty} held`);
+            }
+            const realized = fill.qty * (fill.priceUsd - existing.avgPriceUsd) - fee;
+            this.realizedPnlUsd += realized;
+            existing.qty -= fill.qty;
+            this.cashUsd += notional - fee;
+            if (existing.qty <= 1e-12) {
+                this.positions.delete(fill.symbol);
+            }
+        }
+    }
+    /**
+     * Value the portfolio against a live price table. Callers supply the marks
+     * (e.g. from TradingSignal or a live feed) so this stays pure and testable.
+     * Symbols with no mark are valued at avgPriceUsd (zero unrealized P&L).
+     */
+    markToMarket(priceTable) {
+        let unrealized = 0;
+        let marketValue = 0;
+        const positions = this.listPositions().map((p) => {
+            const mark = priceTable[p.symbol] ?? p.avgPriceUsd;
+            const pnl = p.qty * (mark - p.avgPriceUsd);
+            unrealized += pnl;
+            marketValue += p.qty * mark;
+            return { ...p, markUsd: mark, unrealizedPnlUsd: pnl };
+        });
+        return {
+            equityUsd: this.cashUsd + marketValue,
+            cashUsd: this.cashUsd,
+            unrealizedPnlUsd: unrealized,
+            realizedPnlUsd: this.realizedPnlUsd,
+            positions,
+        };
+    }
+}

package/dist/trading/risk.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RiskEngine — pre-trade guardrails the agent must clear before an order
+ * touches the exchange. Pure function style: the engine holds only config;
+ * Portfolio state is passed in per call so the same engine is reusable.
+ *
+ * Guardrails enforced (MVP):
+ *  - Per-position cap (USD notional any single symbol may hold)
+ *  - Total exposure cap (sum of all open positions' notional)
+ *  - Cash sufficiency (can't buy what you can't pay for)
+ *  - Sell integrity handled by Portfolio itself (no open position → throws)
+ *
+ * Exit orders (sells of existing positions) bypass exposure caps — a paranoid
+ * cap could otherwise trap the agent in a losing position it wants to exit.
+ */
+import type { Portfolio, Side } from './portfolio.js';
+export interface RiskConfig {
+    maxPositionUsd: number;
+    maxTotalExposureUsd: number;
+}
+export interface OrderRequest {
+    symbol: string;
+    side: Side;
+    qty: number;
+    priceUsd: number;
+}
+export interface RiskDecision {
+    allowed: boolean;
+    reason?: string;
+}
+export declare class RiskEngine {
+    private config;
+    constructor(config: RiskConfig);
+    check(portfolio: Portfolio, order: OrderRequest): RiskDecision;
+}

package/dist/trading/risk.js

@@ -0,0 +1,64 @@
+/**
+ * RiskEngine — pre-trade guardrails the agent must clear before an order
+ * touches the exchange. Pure function style: the engine holds only config;
+ * Portfolio state is passed in per call so the same engine is reusable.
+ *
+ * Guardrails enforced (MVP):
+ *  - Per-position cap (USD notional any single symbol may hold)
+ *  - Total exposure cap (sum of all open positions' notional)
+ *  - Cash sufficiency (can't buy what you can't pay for)
+ *  - Sell integrity handled by Portfolio itself (no open position → throws)
+ *
+ * Exit orders (sells of existing positions) bypass exposure caps — a paranoid
+ * cap could otherwise trap the agent in a losing position it wants to exit.
+ */
+export class RiskEngine {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    check(portfolio, order) {
+        // Sells of existing positions are always permitted; exposure caps are
+        // entry-side only, and Portfolio.applyFill enforces that we don't sell
+        // more than we hold.
+        if (order.side === 'sell') {
+            const pos = portfolio.getPosition(order.symbol);
+            if (!pos) {
+                return { allowed: false, reason: `No open ${order.symbol} position to sell` };
+            }
+            return { allowed: true };
+        }
+        const notional = order.qty * order.priceUsd;
+        if (notional > portfolio.cashUsd) {
+            return {
+                allowed: false,
+                reason: `Insufficient cash: order needs $${notional.toFixed(2)} but only $${portfolio.cashUsd.toFixed(2)} available`,
+            };
+        }
+        // Projected position value after fill.
+        const existing = portfolio.getPosition(order.symbol);
+        const projectedPositionUsd = (existing ? existing.qty * order.priceUsd : 0) + notional;
+        if (projectedPositionUsd > this.config.maxPositionUsd) {
+            return {
+                allowed: false,
+                reason: `Exceeds per-position cap: projected $${projectedPositionUsd.toFixed(2)} > cap $${this.config.maxPositionUsd.toFixed(2)}`,
+            };
+        }
+        // Projected total exposure after fill. Marks all other positions at
+        // their avg price (live marks would be nicer, but the engine is
+        // intentionally pure and doesn't fetch).
+        let otherExposure = 0;
+        for (const p of portfolio.listPositions()) {
+            if (p.symbol !== order.symbol)
+                otherExposure += p.qty * p.avgPriceUsd;
+        }
+        const projectedTotalUsd = otherExposure + projectedPositionUsd;
+        if (projectedTotalUsd > this.config.maxTotalExposureUsd) {
+            return {
+                allowed: false,
+                reason: `Exceeds total exposure cap: projected $${projectedTotalUsd.toFixed(2)} > cap $${this.config.maxTotalExposureUsd.toFixed(2)}`,
+            };
+        }
+        return { allowed: true };
+    }
+}

package/dist/trading/store.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Portfolio persistence. Stored as JSON alongside the rest of Franklin's
+ * per-user state under `~/.blockrun/portfolio.json` by default. Read/write
+ * errors never throw — a missing or corrupt file just returns `null` so the
+ * agent can fall back to a fresh portfolio rather than refusing to start.
+ */
+import { Portfolio } from './portfolio.js';
+export declare function savePortfolio(pf: Portfolio, filePath: string): void;
+export declare function loadPortfolio(filePath: string): Portfolio | null;

package/dist/trading/store.js

@@ -0,0 +1,32 @@
+/**
+ * Portfolio persistence. Stored as JSON alongside the rest of Franklin's
+ * per-user state under `~/.blockrun/portfolio.json` by default. Read/write
+ * errors never throw — a missing or corrupt file just returns `null` so the
+ * agent can fall back to a fresh portfolio rather than refusing to start.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { Portfolio } from './portfolio.js';
+export function savePortfolio(pf, filePath) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(pf.snapshot(), null, 2), 'utf-8');
+}
+export function loadPortfolio(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+        if (typeof raw?.cashUsd !== 'number' ||
+            typeof raw?.realizedPnlUsd !== 'number' ||
+            !Array.isArray(raw?.positions)) {
+            return null;
+        }
+        const pf = new Portfolio({ startingCashUsd: 0 });
+        pf.restore(raw);
+        return pf;
+    }
+    catch {
+        // Corrupt JSON — start fresh rather than crash.
+        return null;
+    }
+}

package/dist/trading/trade-log.d.ts

@@ -0,0 +1,39 @@
+/**
+ * TradeLog — JSONL persistent record of every fill the agent executes.
+ *
+ * Purpose: cross-session P&L memory. The Portfolio snapshot tells you
+ * current state; the TradeLog tells you how you got there. This is the
+ * load-bearing surface for answers to questions like:
+ *   - "What was my best / worst trade this week?"
+ *   - "Am I up or down over the last 30 days?"
+ *   - "How many times did I flip BTC in the last session?"
+ *
+ * Claude Code and Cursor can't answer any of these — they have no
+ * persistent economic memory across sessions. Franklin can.
+ *
+ * Format: one JSON object per line, append-only. Reads parse lazily and
+ * skip malformed lines rather than crash, so a partial write from a
+ * prior crash never bricks the log.
+ */
+import type { Side } from './portfolio.js';
+export interface TradeLogEntry {
+    timestamp: number;
+    symbol: string;
+    side: Side;
+    qty: number;
+    priceUsd: number;
+    feeUsd: number;
+    /** Realized P&L from this specific fill — 0 for opens, ± for closes. */
+    realizedPnlUsd: number;
+}
+export declare class TradeLog {
+    private filePath;
+    constructor(filePath: string);
+    append(entry: TradeLogEntry): void;
+    /** Read all entries from disk in chronological order. */
+    all(): TradeLogEntry[];
+    /** Most recent N entries, newest-first. */
+    recent(n: number): TradeLogEntry[];
+    /** Signed sum of realizedPnlUsd across every entry with timestamp >= since. */
+    realizedSince(since: number): number;
+}

package/dist/trading/trade-log.js

@@ -0,0 +1,81 @@
+/**
+ * TradeLog — JSONL persistent record of every fill the agent executes.
+ *
+ * Purpose: cross-session P&L memory. The Portfolio snapshot tells you
+ * current state; the TradeLog tells you how you got there. This is the
+ * load-bearing surface for answers to questions like:
+ *   - "What was my best / worst trade this week?"
+ *   - "Am I up or down over the last 30 days?"
+ *   - "How many times did I flip BTC in the last session?"
+ *
+ * Claude Code and Cursor can't answer any of these — they have no
+ * persistent economic memory across sessions. Franklin can.
+ *
+ * Format: one JSON object per line, append-only. Reads parse lazily and
+ * skip malformed lines rather than crash, so a partial write from a
+ * prior crash never bricks the log.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class TradeLog {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    append(entry) {
+        try {
+            mkdirSync(dirname(this.filePath), { recursive: true });
+            appendFileSync(this.filePath, JSON.stringify(entry) + '\n', 'utf-8');
+        }
+        catch {
+            // Best-effort persistence; never block a trade on disk failure.
+        }
+    }
+    /** Read all entries from disk in chronological order. */
+    all() {
+        if (!existsSync(this.filePath))
+            return [];
+        let raw;
+        try {
+            raw = readFileSync(this.filePath, 'utf-8');
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                if (typeof obj?.timestamp === 'number' &&
+                    typeof obj?.symbol === 'string' &&
+                    (obj.side === 'buy' || obj.side === 'sell') &&
+                    typeof obj.qty === 'number' &&
+                    typeof obj.priceUsd === 'number' &&
+                    typeof obj.feeUsd === 'number' &&
+                    typeof obj.realizedPnlUsd === 'number') {
+                    out.push(obj);
+                }
+            }
+            catch {
+                // Corrupt line — skip, don't crash.
+            }
+        }
+        return out;
+    }
+    /** Most recent N entries, newest-first. */
+    recent(n) {
+        const all = this.all();
+        return all.slice(-n).reverse();
+    }
+    /** Signed sum of realizedPnlUsd across every entry with timestamp >= since. */
+    realizedSince(since) {
+        let total = 0;
+        for (const e of this.all()) {
+            if (e.timestamp >= since)
+                total += e.realizedPnlUsd;
+        }
+        return total;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.7.10",
+  "version": "3.8.0",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {