@blockrun/franklin 3.8.7 → 3.8.9

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;

package/dist/tools/trading-views.js

@@ -0,0 +1,115 @@
+/**
+ * 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.
+ */
+export function formatUsd(n) {
+    const sign = n < 0 ? '-' : '';
+    const abs = Math.abs(n);
+    return `${sign}$${abs.toFixed(2)}`;
+}
+export function formatPct(n) {
+    return `${(n * 100).toFixed(1)}%`;
+}
+export 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)})`);
+}
+export 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}`;
+}
+/** Parse a window string ("24h", "7d", "all") into a lower-bound timestamp. */
+export function windowToSince(window, now) {
+    const m = /^(\d+)\s*([hdwm])$/i.exec(window.trim());
+    if (!m)
+        return 0;
+    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;
+    }
+}
+export function renderPortfolio(snap, riskConfig) {
+    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 lines.join('\n');
+}
+export function renderOrderFilled(params) {
+    const { symbol, fill, portfolio } = params;
+    const pos = portfolio.getPosition(symbol);
+    return (`## Order filled\n` +
+        `- Bought ${fill.qty} ${symbol} @ ${formatUsd(fill.priceUsd)} ` +
+        `(fee ${formatUsd(fill.feeUsd)})\n` +
+        `- Position now: ${pos ? `${pos.qty} ${symbol} @ avg ${formatUsd(pos.avgPriceUsd)}` : '(none)'}\n` +
+        `- Cash remaining: ${formatUsd(portfolio.cashUsd)}`);
+}
+export function renderOrderBlocked(params) {
+    return (`## Order blocked\n` +
+        `- Symbol: ${params.symbol}\n` +
+        `- Attempted: buy ${params.qty} @ ${formatUsd(params.priceUsd)}\n` +
+        `- Reason: ${params.reason}\n\n` +
+        `Try a smaller qty, or close other positions first to free up exposure headroom.`);
+}
+export function renderPositionClosed(params) {
+    const { symbol, fill, tradeRealized, portfolio } = params;
+    const remaining = portfolio.getPosition(symbol);
+    return (`## Position closed\n` +
+        `- Sold ${fill.qty} ${symbol} @ ${formatUsd(fill.priceUsd)} ` +
+        `(fee ${formatUsd(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)}`);
+}
+export function renderTradeHistory(params) {
+    const { windowRaw, entries, realized } = params;
+    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 lines.join('\n');
+}

package/dist/tools/trading.js

@@ -1,4 +1,7 @@
-import { getPrice, getOHLCV, getTrending, getMarketOverview } from '../trading/data.js';
+import { getPrice, getOHLCV, getTrending, getMarketOverview, getFxPrice, getCommodityPrice, getStockPrice, } from '../trading/data.js';
+const SUPPORTED_STOCK_MARKETS = [
+    'us', 'hk', 'jp', 'kr', 'gb', 'de', 'fr', 'nl', 'ie', 'lu', 'cn', 'ca',
+];
 import { rsi, macd, bollingerBands, volatility } from '../trading/metrics.js';
 import { bus } from '../events/bus.js';
 import { makeEvent } from '../events/types.js';
@@ -102,8 +105,17 @@ export const tradingSignalCapability = {
     execute: executeSignal,
     concurrent: true,
 };
+function formatPriceLine(label, priceUsd, change24hPct, opts = {}) {
+    const digits = opts.fractionDigits ?? 2;
+    const priceStr = `$${priceUsd.toLocaleString(undefined, { minimumFractionDigits: digits, maximumFractionDigits: digits })}`;
+    if (opts.showChange === false || !Number.isFinite(change24hPct)) {
+        return `${label}: ${priceStr}`;
+    }
+    const sign = change24hPct > 0 ? '+' : '';
+    return `${label}: ${priceStr} (${sign}${change24hPct.toFixed(2)}% 24h)`;
+}
 async function executeMarket(input, _ctx) {
-    const { action, ticker } = input;
+    const { action, ticker, market } = input;
     if (!action) {
         return { output: 'Error: action is required', isError: true };
     }
@@ -121,6 +133,58 @@ async function executeMarket(input, _ctx) {
                 output: `${ticker.toUpperCase()}: $${price.toLocaleString()} (${change24h > 0 ? '+' : ''}${change24h.toFixed(2)}% 24h), Market Cap: ${formatUsd(marketCap)}, Volume: ${formatUsd(volume24h)}`,
             };
         }
+        case 'fxPrice': {
+            if (!ticker) {
+                return { output: 'Error: ticker is required (e.g. "EUR-USD")', isError: true };
+            }
+            const result = await getFxPrice(ticker);
+            if (typeof result === 'string') {
+                return { output: `Error: ${result}`, isError: true };
+            }
+            return {
+                output: formatPriceLine(ticker.toUpperCase(), result.price, result.change24h, { fractionDigits: 4 }) +
+                    ' · source: BlockRun Gateway / Pyth (free)',
+            };
+        }
+        case 'commodityPrice': {
+            if (!ticker) {
+                return { output: 'Error: ticker is required (e.g. "XAU-USD" for gold)', isError: true };
+            }
+            const result = await getCommodityPrice(ticker);
+            if (typeof result === 'string') {
+                return { output: `Error: ${result}`, isError: true };
+            }
+            return {
+                output: formatPriceLine(ticker.toUpperCase(), result.price, result.change24h, { fractionDigits: 2 }) +
+                    ' · source: BlockRun Gateway / Pyth (free)',
+            };
+        }
+        case 'stockPrice': {
+            if (!ticker) {
+                return { output: 'Error: ticker is required (e.g. "AAPL" on market "us")', isError: true };
+            }
+            if (!market) {
+                return {
+                    output: `Error: market code is required for stockPrice. Supported: ${SUPPORTED_STOCK_MARKETS.join(', ')}`,
+                    isError: true,
+                };
+            }
+            if (!SUPPORTED_STOCK_MARKETS.includes(market)) {
+                return {
+                    output: `Error: unsupported market "${market}". Supported: ${SUPPORTED_STOCK_MARKETS.join(', ')}`,
+                    isError: true,
+                };
+            }
+            const result = await getStockPrice(ticker, market);
+            if (typeof result === 'string') {
+                return { output: `Error: ${result}`, isError: true };
+            }
+            const tickerLabel = `${ticker.toUpperCase()} (${market})`;
+            return {
+                output: formatPriceLine(tickerLabel, result.price, result.change24h, { fractionDigits: 2 }) +
+                    ' · source: BlockRun Gateway / Pyth · $0.001 paid from wallet',
+            };
+        }
         case 'trending': {
             const result = await getTrending();
             if (typeof result === 'string') {
@@ -140,24 +204,39 @@ async function executeMarket(input, _ctx) {
             return { output: `Top 20 by Market Cap:\n${header}\n${sep}\n${rows.join('\n')}` };
         }
         default:
-            return { output: `Error: unknown action "${action}". Use: price, trending, overview`, isError: true };
+            return {
+                output: `Error: unknown action "${action}". Use: price, trending, overview, fxPrice, commodityPrice, stockPrice`,
+                isError: true,
+            };
     }
 }
 export const tradingMarketCapability = {
     spec: {
         name: 'TradingMarket',
-        description: 'Get cryptocurrency market data: price lookup, trending coins, or market overview (top 20 by market cap).',
+        description: 'Get market data across asset classes. Actions: ' +
+            '`price` (crypto spot via CoinGecko, free), ' +
+            '`trending` (top trending coins), ' +
+            '`overview` (top 20 by market cap), ' +
+            '`fxPrice` (FX pair like EUR-USD, BlockRun Gateway/Pyth, free), ' +
+            '`commodityPrice` (XAU-USD for gold, XAG-USD for silver, etc., free), ' +
+            '`stockPrice` (any of 1,746 tickers across us/hk/jp/kr/gb/de/fr/nl/ie/lu/cn/ca, BlockRun Gateway/Pyth, $0.001 per call paid from the agent wallet). ' +
+            'Prefer stockPrice for any equity question — CRCL, AAPL, 7203.JP, 0005.HK, etc.',
         input_schema: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['price', 'trending', 'overview'],
-                    description: 'What to fetch: price lookup, trending coins, or market overview',
+                    enum: ['price', 'trending', 'overview', 'fxPrice', 'commodityPrice', 'stockPrice'],
+                    description: 'What to fetch. See tool description for cost + source per action.',
                 },
                 ticker: {
                     type: 'string',
-                    description: 'Cryptocurrency ticker (required for price action), e.g. "BTC"',
+                    description: 'Ticker. Crypto: "BTC". FX: "EUR-USD". Commodity: "XAU-USD" (gold). Stock: "AAPL", "CRCL", "7203" (Toyota on jp), "0005" (HSBC on hk). Required for all price actions.',
+                },
+                market: {
+                    type: 'string',
+                    enum: ['us', 'hk', 'jp', 'kr', 'gb', 'de', 'fr', 'nl', 'ie', 'lu', 'cn', 'ca'],
+                    description: 'Stock exchange market code. Required when action="stockPrice". Ignored for other actions.',
                 },
             },
             required: ['action'],

package/dist/tools/webhook.d.ts

@@ -0,0 +1,18 @@
+/**
+ * WebhookPost — generic HTTP POST tool for pushing agent output to any
+ * webhook endpoint. Covers WeChat Work, Feishu, Discord, Slack, Telegram
+ * Bot API, PushPlus, ServerChan, custom HTTP receivers — anything that
+ * accepts a JSON body over POST.
+ *
+ * Intentionally not per-vendor: those integrations differ only in body
+ * shape, which the agent already knows how to construct. One tool, eight
+ * channels. If a channel needs a signature header (e.g., Feishu sign
+ * mode), the agent passes it in via `headers`.
+ *
+ * Safety: outbound URLs are a publish surface. We refuse localhost,
+ * private ranges, and file schemes so an agent can't be tricked into
+ * hitting internal services. A permission prompt fires on first use per
+ * session.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const webhookPostCapability: CapabilityHandler;