@blockrun/franklin 3.8.8 → 3.8.10

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;

package/dist/tools/webhook.js

@@ -0,0 +1,185 @@
+/**
+ * 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 { isIP } from 'node:net';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 512 * 1024; // 512 KB is generous for a chat push.
+function isPrivateHost(hostname) {
+    const h = hostname
+        .trim()
+        .replace(/^\[/, '')
+        .replace(/\]$/, '')
+        .split('%', 1)[0]
+        .toLowerCase();
+    if (h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0' || h === '::' || h === '::1')
+        return true;
+    // IPv4 private ranges.
+    if (isIP(h) === 4) {
+        const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(h);
+        if (m) {
+            const [a, b] = [Number(m[1]), Number(m[2])];
+            if (a === 10)
+                return true;
+            if (a === 172 && b >= 16 && b <= 31)
+                return true;
+            if (a === 192 && b === 168)
+                return true;
+            if (a === 169 && b === 254)
+                return true; // link-local
+            if (a === 127)
+                return true;
+        }
+    }
+    if (isIP(h) === 6) {
+        if (h.startsWith('fc') || h.startsWith('fd') || h.startsWith('fe80:'))
+            return true;
+        if (h.startsWith('::ffff:')) {
+            return isPrivateHost(h.slice('::ffff:'.length));
+        }
+    }
+    return false;
+}
+async function execute(input, ctx) {
+    const { url, body, headers, method = 'POST' } = input;
+    if (!url || typeof url !== 'string') {
+        return { output: 'Error: url is required (string).', isError: true };
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { output: `Error: invalid URL: ${url}`, isError: true };
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        return { output: `Error: only http(s) URLs allowed, got ${parsed.protocol}`, isError: true };
+    }
+    if (isPrivateHost(parsed.hostname)) {
+        return {
+            output: `Error: refusing to post to private/loopback host ${parsed.hostname}. ` +
+                `WebhookPost is for public webhook endpoints only.`,
+            isError: true,
+        };
+    }
+    // Serialize body. Accept object/array (JSON.stringify) or string (used as-is).
+    let bodyText;
+    let contentType = 'application/json';
+    if (typeof body === 'string') {
+        bodyText = body;
+        contentType = 'text/plain';
+    }
+    else if (body === undefined || body === null) {
+        bodyText = '';
+    }
+    else {
+        try {
+            bodyText = JSON.stringify(body);
+        }
+        catch (err) {
+            return { output: `Error: body is not JSON-serializable: ${err.message}`, isError: true };
+        }
+    }
+    const bodyBytes = Buffer.byteLength(bodyText, 'utf-8');
+    if (bodyBytes > MAX_BODY_BYTES) {
+        return {
+            output: `Error: body is ${(bodyBytes / 1024).toFixed(1)} KB, exceeds ${MAX_BODY_BYTES / 1024} KB cap.`,
+            isError: true,
+        };
+    }
+    const finalHeaders = {
+        'Content-Type': contentType,
+        'User-Agent': 'franklin/3.8.9 (webhook)',
+        ...(headers ?? {}),
+    };
+    const ctrl = new AbortController();
+    // Chain abort from the execution scope so Ctrl+C cancels the webhook call.
+    const onParentAbort = () => ctrl.abort();
+    ctx.abortSignal.addEventListener('abort', onParentAbort);
+    const timer = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method,
+            headers: finalHeaders,
+            body: bodyText || undefined,
+            signal: ctrl.signal,
+        });
+        // Capture a small slice of the response body for debugging — most webhook
+        // endpoints return a short ack ({"ok":true}, "ok", "1", etc.).
+        const text = await res.text();
+        const preview = text.length > 500 ? text.slice(0, 500) + '...' : text;
+        if (!res.ok) {
+            return {
+                output: `Webhook POST failed: HTTP ${res.status} ${res.statusText}\nResponse: ${preview}`,
+                isError: true,
+            };
+        }
+        return {
+            output: `Posted ${bodyBytes}B to ${parsed.host}${parsed.pathname}\n` +
+                `Response ${res.status}: ${preview || '(empty)'}`,
+        };
+    }
+    catch (err) {
+        if (err.name === 'AbortError') {
+            if (ctx.abortSignal.aborted)
+                return { output: 'Webhook POST canceled by user.', isError: true };
+            return { output: `Webhook POST timed out after ${DEFAULT_TIMEOUT_MS}ms`, isError: true };
+        }
+        return { output: `Webhook POST error: ${err.message}`, isError: true };
+    }
+    finally {
+        clearTimeout(timer);
+        ctx.abortSignal.removeEventListener('abort', onParentAbort);
+    }
+}
+export const webhookPostCapability = {
+    spec: {
+        name: 'WebhookPost',
+        description: 'POST a JSON or plain-text payload to a webhook URL. Works with any service that ' +
+            'accepts an HTTP POST: WeChat Work bots, Feishu/Lark bots, Discord/Slack webhooks, ' +
+            'Telegram Bot API (sendMessage), PushPlus, ServerChan, or a custom receiver. ' +
+            'The agent is responsible for the body shape — each channel has its own schema ' +
+            '(e.g., Discord: { "content": "hello" }; WeChat Work: { "msgtype": "markdown", ' +
+            '"markdown": { "content": "..." } }).\n\n' +
+            'Safety: private/loopback hosts are refused. Bodies over 512KB are refused. ' +
+            'Do NOT use for GET requests — use WebFetch for reads.',
+        input_schema: {
+            type: 'object',
+            required: ['url', 'body'],
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'Full https (or http) webhook URL. Must be a public host.',
+                },
+                body: {
+                    description: 'Request body. Pass an object/array → JSON.stringify. Pass a string → sent ' +
+                        'as text/plain. Construct the shape each channel expects.',
+                },
+                headers: {
+                    type: 'object',
+                    description: 'Optional extra request headers (auth tokens, signing headers). Content-Type ' +
+                        'is set automatically based on body type.',
+                },
+                method: {
+                    type: 'string',
+                    enum: ['POST', 'PUT', 'PATCH'],
+                    description: 'HTTP method. Defaults to POST.',
+                },
+            },
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/trading/data.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Legacy data.ts — thin shim over the provider registry.
+ *
+ * Keeps the historical `string | Data` error-by-string return convention so
+ * the existing callers (`trading.ts`, `tools/index.ts` wiring into
+ * `LiveExchange`) keep working without a call-site rewrite. New code should
+ * import from `./providers/registry.js` and consume `PriceData | ProviderError`
+ * directly — the structured error shape enables UI color-coding and retry
+ * classification the string convention can't express.
+ */
+import type { AssetClass, MarketCode } from './providers/standard-models.js';
 export interface PriceData {
     price: number;
     change24h: number;
@@ -24,7 +35,19 @@ export interface MarketCoin {
     volume24h: number;
 }
 export declare function resolveId(ticker: string): string;
-export declare function getPrice(ticker: string): Promise<PriceData | string>;
+/**
+ * Look up a spot price. `assetClass` defaults to 'crypto' so all existing
+ * crypto-only callers (`TradingSignal`, `LiveExchange.getPrice`) behave
+ * exactly as before. Pass 'fx' / 'commodity' / 'stock' (plus a `market`
+ * code for stocks) to hit the multi-asset Gateway endpoints.
+ */
+export declare function getPrice(ticker: string, assetClass?: AssetClass, market?: MarketCode): Promise<PriceData | string>;
+/** Convenience: FX pair lookup (e.g. "EUR-USD"). */
+export declare function getFxPrice(ticker: string): Promise<PriceData | string>;
+/** Convenience: commodity lookup (e.g. "XAU-USD" for gold). */
+export declare function getCommodityPrice(ticker: string): Promise<PriceData | string>;
+/** Convenience: stock lookup (e.g. "AAPL" on market "us"). */
+export declare function getStockPrice(ticker: string, market: MarketCode): Promise<PriceData | string>;
 export declare function getOHLCV(ticker: string, days?: number): Promise<OHLCVData | string>;
 export declare function getTrending(): Promise<TrendingCoin[] | string>;
 export declare function getMarketOverview(): Promise<MarketCoin[] | string>;