@blockrun/franklin 3.8.7 → 3.8.9

package/dist/panel/html.js

@@ -371,14 +371,14 @@ a:hover { text-decoration:underline; }
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12V7H5a2 2 0 0 1 0-4h14v4"/><path d="M3 5v14a2 2 0 0 0 2 2h16v-5"/><path d="M18 12a2 2 0 0 0 0 4h4v-4z"/></svg>
       Wallet
     </button>
+    <button class="nav-item" data-tab="markets">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M3 3v18h18"/><path d="M7 14l4-4 4 4 5-5"/></svg>
+      Markets
+    </button>
     <button class="nav-item" data-tab="sessions">
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
       Sessions
     </button>
-    <button class="nav-item" data-tab="social">
-      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M4 4l11.733 16h4.267l-11.733-16z"/><path d="M4 20l6.768-6.768M15.232 11.232L20 4"/></svg>
-      Social
-    </button>
     <button class="nav-item" data-tab="learnings">
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z"/><path d="M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z"/></svg>
       Learnings
@@ -542,16 +542,34 @@ a:hover { text-decoration:underline; }
     <div class="session-detail" id="session-detail" style="display:none"></div>
   </div>
 
-  <!-- Social -->
-  <div class="tab" id="tab-social">
+  <!-- Markets -->
+  <div class="tab" id="tab-markets">
     <div class="content-header">
-      <h2>Social</h2>
-      <p>X/Twitter engagement stats</p>
+      <h2>Markets</h2>
+      <p>How Franklin gets trading data — and what it costs.</p>
     </div>
-    <div class="grid grid-4" id="social-stats"></div>
-    <div class="card" style="margin-top:12px">
-      <h3>Recent Activity</h3>
-      <div id="social-feed" class="empty">No social activity yet</div>
+
+    <div class="grid grid-4">
+      <div class="card"><h3>Calls today</h3><div class="metric" id="mk-calls">&mdash;</div></div>
+      <div class="card"><h3>Spend today</h3><div class="metric gold" id="mk-spend">&mdash;</div></div>
+      <div class="card"><h3>p50 latency</h3><div class="metric" id="mk-p50">&mdash;</div></div>
+      <div class="card"><h3>Payment chain</h3><div class="metric" id="mk-chain">&mdash;</div></div>
+    </div>
+
+    <div style="display:grid;grid-template-columns:1.1fr 1fr;gap:14px;margin-top:14px">
+      <div class="card">
+        <h3>Data pipeline</h3>
+        <p style="color:var(--text-dim);font-size:12px;margin:4px 0 14px">
+          Each asset class routes through the provider registry to the active upstream.
+        </p>
+        <div id="mk-pipeline" style="font-family:var(--mono);font-size:12px;line-height:1.75"></div>
+      </div>
+      <div class="card">
+        <h3>Providers</h3>
+        <div id="mk-providers" style="margin-top:6px"></div>
+        <h3 style="margin-top:18px">Recent paid calls</h3>
+        <div id="mk-paid" class="empty" style="margin-top:6px">No paid calls yet</div>
+      </div>
     </div>
   </div>
 
@@ -588,6 +606,7 @@ a:hover { text-decoration:underline; }
     </div>
     <div id="audit-list" style="font-family:ui-monospace,SFMono-Regular,Consolas,monospace;font-size:12px;"></div>
   </div>
+
 </div>
 
 <script>
@@ -716,14 +735,84 @@ document.getElementById('session-search').addEventListener('input', (e) => {
   }, 300);
 });
 
-async function loadSocial() {
-  const social = await api('social');
-  if (!social) return;
-  document.getElementById('social-stats').innerHTML =
-    '<div class="card"><h3>Posted</h3><div class="metric success">' + (social.posted || 0) + '</div></div>' +
-    '<div class="card"><h3>Drafted</h3><div class="metric">' + (social.drafted || 0) + '</div></div>' +
-    '<div class="card"><h3>Skipped</h3><div class="metric">' + (social.skipped || 0) + '</div></div>' +
-    '<div class="card"><h3>Social Cost</h3><div class="metric gold">' + usd(social.totalCost || 0) + '</div></div>';
+async function loadMarkets() {
+  const data = await api('markets');
+  if (!data) return;
+
+  const calls = (data.totals && data.totals.callsToday) || 0;
+  const spend = (data.totals && data.totals.spendUsdToday) || 0;
+  const p50 = data.totals && data.totals.p50LatencyMs;
+  document.getElementById('mk-calls').textContent = String(calls);
+  document.getElementById('mk-spend').textContent = usd(spend);
+  document.getElementById('mk-p50').textContent = (p50 == null) ? '—' : (p50 + ' ms');
+  document.getElementById('mk-chain').textContent = (data.chain || 'base').toUpperCase();
+
+  // Pipeline: Franklin → registry → per-asset-class provider → endpoint
+  const rows = (data.wiring || []).filter(function(r){ return r.kind === 'price'; });
+  const singletonRows = (data.wiring || []).filter(function(r){ return r.kind !== 'price'; });
+  const providerLabel = function(name) {
+    if (name === 'coingecko') return '<span style="color:var(--success)">CoinGecko</span>';
+    if (name === 'blockrun') return '<span style="color:var(--gold)">BlockRun Gateway</span>';
+    return esc(name);
+  };
+  const pipeLines = [
+    '<div>Franklin agent</div>',
+    '<div style="color:var(--text-dim);padding-left:8px">↓</div>',
+    '<div>Provider registry</div>',
+    '<div style="color:var(--text-dim);padding-left:8px">↓</div>',
+  ];
+  rows.forEach(function(r, i){
+    const last = i === rows.length - 1;
+    const branch = last ? '└' : '├';
+    const paid = r.paid ? ' <span style="color:var(--gold);font-size:10px">◆ x402</span>' : '';
+    pipeLines.push(
+      '<div>&nbsp;' + branch + '─ ' + esc(r.assetClass).padEnd(9, ' ') +
+      ' → ' + providerLabel(r.provider) + paid + '</div>'
+    );
+  });
+  pipeLines.push('<div style="margin-top:10px;color:var(--text-dim);font-size:11px">Other singleton kinds:</div>');
+  singletonRows.forEach(function(r){
+    pipeLines.push(
+      '<div style="color:var(--text-dim);font-size:11px">&nbsp;&nbsp;' +
+      esc(r.kind) + ' → ' + providerLabel(r.provider) + '</div>'
+    );
+  });
+  document.getElementById('mk-pipeline').innerHTML = pipeLines.join('');
+
+  // Providers health
+  const statusChip = function(s){
+    if (s === 'ok')       return '<span class="dot on"></span> <span style="color:var(--success)">OK</span>';
+    if (s === 'degraded') return '<span class="dot off"></span> <span style="color:var(--danger)">degraded</span>';
+    return '<span class="dot" style="background:var(--text-dim)"></span> <span style="color:var(--text-dim)">cold</span>';
+  };
+  const providers = data.providers || [];
+  document.getElementById('mk-providers').innerHTML = providers.length === 0 ? '<div class="empty">No calls recorded yet.</div>' : providers.map(function(p){
+    const since = p.lastOkAt ? Math.round((Date.now() - p.lastOkAt) / 1000) + 's ago' : '—';
+    return '<div style="display:flex;justify-content:space-between;align-items:center;padding:7px 0;border-bottom:1px solid var(--border);font-size:12px">' +
+      '<span>' + statusChip(p.status) + ' &nbsp;<strong>' + esc(p.name) + '</strong></span>' +
+      '<span style="color:var(--text-dim);font-family:var(--mono);font-size:11px">' +
+        p.calls + ' calls · p50 ' + (p.p50LatencyMs == null ? '—' : p.p50LatencyMs + 'ms') + ' · last ' + since +
+      '</span>' +
+    '</div>';
+  }).join('');
+
+  // Recent paid calls
+  const paid = data.recentPaidCalls || [];
+  const paidBox = document.getElementById('mk-paid');
+  if (paid.length === 0) {
+    paidBox.className = 'empty';
+    paidBox.textContent = 'No paid calls yet — stocks ship in the next release.';
+  } else {
+    paidBox.className = '';
+    paidBox.innerHTML = paid.map(function(r){
+      const age = Math.round((Date.now() - r.ts) / 1000) + 's ago';
+      return '<div style="display:flex;justify-content:space-between;padding:4px 0;font-family:var(--mono);font-size:12px">' +
+        '<span>' + esc(r.endpoint) + '</span>' +
+        '<span class="gold">' + usd(r.costUsd) + '</span>' +
+        '<span style="color:var(--text-dim)">' + age + '</span>' +
+      '</div>';
+    }).join('');
+  }
 }
 
 async function loadLearnings() {
@@ -909,9 +998,10 @@ document.querySelector('[data-tab="audit"]')?.addEventListener('click', loadAudi
 
 loadOverview();
 loadSessions();
-loadSocial();
+loadMarkets();
 loadLearnings();
 loadWallet();
+document.querySelector('[data-tab="markets"]')?.addEventListener('click', loadMarkets);
 setInterval(() => api('wallet').then(w => {
   if (w) {
     document.getElementById('balance').textContent = usdBig(w.balance) + ' USDC';

package/dist/panel/server.js

@@ -13,7 +13,8 @@ import { listSessions, loadSessionHistory } from '../session/storage.js';
 import { searchSessions } from '../session/search.js';
 import { loadLearnings } from '../learnings/store.js';
 import { readAudit } from '../stats/audit.js';
-import { getStats as getSocialStats } from '../social/db.js';
+import { snapshot as marketsSnapshot } from '../trading/providers/telemetry.js';
+import { describeWiring } from '../trading/providers/registry.js';
 import { getHTML } from './html.js';
 const sseClients = new Set();
 function json(res, data, status = 200) {
@@ -312,9 +313,19 @@ export function createPanelServer(port) {
                     }
                     return;
                 }
-                if (p === '/api/social') {
-                    const stats = getSocialStats();
-                    json(res, stats);
+                if (p === '/api/markets') {
+                    // Snapshot of every active data provider for the Markets panel:
+                    // pipeline wiring (which endpoint serves which asset class), live
+                    // health + latency per provider, and today's paid-call ledger.
+                    const snap = marketsSnapshot();
+                    const wiring = describeWiring();
+                    json(res, {
+                        chain: loadChain(),
+                        wiring,
+                        providers: snap.providers,
+                        totals: snap.totals,
+                        recentPaidCalls: snap.recentPaidCalls,
+                    });
                     return;
                 }
                 if (p === '/api/learnings') {

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/read.js

@@ -80,13 +80,32 @@ async function execute(input, ctx) {
         if (stat.size > maxBytes) {
             return { output: `Error: file is too large (${(stat.size / 1024 / 1024).toFixed(1)}MB). Use offset/limit to read a portion.`, isError: true };
         }
-        // Detect binary files
+        // Detect binary files — first by extension, then by content
+        // (some binaries have no extension: `.env.enc`, `.data`, compiled tools
+        // without suffixes, etc. Content sniff catches those.)
         const ext = path.extname(resolved).toLowerCase();
         const binaryExts = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.bmp', '.pdf', '.zip', '.tar', '.gz', '.woff', '.woff2', '.ttf', '.eot', '.mp3', '.mp4', '.wav', '.avi', '.mov', '.exe', '.dll', '.so', '.dylib']);
         if (binaryExts.has(ext)) {
             const sizeStr = stat.size >= 1024 ? `${(stat.size / 1024).toFixed(1)}KB` : `${stat.size}B`;
             return { output: `Binary file: ${resolved} (${ext}, ${sizeStr}). Cannot display contents.` };
         }
+        // NUL-byte content sniff — read up to 8KB as a Buffer, scan for 0x00.
+        // Text files effectively never contain NUL; binary files almost always
+        // do within the first few KB.
+        try {
+            const SNIFF_BYTES = Math.min(stat.size, 8192);
+            if (SNIFF_BYTES > 0) {
+                const fd = fs.openSync(resolved, 'r');
+                const buf = Buffer.alloc(SNIFF_BYTES);
+                fs.readSync(fd, buf, 0, SNIFF_BYTES, 0);
+                fs.closeSync(fd);
+                if (buf.includes(0)) {
+                    const sizeStr = stat.size >= 1024 ? `${(stat.size / 1024).toFixed(1)}KB` : `${stat.size}B`;
+                    return { output: `Binary file: ${resolved} (no text extension but NUL bytes detected, ${sizeStr}). Cannot display contents.` };
+                }
+            }
+        }
+        catch { /* best-effort sniff — fall through to text read */ }
         const raw = fs.readFileSync(resolved, 'utf-8');
         const allLines = raw.split('\n');
         const startLine = Math.max(0, (Math.max(1, offset ?? 1)) - 1);

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[];