@blockrun/franklin 3.8.8 → 3.8.10

package/dist/tools/activate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ActivateTool — meta-capability that lets the agent pull on-demand tools
+ * into the active toolset per session.
+ *
+ * Pattern borrowed from OpenBB MCP server's per-session tool visibility:
+ * a weak model confronted with 25+ tool definitions starts inventing names
+ * or emits role-play "[TOOLCALL]" fragments. Register only the core file/
+ * shell tools by default and let the model explicitly opt in to the rest.
+ *
+ * Contract:
+ *   - `ActivateTool()` with no args → lists every inactive tool with a
+ *     one-line description so the model knows what's available.
+ *   - `ActivateTool({ names: ["ExaSearch", "ExaReadUrls"] })` → adds the
+ *     named tools to the session's active set; subsequent turns include
+ *     their full schemas. Returns a concise confirmation.
+ *
+ * The factory captures the shared `activeTools` Set that the loop filters
+ * against and the full `allTools` map used for name resolution. Both live
+ * in the session — activation is not durable across restarts on purpose,
+ * since the model can always re-activate on the next turn if it needs to.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export interface ActivateToolDeps {
+    /** Mutable set of tool names currently visible to the model. */
+    activeTools: Set<string>;
+    /** Map of every registered capability, keyed by name. */
+    allTools: Map<string, CapabilityHandler>;
+}
+export declare function createActivateToolCapability(deps: ActivateToolDeps): CapabilityHandler;

package/dist/tools/activate.js

@@ -0,0 +1,96 @@
+/**
+ * ActivateTool — meta-capability that lets the agent pull on-demand tools
+ * into the active toolset per session.
+ *
+ * Pattern borrowed from OpenBB MCP server's per-session tool visibility:
+ * a weak model confronted with 25+ tool definitions starts inventing names
+ * or emits role-play "[TOOLCALL]" fragments. Register only the core file/
+ * shell tools by default and let the model explicitly opt in to the rest.
+ *
+ * Contract:
+ *   - `ActivateTool()` with no args → lists every inactive tool with a
+ *     one-line description so the model knows what's available.
+ *   - `ActivateTool({ names: ["ExaSearch", "ExaReadUrls"] })` → adds the
+ *     named tools to the session's active set; subsequent turns include
+ *     their full schemas. Returns a concise confirmation.
+ *
+ * The factory captures the shared `activeTools` Set that the loop filters
+ * against and the full `allTools` map used for name resolution. Both live
+ * in the session — activation is not durable across restarts on purpose,
+ * since the model can always re-activate on the next turn if it needs to.
+ */
+function shortDesc(desc) {
+    // First sentence or first 120 chars, whichever is shorter.
+    const firstSentence = desc.split(/[.\n]/)[0]?.trim() ?? '';
+    if (firstSentence && firstSentence.length <= 120)
+        return firstSentence;
+    const trimmed = desc.replace(/\s+/g, ' ').trim();
+    return trimmed.length <= 120 ? trimmed : trimmed.slice(0, 117) + '...';
+}
+export function createActivateToolCapability(deps) {
+    const { activeTools, allTools } = deps;
+    return {
+        spec: {
+            name: 'ActivateTool',
+            description: 'Activate additional tools for this session. Most tools are hidden by default to keep your tool inventory small. ' +
+                'Call with no arguments to see what is available. Call with { "names": ["ToolA", "ToolB"] } to enable specific tools — ' +
+                'they become visible in your tool list on the next turn. Activate only what you need; extra tools crowd the inventory.',
+            input_schema: {
+                type: 'object',
+                properties: {
+                    names: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of tool names to activate. Omit to list what is available.',
+                    },
+                },
+            },
+        },
+        concurrent: false,
+        async execute(input) {
+            const raw = input.names;
+            const names = Array.isArray(raw) ? raw.filter((n) => typeof n === 'string') : undefined;
+            // No args → catalog the inactive tools so the model knows what's there.
+            if (!names || names.length === 0) {
+                const inactive = [...allTools.values()]
+                    .filter(t => !activeTools.has(t.spec.name))
+                    .sort((a, b) => a.spec.name.localeCompare(b.spec.name));
+                if (inactive.length === 0) {
+                    return { output: 'All registered tools are already active.' };
+                }
+                const lines = inactive.map(t => `- ${t.spec.name}: ${shortDesc(t.spec.description)}`);
+                return {
+                    output: `Available on-demand tools (${inactive.length}). Activate with ` +
+                        `ActivateTool({ "names": ["<name>", ...] }):\n` +
+                        lines.join('\n'),
+                };
+            }
+            // Activate each named tool.
+            const activated = [];
+            const alreadyActive = [];
+            const unknown = [];
+            for (const name of names) {
+                if (!allTools.has(name)) {
+                    unknown.push(name);
+                }
+                else if (activeTools.has(name)) {
+                    alreadyActive.push(name);
+                }
+                else {
+                    activeTools.add(name);
+                    activated.push(name);
+                }
+            }
+            const parts = [];
+            if (activated.length)
+                parts.push(`Activated: ${activated.join(', ')}`);
+            if (alreadyActive.length)
+                parts.push(`Already active: ${alreadyActive.join(', ')}`);
+            if (unknown.length)
+                parts.push(`Unknown (not registered): ${unknown.join(', ')}`);
+            const output = parts.length ? parts.join('. ') + '.' : 'No change.';
+            const isError = activated.length === 0 && unknown.length > 0;
+            return { output, isError };
+        },
+    };
+}

package/dist/tools/index.js

@@ -22,6 +22,7 @@ import { tradingSignalCapability, tradingMarketCapability } from './trading.js';
 import { searchXCapability } from './searchx.js';
 import { postToXCapability } from './posttox.js';
 import { moaCapability } from './moa.js';
+import { webhookPostCapability } from './webhook.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -138,6 +139,7 @@ export const allCapabilities = [
     searchXCapability,
     postToXCapability,
     moaCapability,
+    webhookPostCapability,
 ];
 export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/tool-categories.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tool visibility categories.
+ *
+ * Franklin ships with ~27 capabilities. Exposing all of them to the model on
+ * every turn makes the tool inventory large enough that weak models start
+ * hallucinating tool names or emitting role-play "[TOOLCALL]" fragments.
+ * The fix: keep a minimal always-on core (file ops, shell, ask) and gate the
+ * rest behind an `ActivateTool` meta-tool that the agent pulls on demand —
+ * the same per-session visibility pattern that OpenBB's MCP server uses.
+ *
+ * `CORE_TOOL_NAMES` is the per-session initial active set. Everything else
+ * becomes visible only after the agent calls ActivateTool with its name.
+ */
+export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
+/** True if this tool is always available without activation. */
+export declare function isCoreTool(name: string): boolean;
+/**
+ * Env opt-out: setting `FRANKLIN_DYNAMIC_TOOLS=0` disables the core/on-demand
+ * split and exposes every registered tool on every turn (pre-3.8.9 behavior).
+ * Kept as a safety valve for users whose workflows depend on the full surface.
+ */
+export declare function dynamicToolsEnabled(): boolean;

package/dist/tools/tool-categories.js

@@ -0,0 +1,44 @@
+/**
+ * Tool visibility categories.
+ *
+ * Franklin ships with ~27 capabilities. Exposing all of them to the model on
+ * every turn makes the tool inventory large enough that weak models start
+ * hallucinating tool names or emitting role-play "[TOOLCALL]" fragments.
+ * The fix: keep a minimal always-on core (file ops, shell, ask) and gate the
+ * rest behind an `ActivateTool` meta-tool that the agent pulls on demand —
+ * the same per-session visibility pattern that OpenBB's MCP server uses.
+ *
+ * `CORE_TOOL_NAMES` is the per-session initial active set. Everything else
+ * becomes visible only after the agent calls ActivateTool with its name.
+ */
+export const CORE_TOOL_NAMES = new Set([
+    // File operations — nothing else works without these.
+    'Read',
+    'Write',
+    'Edit',
+    // Shell execution — needed for running tests, builds, scripts.
+    'Bash',
+    // Search — code exploration is table stakes.
+    'Grep',
+    'Glob',
+    // User dialogue — the agent must be able to ask for clarification.
+    'AskUser',
+    // Sub-agent delegation — the sub-agent has its own tool resolution,
+    // so keeping this in the core doesn't leak the full inventory.
+    'Task',
+    // The meta-tool itself — must always be callable so the agent can
+    // discover and activate the rest.
+    'ActivateTool',
+]);
+/** True if this tool is always available without activation. */
+export function isCoreTool(name) {
+    return CORE_TOOL_NAMES.has(name);
+}
+/**
+ * Env opt-out: setting `FRANKLIN_DYNAMIC_TOOLS=0` disables the core/on-demand
+ * split and exposes every registered tool on every turn (pre-3.8.9 behavior).
+ * Kept as a safety valve for users whose workflows depend on the full surface.
+ */
+export function dynamicToolsEnabled() {
+    return process.env.FRANKLIN_DYNAMIC_TOOLS !== '0';
+}

package/dist/tools/trading-execute.d.ts

@@ -1,19 +1,13 @@
 /**
- * Trading execution capabilities. Exposes Franklin's Portfolio + RiskEngine
- * + Exchange stack to the agent as three tools: TradingPortfolio (read),
- * TradingOpenPosition (buy side), TradingClosePosition (sell side).
+ * Trading execution capabilities — the three-to-four tools that let the
+ * agent inspect its portfolio, open/close paper positions, and (when a
+ * persistent trade log is attached) query cross-session history.
  *
- * This is the surface that differentiates Franklin from generic coding
- * agents — stateless tools can't hold a wallet, track positions across
- * sessions, or reason about P&L. Every output here is deliberately
- * information-rich so the agent has the numbers it needs to make the next
- * economic decision (cash left, risk utilization, unrealized vs realized
- * P&L, fill detail) without a follow-up tool call.
- *
- * Factory-style construction (createTradingCapabilities) keeps testing
- * clean: production code calls it with a default disk-backed engine;
- * tests inject a MockExchange-backed engine and assert behavior without
- * touching disk.
+ * This file is now the "router" layer only: it binds the engine to tool
+ * handlers and delegates rendering to `trading-views.ts`. The portfolio
+ * math, risk math, and exchange simulation all live in `../trading/*`.
+ * The split mirrors OpenBB's router/engine/view layering and keeps every
+ * layer testable in isolation.
  */
 import type { CapabilityHandler } from '../agent/types.js';
 import type { TradingEngine } from '../trading/engine.js';
@@ -21,15 +15,11 @@ import type { RiskConfig } from '../trading/risk.js';
 import type { TradeLog } from '../trading/trade-log.js';
 export interface TradingCapabilitiesDeps {
     engine: TradingEngine;
-    /** Risk config used to report "you're using X% of your position cap". */
+    /** Risk config used for "you're at X% of your exposure cap" readout. */
     riskConfig?: RiskConfig;
-    /** Optional hook run after every state-changing call (e.g., persist to disk). */
+    /** Hook run after state-changing calls — typically persists to disk. */
     onStateChange?: () => void | Promise<void>;
-    /**
-     * Optional persistent trade log. When provided, opens and closes are
-     * appended to it and the TradingHistory capability is registered so the
-     * agent can query cross-session P&L.
-     */
+    /** Persistent trade log; when provided, TradingHistory is registered. */
     tradeLog?: TradeLog;
 }
 export declare function createTradingCapabilities(deps: TradingCapabilitiesDeps): CapabilityHandler[];

package/dist/tools/trading-execute.js

@@ -1,54 +1,31 @@
 /**
- * Trading execution capabilities. Exposes Franklin's Portfolio + RiskEngine
- * + Exchange stack to the agent as three tools: TradingPortfolio (read),
- * TradingOpenPosition (buy side), TradingClosePosition (sell side).
+ * Trading execution capabilities — the three-to-four tools that let the
+ * agent inspect its portfolio, open/close paper positions, and (when a
+ * persistent trade log is attached) query cross-session history.
  *
- * This is the surface that differentiates Franklin from generic coding
- * agents — stateless tools can't hold a wallet, track positions across
- * sessions, or reason about P&L. Every output here is deliberately
- * information-rich so the agent has the numbers it needs to make the next
- * economic decision (cash left, risk utilization, unrealized vs realized
- * P&L, fill detail) without a follow-up tool call.
- *
- * Factory-style construction (createTradingCapabilities) keeps testing
- * clean: production code calls it with a default disk-backed engine;
- * tests inject a MockExchange-backed engine and assert behavior without
- * touching disk.
+ * This file is now the "router" layer only: it binds the engine to tool
+ * handlers and delegates rendering to `trading-views.ts`. The portfolio
+ * math, risk math, and exchange simulation all live in `../trading/*`.
+ * The split mirrors OpenBB's router/engine/view layering and keeps every
+ * layer testable in isolation.
  */
-function formatUsd(n) {
-    const sign = n < 0 ? '-' : '';
-    const abs = Math.abs(n);
-    return `${sign}$${abs.toFixed(2)}`;
-}
-function formatPct(n) {
-    return `${(n * 100).toFixed(1)}%`;
+import { renderOrderBlocked, renderOrderFilled, renderPortfolio, renderPositionClosed, renderTradeHistory, windowToSince, } from './trading-views.js';
+function enginePortfolio(engine) {
+    return engine.deps.portfolio;
 }
-function formatPositionLine(p) {
-    const pctReturn = (p.markUsd - p.avgPriceUsd) / p.avgPriceUsd;
-    const arrow = p.unrealizedPnlUsd >= 0 ? '↑' : '↓';
-    return (`- **${p.symbol}** qty=${p.qty} @ avg ${formatUsd(p.avgPriceUsd)} ` +
-        `| mark ${formatUsd(p.markUsd)} ${arrow} ` +
-        `| unrealized ${formatUsd(p.unrealizedPnlUsd)} (${formatPct(pctReturn)})`);
+function engineExchange(engine) {
+    return engine.deps.exchange;
 }
-/** Parse a window string (e.g. "24h", "7d", "all") into a lower-bound timestamp. */
-function windowToSince(window, now) {
-    const m = /^(\d+)\s*([hdwm])$/i.exec(window.trim());
-    if (!m)
-        return 0; // "all" or anything unparseable → since epoch
-    const n = parseInt(m[1], 10);
-    switch (m[2].toLowerCase()) {
-        case 'h': return now - n * 3_600_000;
-        case 'd': return now - n * 86_400_000;
-        case 'w': return now - n * 7 * 86_400_000;
-        case 'm': return now - n * 30 * 86_400_000;
-        default: return 0;
+async function buildPortfolioSnapshot(engine) {
+    const portfolio = enginePortfolio(engine);
+    const exchange = engineExchange(engine);
+    const priceTable = {};
+    for (const p of portfolio.listPositions()) {
+        const quote = await exchange.getPrice(p.symbol);
+        if (quote != null)
+            priceTable[p.symbol] = quote;
     }
-}
-function formatTradeLine(entry) {
-    const when = new Date(entry.timestamp).toISOString().replace('T', ' ').slice(0, 16);
-    const side = entry.side.toUpperCase();
-    const pnl = entry.realizedPnlUsd === 0 ? '' : ` → realized ${formatUsd(entry.realizedPnlUsd)}`;
-    return `- ${when}  ${side} ${entry.qty} ${entry.symbol} @ ${formatUsd(entry.priceUsd)}${pnl}`;
+    return portfolio.markToMarket(priceTable);
 }
 export function createTradingCapabilities(deps) {
     const { engine, riskConfig, onStateChange, tradeLog } = deps;
@@ -66,39 +43,8 @@ export function createTradingCapabilities(deps) {
         },
         concurrent: true,
         async execute(_input, _ctx) {
-            // markToMarket against current exchange prices; fall back to avg price
-            // (flat unrealized) when the exchange doesn't know the symbol.
-            const priceTable = {};
-            for (const p of engine.deps.portfolio.listPositions()) {
-                const quote = await engine.deps.exchange.getPrice(p.symbol);
-                if (quote != null)
-                    priceTable[p.symbol] = quote;
-            }
-            const portfolio = engine.deps.portfolio;
-            const snap = portfolio.markToMarket(priceTable);
-            const lines = [];
-            lines.push('## Portfolio');
-            lines.push(`- Cash: ${formatUsd(snap.cashUsd)}`);
-            lines.push(`- Equity (cash + positions marked-to-market): ${formatUsd(snap.equityUsd)}`);
-            lines.push(`- Unrealized P&L: ${formatUsd(snap.unrealizedPnlUsd)}`);
-            lines.push(`- Realized P&L (this session): ${formatUsd(snap.realizedPnlUsd)}`);
-            lines.push('');
-            if (snap.positions.length === 0) {
-                lines.push('_No open positions._');
-            }
-            else {
-                lines.push('### Open positions');
-                for (const p of snap.positions)
-                    lines.push(formatPositionLine(p));
-            }
-            if (riskConfig) {
-                const totalExposure = snap.positions.reduce((a, p) => a + p.qty * p.markUsd, 0);
-                lines.push('');
-                lines.push('### Risk utilization');
-                lines.push(`- Total exposure: ${formatUsd(totalExposure)} / cap ${formatUsd(riskConfig.maxTotalExposureUsd)} ` +
-                    `(${formatPct(totalExposure / riskConfig.maxTotalExposureUsd)})`);
-            }
-            return { output: lines.join('\n') };
+            const snap = await buildPortfolioSnapshot(engine);
+            return { output: renderPortfolio(snap, riskConfig) };
         },
     };
     const tradingOpenPosition = {
@@ -132,14 +78,7 @@ export function createTradingCapabilities(deps) {
             }
             const outcome = await engine.openPosition({ symbol, qty, priceUsd });
             if (outcome.status === 'blocked') {
-                // Not an agent error — a legitimate risk decision the agent must read.
-                return {
-                    output: `## Order blocked\n` +
-                        `- Symbol: ${symbol}\n` +
-                        `- Attempted: buy ${qty} @ ${formatUsd(priceUsd)}\n` +
-                        `- Reason: ${outcome.reason}\n\n` +
-                        `Try a smaller qty, or close other positions first to free up exposure headroom.`,
-                };
+                return { output: renderOrderBlocked({ symbol, qty, priceUsd, reason: outcome.reason }) };
             }
             if (outcome.status === 'noop') {
                 return { output: `No-op: ${outcome.reason}` };
@@ -157,14 +96,12 @@ export function createTradingCapabilities(deps) {
             }
             if (onStateChange)
                 await onStateChange();
-            const portfolio = engine.deps.portfolio;
-            const pos = portfolio.getPosition(symbol);
             return {
-                output: `## Order filled\n` +
-                    `- Bought ${outcome.fill.qty} ${symbol} @ ${formatUsd(outcome.fill.priceUsd)} ` +
-                    `(fee ${formatUsd(outcome.fill.feeUsd)})\n` +
-                    `- Position now: ${pos ? `${pos.qty} ${symbol} @ avg ${formatUsd(pos.avgPriceUsd)}` : '(none)'}\n` +
-                    `- Cash remaining: ${formatUsd(portfolio.cashUsd)}`,
+                output: renderOrderFilled({
+                    symbol,
+                    fill: outcome.fill,
+                    portfolio: enginePortfolio(engine),
+                }),
             };
         },
     };
@@ -172,8 +109,8 @@ export function createTradingCapabilities(deps) {
         spec: {
             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.',
+                "Omit qty to flatten the position entirely; pass qty to partially reduce. Uses the " +
+                "exchange's current mark — no manual price required.",
             input_schema: {
                 type: 'object',
                 required: ['symbol'],
@@ -192,27 +129,19 @@ export function createTradingCapabilities(deps) {
             const symbol = String(input.symbol ?? '').toUpperCase();
             const qty = input.qty != null ? Number(input.qty) : undefined;
             if (!symbol) {
-                return {
-                    output: 'Error: TradingClosePosition requires symbol.',
-                    isError: true,
-                };
+                return { output: 'Error: TradingClosePosition requires symbol.', isError: true };
             }
             if (qty != null && (!Number.isFinite(qty) || qty <= 0)) {
-                return {
-                    output: 'Error: if qty is provided, it must be > 0.',
-                    isError: true,
-                };
+                return { output: 'Error: if qty is provided, it must be > 0.', isError: true };
             }
-            const portfolio = engine.deps.portfolio;
+            const portfolio = enginePortfolio(engine);
             const priorRealized = portfolio.realizedPnlUsd;
             const outcome = await engine.closePosition({ symbol, qty });
             if (outcome.status === 'noop') {
                 return { output: `No open ${symbol} position to close.` };
             }
             if (outcome.status === 'blocked') {
-                return {
-                    output: `## Close blocked\n- Symbol: ${symbol}\n- Reason: ${outcome.reason}`,
-                };
+                return { output: `## Close blocked\n- Symbol: ${symbol}\n- Reason: ${outcome.reason}` };
             }
             const tradeRealized = portfolio.realizedPnlUsd - priorRealized;
             if (tradeLog) {
@@ -228,15 +157,13 @@ export function createTradingCapabilities(deps) {
             }
             if (onStateChange)
                 await onStateChange();
-            const remaining = portfolio.getPosition(symbol);
             return {
-                output: `## Position closed\n` +
-                    `- Sold ${outcome.fill.qty} ${symbol} @ ${formatUsd(outcome.fill.priceUsd)} ` +
-                    `(fee ${formatUsd(outcome.fill.feeUsd)})\n` +
-                    `- Realized on this trade: ${formatUsd(tradeRealized)}\n` +
-                    `- Remaining ${symbol}: ${remaining ? `${remaining.qty} @ avg ${formatUsd(remaining.avgPriceUsd)}` : '(flat)'}\n` +
-                    `- Cash: ${formatUsd(portfolio.cashUsd)} · ` +
-                    `Session realized P&L: ${formatUsd(portfolio.realizedPnlUsd)}`,
+                output: renderPositionClosed({
+                    symbol,
+                    fill: outcome.fill,
+                    tradeRealized,
+                    portfolio,
+                }),
             };
         },
     };
@@ -274,21 +201,7 @@ export function createTradingCapabilities(deps) {
                 const since = windowRaw.toLowerCase() === 'all' ? 0 : windowToSince(windowRaw, now);
                 const entries = tradeLog.recent(limit).filter((e) => e.timestamp >= since);
                 const realized = tradeLog.realizedSince(since);
-                const opens = entries.filter((e) => e.side === 'buy').length;
-                const closes = entries.filter((e) => e.side === 'sell').length;
-                const lines = [];
-                lines.push(`## Trade history (${windowRaw})`);
-                lines.push(`- ${windowRaw} P&L (realized): ${formatUsd(realized)}`);
-                lines.push(`- Trades: ${entries.length} (${opens} opens, ${closes} closes)`);
-                lines.push('');
-                if (entries.length === 0) {
-                    lines.push('_No trades in this window._');
-                }
-                else {
-                    for (const e of entries)
-                        lines.push(formatTradeLine(e));
-                }
-                return { output: lines.join('\n') };
+                return { output: renderTradeHistory({ windowRaw, entries, realized }) };
             },
         };
         caps.push(tradingHistory);

package/dist/tools/trading-views.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Trading view/formatter helpers.
+ *
+ * Anything that turns engine state into human/agent-readable markdown
+ * belongs here. Split out of `trading-execute.ts` so the tool handlers in
+ * `trading-router.ts` stay focused on request handling and the engine
+ * stays free of presentation concerns. This mirrors the view/controller
+ * separation OpenBB enforces between `standard_models` (data) and the
+ * router-side rendering that happens in their MCP layer.
+ */
+import type { Position } from '../trading/portfolio.js';
+import type { Portfolio } from '../trading/portfolio.js';
+import type { RiskConfig } from '../trading/risk.js';
+import type { TradeLogEntry } from '../trading/trade-log.js';
+export declare function formatUsd(n: number): string;
+export declare function formatPct(n: number): string;
+export declare function formatPositionLine(p: Position & {
+    markUsd: number;
+    unrealizedPnlUsd: number;
+}): string;
+export declare function formatTradeLine(entry: TradeLogEntry): string;
+/** Parse a window string ("24h", "7d", "all") into a lower-bound timestamp. */
+export declare function windowToSince(window: string, now: number): number;
+export interface PortfolioSnapshot {
+    cashUsd: number;
+    equityUsd: number;
+    unrealizedPnlUsd: number;
+    realizedPnlUsd: number;
+    positions: (Position & {
+        markUsd: number;
+        unrealizedPnlUsd: number;
+    })[];
+}
+export declare function renderPortfolio(snap: PortfolioSnapshot, riskConfig?: RiskConfig): string;
+export declare function renderOrderFilled(params: {
+    symbol: string;
+    fill: {
+        qty: number;
+        priceUsd: number;
+        feeUsd: number;
+    };
+    portfolio: Portfolio;
+}): string;
+export declare function renderOrderBlocked(params: {
+    symbol: string;
+    qty: number;
+    priceUsd: number;
+    reason: string;
+}): string;
+export declare function renderPositionClosed(params: {
+    symbol: string;
+    fill: {
+        qty: number;
+        priceUsd: number;
+        feeUsd: number;
+    };
+    tradeRealized: number;
+    portfolio: Portfolio;
+}): string;
+export declare function renderTradeHistory(params: {
+    windowRaw: string;
+    entries: TradeLogEntry[];
+    realized: number;
+}): string;