@blockrun/franklin 3.17.0 → 3.18.0

package/dist/panel/html.js

@@ -410,6 +410,63 @@ a:hover { text-decoration:underline; }
 .btn-danger { background:oklch(0.65 0.20 25 / 18%); color:var(--danger); border-color:oklch(0.65 0.20 25 / 35%); }
 .btn-danger:hover { background:oklch(0.65 0.20 25 / 30%); }
 
+.nav-badge {
+  margin-left:auto; font-size:10px; font-weight:700; letter-spacing:0.3px;
+  padding:2px 7px; border-radius:8px;
+  background:oklch(0.65 0.20 25 / 22%); color:var(--danger);
+  border:1px solid oklch(0.65 0.20 25 / 35%);
+}
+.nav-badge.warn { background:oklch(0.78 0.14 85 / 22%); color:var(--gold); border-color:oklch(0.78 0.14 85 / 35%); }
+
+.phone-list { display:flex; flex-direction:column; gap:10px; }
+.phone-row {
+  display:grid; grid-template-columns:auto 1fr auto; gap:14px; align-items:center;
+  padding:14px 16px; background:var(--bg-card); border:1px solid var(--border);
+  border-radius:var(--radius); transition:border-color 0.15s, background 0.15s;
+}
+.phone-row:hover { background:var(--bg-card-hover); }
+.phone-row.warn { border-color:oklch(0.78 0.14 85 / 50%); }
+.phone-row.crit { border-color:oklch(0.65 0.20 25 / 55%); }
+.phone-row.expired { opacity:0.65; border-color:oklch(0.65 0.20 25 / 45%); }
+.phone-icon-bubble {
+  width:36px; height:36px; border-radius:10px; display:grid; place-items:center;
+  background:oklch(0.68 0.16 260 / 18%); color:var(--brand);
+}
+.phone-main { display:flex; flex-direction:column; gap:3px; min-width:0; }
+.phone-num {
+  font-family:var(--mono); font-size:15px; font-weight:600; color:var(--text);
+  letter-spacing:0.02em;
+}
+.phone-meta { font-size:12px; color:var(--text-muted); display:flex; gap:10px; flex-wrap:wrap; }
+.phone-meta .chip {
+  display:inline-flex; align-items:center; gap:4px;
+  padding:2px 7px; border-radius:6px; background:oklch(0 0 0 / 25%);
+  font-size:10.5px; letter-spacing:0.5px; text-transform:uppercase; font-weight:700;
+}
+.phone-meta .chip.green { color:var(--success); background:oklch(0.65 0.18 145 / 18%); }
+.phone-meta .chip.amber { color:var(--gold);    background:oklch(0.78 0.14 85 / 20%); }
+.phone-meta .chip.red   { color:var(--danger);  background:oklch(0.65 0.20 25 / 20%); }
+.phone-row .phone-actions { display:flex; align-items:center; gap:6px; }
+.phone-row.expired .phone-num { text-decoration:line-through; }
+
+.phone-empty {
+  padding:24px; text-align:center; border:1px dashed var(--border);
+  border-radius:var(--radius); color:var(--text-muted); font-size:13px;
+  line-height:1.6;
+}
+.phone-empty strong { color:var(--text); font-weight:600; display:block; margin-bottom:6px; font-size:14px; }
+
+.phone-buy-form { display:flex; gap:8px; flex-wrap:wrap; align-items:center; margin-top:10px; }
+.phone-buy-form select, .phone-buy-form input {
+  padding:7px 10px; background:oklch(0 0 0 / 35%); color:var(--text);
+  border:1px solid var(--border); border-radius:7px; font-size:13px;
+  font-family:var(--mono);
+}
+.phone-buy-form input { width:120px; }
+.phone-status { font-size:12px; color:var(--text-muted); }
+.phone-status.ok  { color:var(--success); }
+.phone-status.err { color:var(--danger); }
+
 @media (max-width:768px) {
   body { flex-direction:column; }
   .sidebar { width:100%; min-width:100%; flex-direction:row; padding:8px; overflow-x:auto; border-right:none; border-bottom:1px solid var(--border); }
@@ -455,6 +512,11 @@ 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="M3 3v18h18"/><path d="M7 14l4-4 4 4 5-5"/></svg>
       Markets
     </button>
+    <button class="nav-item" data-tab="phone">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72 12.84 12.84 0 0 0 .7 2.81 2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45 12.84 12.84 0 0 0 2.81.7A2 2 0 0 1 22 16.92z"/></svg>
+      Phone
+      <span class="nav-badge" id="phone-nav-badge" style="display:none"></span>
+    </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
@@ -677,6 +739,46 @@ a:hover { text-decoration:underline; }
     </div>
   </div>
 
+  <!-- Phone & Voice -->
+  <div class="tab" id="tab-phone">
+    <div class="content-header">
+      <h2>Phone &amp; Voice</h2>
+      <p>Numbers your wallet owns. Leases run 30 days &mdash; renew before they expire or set auto-renew.</p>
+    </div>
+
+    <div class="card" style="margin-bottom:16px">
+      <div style="display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap;">
+        <h3 style="margin:0">Your numbers</h3>
+        <div style="display:flex;gap:8px;align-items:center">
+          <span class="phone-status" id="phone-list-status"></span>
+          <button class="btn btn-ghost" id="phone-refresh-btn" title="Refetch from BlockRun ($0.001)">Refresh</button>
+        </div>
+      </div>
+      <div id="phone-list" style="margin-top:12px">
+        <div class="phone-empty">Loading&hellip;</div>
+      </div>
+    </div>
+
+    <div class="card">
+      <h3 style="margin:0 0 6px">Add another number</h3>
+      <p class="wallet-hint">
+        $5 USDC for a fresh number, bound to your wallet for 30 days. <strong>This adds
+        a new number alongside any you already own &mdash; nothing is replaced.</strong>
+        Use it as caller ID for outbound AI voice calls, or (soon) to receive inbound calls.
+        Multiple numbers are fine; release any you no longer need to stop paying renewals on them.
+      </p>
+      <div class="phone-buy-form">
+        <select id="phone-buy-country">
+          <option value="US">United States (+1)</option>
+          <option value="CA">Canada (+1)</option>
+        </select>
+        <input id="phone-buy-areacode" placeholder="Area code (opt)" maxlength="6" />
+        <button class="btn btn-warn" id="phone-buy-btn">Buy for $5</button>
+        <span class="phone-status" id="phone-buy-status"></span>
+      </div>
+    </div>
+  </div>
+
   <!-- Learnings -->
   <div class="tab" id="tab-learnings">
     <div class="content-header">
@@ -1544,6 +1646,307 @@ document.addEventListener('visibilitychange', () => {
 
 document.getElementById('tasks-refresh-btn')?.addEventListener('click', fetchTasks);
 
+// ─── Phone & Voice ──────────────────────────────────────────────────────
+// Renders the user's wallet-owned numbers, days-remaining countdown,
+// renew / release / auto-renew controls, and the buy form. Drives the
+// sidebar nav badge so users with an expiring number see it even from
+// the Overview tab. Notification ladder uses the Notifications API,
+// dedupe-keyed in sessionStorage so we don't spam the user every open.
+
+const phoneState = { data: null, countdownTimer: null };
+
+function formatPhoneNumber(e164) {
+  // E.164 → human, for display only. Keep raw value for actions.
+  if (!e164) return '—';
+  const m = String(e164).match(/^\\+1(\\d{3})(\\d{3})(\\d{4})$/);
+  if (m) return '+1 (' + m[1] + ') ' + m[2] + '-' + m[3];
+  return e164;
+}
+
+function daysLeft(expiresAt) {
+  const expiry = new Date(expiresAt).getTime();
+  if (isNaN(expiry)) return 0;
+  return Math.floor((expiry - Date.now()) / 86400000);
+}
+
+function phoneTier(days) {
+  if (days < 0) return 'expired';
+  if (days <= 2) return 'crit';
+  if (days <= 7) return 'warn';
+  return 'ok';
+}
+
+function phoneChipClass(tier) {
+  if (tier === 'expired' || tier === 'crit') return 'red';
+  if (tier === 'warn') return 'amber';
+  return 'green';
+}
+
+function phoneCountdownLabel(days) {
+  if (days < 0) return 'expired ' + Math.abs(days) + 'd ago';
+  if (days === 0) return 'expires today';
+  if (days === 1) return '1 day left';
+  return days + ' days left';
+}
+
+function updatePhoneNavBadge(numbers) {
+  const badge = document.getElementById('phone-nav-badge');
+  if (!badge) return;
+  let worst = 999;
+  let anyExpired = false;
+  numbers.forEach(n => {
+    const d = daysLeft(n.expires_at);
+    if (d < 0) anyExpired = true;
+    if (d < worst) worst = d;
+  });
+  if (anyExpired) {
+    badge.textContent = '!'; badge.className = 'nav-badge'; badge.style.display = '';
+  } else if (worst <= 2) {
+    badge.textContent = worst + 'd'; badge.className = 'nav-badge'; badge.style.display = '';
+  } else if (worst <= 7) {
+    badge.textContent = worst + 'd'; badge.className = 'nav-badge warn'; badge.style.display = '';
+  } else {
+    badge.style.display = 'none';
+  }
+}
+
+function maybeNotifyExpiry(numbers) {
+  if (typeof Notification === 'undefined') return;
+  if (Notification.permission !== 'granted') return;
+  numbers.forEach(n => {
+    const d = daysLeft(n.expires_at);
+    let mark = null;
+    if (d < 0) mark = 'expired';
+    else if (d <= 1) mark = 't1';
+    else if (d <= 3) mark = 't3';
+    else if (d <= 7) mark = 't7';
+    if (!mark) return;
+    const key = 'phone:notify:' + n.phone_number + ':' + mark;
+    if (sessionStorage.getItem(key)) return;
+    sessionStorage.setItem(key, '1');
+    const human = formatPhoneNumber(n.phone_number);
+    const title = 'Franklin: ' + human;
+    const body = mark === 'expired'
+      ? 'This number has expired. Provision a new one in the Phone tab.'
+      : (mark === 't1'
+        ? 'Expires in 1 day. Click to renew for $5.'
+        : (mark === 't3'
+          ? 'Expires in 3 days. Click to renew for $5.'
+          : 'Expires in a week. Renew when convenient.'));
+    try {
+      const notif = new Notification(title, { body, tag: key });
+      notif.onclick = () => {
+        try { window.focus(); } catch (e) {}
+        location.hash = 'phone';
+        activateTab('phone');
+        notif.close();
+      };
+    } catch (e) { /* ignore */ }
+  });
+}
+
+function renderPhoneNumbers(data) {
+  const list = document.getElementById('phone-list');
+  if (!list) return;
+  const numbers = (data && data.numbers) || [];
+  updatePhoneNavBadge(numbers);
+
+  if (!numbers.length) {
+    list.innerHTML = '<div class="phone-empty">' +
+      '<strong>No numbers yet</strong>' +
+      'Provision a number below to give Franklin a phone identity. ' +
+      'Numbers cost $5 for a 30-day lease and are bound to your wallet.' +
+      '</div>';
+    return;
+  }
+
+  const html = numbers.map(n => {
+    const d = daysLeft(n.expires_at);
+    const tier = phoneTier(d);
+    const chipCls = phoneChipClass(tier);
+    const rowCls = tier === 'ok' ? '' : (' ' + tier);
+    const human = formatPhoneNumber(n.phone_number);
+    const renewBtn = tier === 'expired'
+      ? ''
+      : '<button class="btn btn-warn" data-phone-renew="' + n.phone_number + '">Renew $5</button>';
+    const releaseLabel = tier === 'expired' ? 'Remove' : 'Release';
+    return ''
+      + '<div class="phone-row' + rowCls + '">'
+      + '  <div class="phone-icon-bubble">'
+      + '    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">'
+      + '      <path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72 12.84 12.84 0 0 0 .7 2.81 2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45 12.84 12.84 0 0 0 2.81.7A2 2 0 0 1 22 16.92z"/>'
+      + '    </svg>'
+      + '  </div>'
+      + '  <div class="phone-main">'
+      + '    <div class="phone-num">' + human + '</div>'
+      + '    <div class="phone-meta">'
+      + '      <span class="chip">' + (n.chain || '—') + '</span>'
+      + '      <span class="chip ' + chipCls + '">' + phoneCountdownLabel(d) + '</span>'
+      + '    </div>'
+      + '  </div>'
+      + '  <div class="phone-actions">'
+      +      renewBtn
+      + '    <button class="btn btn-ghost" data-phone-release="' + n.phone_number + '" title="' + releaseLabel + ' this number">' + releaseLabel + '</button>'
+      + '  </div>'
+      + '</div>';
+  }).join('');
+
+  list.innerHTML = html;
+
+  list.querySelectorAll('[data-phone-renew]').forEach(btn => {
+    btn.addEventListener('click', () => renewPhoneNumber(btn.getAttribute('data-phone-renew')));
+  });
+  list.querySelectorAll('[data-phone-release]').forEach(btn => {
+    btn.addEventListener('click', () => releasePhoneNumber(btn.getAttribute('data-phone-release')));
+  });
+
+  maybeNotifyExpiry(numbers);
+}
+
+async function loadPhone(opts) {
+  const force = !!(opts && opts.force);
+  const statusEl = document.getElementById('phone-list-status');
+  if (statusEl) statusEl.textContent = force ? 'Refreshing…' : 'Loading…';
+  try {
+    const url = '/api/phone/numbers';
+    const r = force
+      ? await fetch('/api/phone/numbers/refresh', { method: 'POST' })
+      : await fetch(url);
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Failed to load'; statusEl.className = 'phone-status err'; }
+      const list = document.getElementById('phone-list');
+      if (list) list.innerHTML = '<div class="phone-empty"><strong>Could not load numbers</strong>' + (data.error || 'Unknown error') + '</div>';
+      return;
+    }
+    phoneState.data = data;
+    renderPhoneNumbers(data);
+    if (statusEl) {
+      statusEl.className = 'phone-status';
+      statusEl.textContent = data.fromCache
+        ? 'Cached ' + new Date(data.fetchedAt).toLocaleTimeString()
+        : 'Synced ' + new Date(data.fetchedAt || Date.now()).toLocaleTimeString();
+    }
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  }
+}
+
+async function renewPhoneNumber(num) {
+  const statusEl = document.getElementById('phone-list-status');
+  if (statusEl) { statusEl.textContent = 'Renewing ' + formatPhoneNumber(num) + '…'; statusEl.className = 'phone-status'; }
+  try {
+    const r = await fetch('/api/phone/numbers/renew', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ phoneNumber: num }),
+    });
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Renew failed'; statusEl.className = 'phone-status err'; }
+      return;
+    }
+    // Clear dedupe keys so a renewed number can re-notify if it expires again later
+    Object.keys(sessionStorage).filter(k => k.startsWith('phone:notify:' + num + ':')).forEach(k => sessionStorage.removeItem(k));
+    if (statusEl) { statusEl.textContent = 'Renewed — new expiry ' + new Date(data.expires_at).toLocaleDateString(); statusEl.className = 'phone-status ok'; }
+    await loadPhone({});
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  }
+}
+
+async function releasePhoneNumber(num) {
+  if (!confirm('Release ' + formatPhoneNumber(num) + '? This permanently gives up the number and cannot be undone.')) return;
+  const statusEl = document.getElementById('phone-list-status');
+  if (statusEl) { statusEl.textContent = 'Releasing…'; statusEl.className = 'phone-status'; }
+  try {
+    const r = await fetch('/api/phone/numbers/release', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ phoneNumber: num }),
+    });
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Release failed'; statusEl.className = 'phone-status err'; }
+      return;
+    }
+    if (statusEl) { statusEl.textContent = 'Released ' + formatPhoneNumber(num); statusEl.className = 'phone-status ok'; }
+    await loadPhone({});
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  }
+}
+
+async function buyPhoneNumber() {
+  const country = (document.getElementById('phone-buy-country') || {}).value || 'US';
+  const areaCode = ((document.getElementById('phone-buy-areacode') || {}).value || '').trim();
+  const statusEl = document.getElementById('phone-buy-status');
+  const btn = document.getElementById('phone-buy-btn');
+  const existingCount = ((phoneState.data && phoneState.data.numbers) || []).filter(n => daysLeft(n.expires_at) >= 0).length;
+  const intro = existingCount > 0
+    ? 'You already own ' + existingCount + ' active number' + (existingCount === 1 ? '' : 's') + '. This will ADD a new number — nothing is replaced.\\n\\n'
+    : '';
+  if (!confirm(intro + 'Buy a new phone number for $5? It will be charged from your wallet immediately and last 30 days.')) return;
+  if (statusEl) { statusEl.textContent = 'Provisioning…'; statusEl.className = 'phone-status'; }
+  if (btn) btn.disabled = true;
+  try {
+    const r = await fetch('/api/phone/numbers/buy', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ country, areaCode: areaCode || undefined }),
+    });
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Purchase failed'; statusEl.className = 'phone-status err'; }
+      return;
+    }
+    if (statusEl) { statusEl.textContent = 'Got ' + formatPhoneNumber(data.phone_number); statusEl.className = 'phone-status ok'; }
+    await loadPhone({});
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  } finally {
+    if (btn) btn.disabled = false;
+  }
+}
+
+function startPhoneCountdown() {
+  if (phoneState.countdownTimer) return;
+  // Re-render every minute so countdown chips age in place. Cheap — no
+  // network, just DOM. Pauses when tab not visible (see visibilitychange).
+  phoneState.countdownTimer = setInterval(() => {
+    if (document.visibilityState !== 'visible') return;
+    if (phoneState.data) renderPhoneNumbers(phoneState.data);
+  }, 60000);
+}
+
+function stopPhoneCountdown() {
+  if (phoneState.countdownTimer) {
+    clearInterval(phoneState.countdownTimer);
+    phoneState.countdownTimer = null;
+  }
+}
+
+document.querySelector('[data-tab="phone"]')?.addEventListener('click', () => {
+  // Ask once for notification permission when the user first opens the tab.
+  // We never auto-prompt on page load — that would be annoying.
+  if (typeof Notification !== 'undefined' && Notification.permission === 'default') {
+    Notification.requestPermission().catch(() => {});
+  }
+  loadPhone({});
+  startPhoneCountdown();
+});
+
+document.addEventListener('tab:deactivated', (e) => {
+  if (e.detail && e.detail.name === 'phone') stopPhoneCountdown();
+});
+
+document.getElementById('phone-refresh-btn')?.addEventListener('click', () => loadPhone({ force: true }));
+document.getElementById('phone-buy-btn')?.addEventListener('click', buyPhoneNumber);
+
+// Prime the nav badge so an expiring number is visible even before the user
+// clicks into the Phone tab. Cached read — no network cost.
+loadPhone({});
+
 loadOverview();
 loadSessions();
 loadMarkets();

package/dist/panel/server.js

@@ -7,6 +7,8 @@ import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadChain, saveChain } from '../config.js';
+import { listNumbers as gatewayListNumbers, renewNumber as gatewayRenewNumber, buyNumber as gatewayBuyNumber, releaseNumber as gatewayReleaseNumber, } from '../phone/client.js';
+import { readCache as readPhoneCache, writeCache as writePhoneCache, clearCache as clearPhoneCache, isFresh as isPhoneCacheFresh, } from '../phone/cache.js';
 import { getStatsSummary, getStatsFilePath } from '../stats/tracker.js';
 import { generateInsights } from '../stats/insights.js';
 import { listSessions, loadSessionHistory } from '../session/storage.js';
@@ -24,7 +26,7 @@ const sseClients = new Set();
 function json(res, data, status = 200) {
     res.writeHead(status, {
         'Content-Type': 'application/json',
-        'Access-Control-Allow-Origin': '*',
+        'Cache-Control': 'no-store',
     });
     res.end(JSON.stringify(data));
 }
@@ -37,6 +39,39 @@ function isLoopback(req) {
     const addr = req.socket.remoteAddress || '';
     return addr === '127.0.0.1' || addr === '::1' || addr === '::ffff:127.0.0.1';
 }
+function isLocalHostname(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
+}
+/**
+ * Loopback binding prevents LAN exposure, but it does not stop a malicious
+ * website open in the user's browser from issuing requests to localhost.
+ * Browsers attach Origin on cross-origin fetches, so spendful and
+ * wallet-mutating routes require either no Origin (curl/direct navigation)
+ * or the exact same local origin that served the panel page.
+ */
+function isTrustedPanelOrigin(req) {
+    const origin = req.headers.origin;
+    if (!origin)
+        return true;
+    if (Array.isArray(origin))
+        return false;
+    const host = req.headers.host;
+    if (!host)
+        return false;
+    try {
+        const originUrl = new URL(origin);
+        const hostUrl = new URL(`http://${host}`);
+        return originUrl.protocol === 'http:' &&
+            originUrl.host === hostUrl.host &&
+            isLocalHostname(originUrl.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function isLocalPanelRequest(req) {
+    return isLoopback(req) && isTrustedPanelOrigin(req);
+}
 async function readBody(req, maxBytes = 16 * 1024) {
     return new Promise((resolve, reject) => {
         let size = 0;
@@ -65,6 +100,25 @@ function broadcast(data) {
         }
     }
 }
+/**
+ * Resolve the current active wallet address (Base or Solana, depending on
+ * the active chain). Used by phone endpoints that key the cache by wallet,
+ * and that must sign x402 payments out of the wallet the user owns.
+ *
+ * Throws if no wallet exists yet — the UI handles this by showing an
+ * empty state with a "Create wallet" CTA before any phone calls can be made.
+ */
+async function currentWalletAddress() {
+    const chain = loadChain();
+    if (chain === 'solana') {
+        const { setupAgentSolanaWallet } = await import('@blockrun/llm');
+        const client = await setupAgentSolanaWallet({ silent: true });
+        return await client.getWalletAddress();
+    }
+    const { setupAgentWallet } = await import('@blockrun/llm');
+    const client = setupAgentWallet({ silent: true });
+    return client.getWalletAddress();
+}
 export function createPanelServer(port) {
     const html = getHTML();
     const server = http.createServer(async (req, res) => {
@@ -239,9 +293,9 @@ export function createPanelServer(port) {
                 // ─── Wallet secret (loopback only) ──────────────────────────────────
                 // Returns the private key so the user can back it up / move it.
                 // Hardened: loopback-only (belt-and-suspenders on the 127.0.0.1 bind),
-                // no-store cache header, JSON only.
+                // same-origin for browser requests, no-store cache header, JSON only.
                 if (p === '/api/wallet/secret') {
-                    if (!isLoopback(req)) {
+                    if (!isLocalPanelRequest(req)) {
                         json(res, { error: 'forbidden' }, 403);
                         return;
                     }
@@ -271,9 +325,9 @@ export function createPanelServer(port) {
                 // ─── Wallet import (loopback only) ──────────────────────────────────
                 // Overwrites the local wallet with a user-supplied private key.
                 // Destructive — overwrites the existing wallet file without backup,
-                // so the UI warns the user. Loopback-only.
+                // so the UI warns the user. Loopback + same-origin only.
                 if (p === '/api/wallet/import' && req.method === 'POST') {
-                    if (!isLoopback(req)) {
+                    if (!isLocalPanelRequest(req)) {
                         json(res, { error: 'forbidden' }, 403);
                         return;
                     }
@@ -329,7 +383,7 @@ export function createPanelServer(port) {
                 // reads and for the *next* agent invocation, but won't flip chain
                 // mid-session for an already-running agent. UI copy makes this clear.
                 if (p === '/api/chain' && req.method === 'POST') {
-                    if (!isLoopback(req)) {
+                    if (!isLocalPanelRequest(req)) {
                         json(res, { error: 'forbidden' }, 403);
                         return;
                     }
@@ -364,6 +418,163 @@ export function createPanelServer(port) {
                     }
                     return;
                 }
+                // ─── Phone & Voice ──────────────────────────────────────────────────
+                // GET  /api/phone/numbers           — list wallet-owned numbers (cached)
+                // POST /api/phone/numbers/refresh   — force-refresh from BlockRun ($0.001)
+                // POST /api/phone/numbers/renew     — extend lease 30d ($5)
+                // POST /api/phone/numbers/buy       — provision new number ($5)
+                // POST /api/phone/numbers/release   — release (free)
+                //
+                // Renewals are explicit user clicks. No silent auto-renew: a wallet
+                // that runs dry between charges would fail the renewal and surprise
+                // the user. Notifications at T-7/3/1 days keep them in the loop.
+                //
+                // All spendful/mutating endpoints are loopback + same-origin because
+                // they spend money out of the user's wallet. Even the list endpoint can
+                // cost $0.001 on cache miss, so it gets the same browser-origin guard.
+                if (p === '/api/phone/numbers' && (!req.method || req.method === 'GET')) {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden', numbers: [] }, 403);
+                        return;
+                    }
+                    try {
+                        const wallet = await currentWalletAddress();
+                        const chain = loadChain();
+                        const cache = readPhoneCache();
+                        if (cache && isPhoneCacheFresh(cache, wallet, chain)) {
+                            json(res, {
+                                wallet,
+                                chain,
+                                fetchedAt: cache.fetchedAt,
+                                fromCache: true,
+                                numbers: cache.numbers,
+                            });
+                            return;
+                        }
+                        // Cache stale or missing — fetch fresh (costs $0.001).
+                        // We pay through the panel's wallet, which is the same wallet
+                        // that owns the numbers, so the gateway returns this user's list.
+                        const fresh = await gatewayListNumbers({ walletAddress: wallet });
+                        json(res, {
+                            wallet,
+                            chain,
+                            fetchedAt: Date.now(),
+                            fromCache: false,
+                            paid: fresh.paid,
+                            numbers: fresh.numbers,
+                        });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message, numbers: [] }, 500);
+                    }
+                    return;
+                }
+                if (p === '/api/phone/numbers/refresh' && req.method === 'POST') {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const wallet = await currentWalletAddress();
+                        clearPhoneCache();
+                        const fresh = await gatewayListNumbers({ walletAddress: wallet });
+                        broadcast({ type: 'phone.refreshed' });
+                        json(res, {
+                            wallet,
+                            chain: loadChain(),
+                            paid: fresh.paid,
+                            numbers: fresh.numbers,
+                        });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
+                if (p === '/api/phone/numbers/renew' && req.method === 'POST') {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const raw = await readBody(req);
+                        const body = JSON.parse(raw);
+                        const target = (body.phoneNumber || '').trim();
+                        if (!target) {
+                            json(res, { error: 'phoneNumber required' }, 400);
+                            return;
+                        }
+                        const result = await gatewayRenewNumber(target);
+                        // Patch the cache in place so the panel UI gets the new expiry
+                        // without a follow-up $0.001 list call.
+                        const cache = readPhoneCache();
+                        if (cache) {
+                            const idx = cache.numbers.findIndex(n => n.phone_number === target);
+                            if (idx >= 0) {
+                                cache.numbers[idx] = {
+                                    ...cache.numbers[idx],
+                                    expires_at: result.expires_at,
+                                    active: true,
+                                };
+                                writePhoneCache({ wallet: cache.wallet, chain: cache.chain, numbers: cache.numbers });
+                            }
+                        }
+                        broadcast({ type: 'phone.renewed', phoneNumber: target, expires_at: result.expires_at });
+                        json(res, { ok: true, ...result });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
+                if (p === '/api/phone/numbers/buy' && req.method === 'POST') {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const raw = await readBody(req);
+                        const body = JSON.parse(raw);
+                        const result = await gatewayBuyNumber({
+                            country: body.country,
+                            areaCode: body.areaCode,
+                        });
+                        clearPhoneCache(); // forces next /api/phone/numbers to re-list
+                        broadcast({ type: 'phone.bought', phoneNumber: result.phone_number });
+                        json(res, { ok: true, ...result });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
+                if (p === '/api/phone/numbers/release' && req.method === 'POST') {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const raw = await readBody(req);
+                        const body = JSON.parse(raw);
+                        const target = (body.phoneNumber || '').trim();
+                        if (!target) {
+                            json(res, { error: 'phoneNumber required' }, 400);
+                            return;
+                        }
+                        const result = await gatewayReleaseNumber(target);
+                        const cache = readPhoneCache();
+                        if (cache) {
+                            const next = cache.numbers.filter(n => n.phone_number !== target);
+                            writePhoneCache({ wallet: cache.wallet, chain: cache.chain, numbers: next });
+                        }
+                        broadcast({ type: 'phone.released', phoneNumber: target });
+                        json(res, { ok: true, ...result });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
                 if (p === '/api/markets') {
                     // Snapshot of every active data provider for the Markets panel:
                     // pipeline wiring (which endpoint serves which asset class), live

package/dist/phone/cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared cache for the user's BlockRun-provisioned phone numbers.
+ *
+ * Why a cache: `POST /v1/phone/numbers/list` costs $0.001 per call. The
+ * panel ticks countdowns once per minute and the terminal status bar
+ * re-renders on every prompt cycle — both surfaces hitting the gateway
+ * directly would burn pointless micropayments. We hit the gateway only
+ * on cache-miss, panel-reload, or after a state-changing call (buy /
+ * renew / release).
+ *
+ * Storage: ~/.blockrun/phone-numbers.json. Read by both the Ink terminal
+ * status bar and the web panel, so they always agree on which numbers
+ * the wallet owns and how many days remain.
+ */
+import { type Chain } from '../config.js';
+export interface PhoneNumberRecord {
+    phone_number: string;
+    chain: Chain;
+    expires_at: string;
+    active: boolean;
+}
+interface CacheFile {
+    fetchedAt: number;
+    wallet: string;
+    chain: Chain;
+    numbers: PhoneNumberRecord[];
+}
+/** 6 hours — long enough to not thrash the gateway, short enough that
+ * a number provisioned on another device shows up the same day. */
+export declare const CACHE_TTL_MS: number;
+export declare function readCache(): CacheFile | null;
+export declare function writeCache(data: {
+    wallet: string;
+    chain: Chain;
+    numbers: PhoneNumberRecord[];
+}): void;
+export declare function clearCache(): void;
+export declare function isFresh(cache: CacheFile | null, wallet: string, chain: Chain): boolean;
+/**
+ * Compute days-remaining for a number's lease. Negative when expired.
+ * UI uses this for the colour ladder (green / amber / red).
+ */
+export declare function daysRemaining(expiresAt: string): number;
+export {};

package/dist/phone/cache.js

@@ -0,0 +1,74 @@
+/**
+ * Shared cache for the user's BlockRun-provisioned phone numbers.
+ *
+ * Why a cache: `POST /v1/phone/numbers/list` costs $0.001 per call. The
+ * panel ticks countdowns once per minute and the terminal status bar
+ * re-renders on every prompt cycle — both surfaces hitting the gateway
+ * directly would burn pointless micropayments. We hit the gateway only
+ * on cache-miss, panel-reload, or after a state-changing call (buy /
+ * renew / release).
+ *
+ * Storage: ~/.blockrun/phone-numbers.json. Read by both the Ink terminal
+ * status bar and the web panel, so they always agree on which numbers
+ * the wallet owns and how many days remain.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR } from '../config.js';
+const CACHE_PATH = path.join(BLOCKRUN_DIR, 'phone-numbers.json');
+/** 6 hours — long enough to not thrash the gateway, short enough that
+ * a number provisioned on another device shows up the same day. */
+export const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+export function readCache() {
+    try {
+        const raw = fs.readFileSync(CACHE_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.numbers))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCache(data) {
+    try {
+        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+        const payload = {
+            fetchedAt: Date.now(),
+            wallet: data.wallet,
+            chain: data.chain,
+            numbers: data.numbers,
+        };
+        fs.writeFileSync(CACHE_PATH, JSON.stringify(payload, null, 2) + '\n', {
+            mode: 0o600,
+        });
+    }
+    catch {
+        /* best-effort — cache is an optimization, not a source of truth */
+    }
+}
+export function clearCache() {
+    try {
+        fs.unlinkSync(CACHE_PATH);
+    }
+    catch { /* not there, fine */ }
+}
+export function isFresh(cache, wallet, chain) {
+    if (!cache)
+        return false;
+    if (cache.wallet !== wallet)
+        return false;
+    if (cache.chain !== chain)
+        return false;
+    return Date.now() - cache.fetchedAt < CACHE_TTL_MS;
+}
+/**
+ * Compute days-remaining for a number's lease. Negative when expired.
+ * UI uses this for the colour ladder (green / amber / red).
+ */
+export function daysRemaining(expiresAt) {
+    const expiry = new Date(expiresAt).getTime();
+    const now = Date.now();
+    return Math.floor((expiry - now) / (24 * 60 * 60 * 1000));
+}

package/dist/phone/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * BlockRun phone API client.
+ *
+ * Thin wrapper over `/v1/phone/numbers/{list,buy,renew,release}` that
+ * handles the x402 payment handshake using the wallet Franklin already
+ * loads at startup. Pattern mirrors `src/tools/modal.ts` — first POST
+ * returns 402 with payment requirements, we sign with the local wallet,
+ * retry once with X-PAYMENT.
+ *
+ * Used by:
+ *   - panel server (renew button, buy flow, refresh button)
+ *   - phone cache refresh (background)
+ *   - future Phone/Call tools surfaced to the agent
+ */
+import { type Chain } from '../config.js';
+import { type PhoneNumberRecord } from './cache.js';
+export interface ListNumbersResult {
+    numbers: PhoneNumberRecord[];
+    count: number;
+    /** $0.001 was paid for this list call. UI can show it. */
+    paid: number;
+}
+/**
+ * Fetch the wallet's owned numbers from BlockRun. Refreshes the local
+ * cache on success so the terminal status bar picks up the same data.
+ */
+export declare function listNumbers(opts: {
+    walletAddress: string;
+}): Promise<ListNumbersResult>;
+export interface RenewResult {
+    phone_number: string;
+    expires_at: string;
+    paid: number;
+}
+export declare function renewNumber(phoneNumber: string): Promise<RenewResult>;
+export interface BuyResult {
+    phone_number: string;
+    expires_at: string;
+    chain: Chain;
+    paid: number;
+}
+export declare function buyNumber(opts: {
+    country?: string;
+    areaCode?: string;
+}): Promise<BuyResult>;
+export interface ReleaseResult {
+    released: boolean;
+    phone_number: string;
+}
+export declare function releaseNumber(phoneNumber: string): Promise<ReleaseResult>;

package/dist/phone/client.js

@@ -0,0 +1,162 @@
+/**
+ * BlockRun phone API client.
+ *
+ * Thin wrapper over `/v1/phone/numbers/{list,buy,renew,release}` that
+ * handles the x402 payment handshake using the wallet Franklin already
+ * loads at startup. Pattern mirrors `src/tools/modal.ts` — first POST
+ * returns 402 with payment requirements, we sign with the local wallet,
+ * retry once with X-PAYMENT.
+ *
+ * Used by:
+ *   - panel server (renew button, buy flow, refresh button)
+ *   - phone cache refresh (background)
+ *   - future Phone/Call tools surfaced to the agent
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, USER_AGENT } from '../config.js';
+import { writeCache } from './cache.js';
+function phoneEndpoint(chain, path) {
+    return `${API_URLS[chain]}/v1/phone/${path}`;
+}
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.clone().json());
+            if (body.x402 || body.accepts)
+                header = btoa(JSON.stringify(body));
+        }
+        catch { /* not JSON, no header */ }
+    }
+    return header;
+}
+async function signPayment(response, chain, endpoint, resourceDescription) {
+    const paymentHeader = await extractPaymentReq(response);
+    if (!paymentHeader)
+        return null;
+    if (chain === 'solana') {
+        const wallet = await getOrCreateSolanaWallet();
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+        const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+        const feePayer = details.extra?.feePayer || details.recipient;
+        const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+            resourceUrl: details.resource?.url || endpoint,
+            resourceDescription: details.resource?.description || resourceDescription,
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    else {
+        const wallet = getOrCreateWallet();
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        const details = extractPaymentDetails(paymentRequired);
+        const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+            resourceUrl: details.resource?.url || endpoint,
+            resourceDescription: details.resource?.description || resourceDescription,
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+}
+async function postWithPayment(endpoint, body, resourceDescription, timeoutMs = 30_000) {
+    const chain = loadChain();
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': USER_AGENT,
+    };
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const payload = JSON.stringify(body);
+        let response = await fetch(endpoint, {
+            method: 'POST',
+            signal: ctrl.signal,
+            headers,
+            body: payload,
+        });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint, resourceDescription);
+            if (!paymentHeaders) {
+                return { ok: false, status: 402, body: { error: 'payment signing failed' }, raw: '' };
+            }
+            response = await fetch(endpoint, {
+                method: 'POST',
+                signal: ctrl.signal,
+                headers: { ...headers, ...paymentHeaders },
+                body: payload,
+            });
+        }
+        const raw = await response.text().catch(() => '');
+        let parsed = {};
+        try {
+            parsed = raw ? JSON.parse(raw) : {};
+        }
+        catch { /* leave as {} */ }
+        return { ok: response.ok, status: response.status, body: parsed, raw };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch the wallet's owned numbers from BlockRun. Refreshes the local
+ * cache on success so the terminal status bar picks up the same data.
+ */
+export async function listNumbers(opts) {
+    const chain = loadChain();
+    const result = await postWithPayment(phoneEndpoint(chain, 'numbers/list'), {}, 'List wallet-owned BlockRun phone numbers');
+    if (!result.ok) {
+        const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
+        throw new Error(message);
+    }
+    const numbers = Array.isArray(result.body.numbers)
+        ? result.body.numbers
+        : [];
+    writeCache({ wallet: opts.walletAddress, chain, numbers });
+    return { numbers, count: numbers.length, paid: 0.001 };
+}
+export async function renewNumber(phoneNumber) {
+    const chain = loadChain();
+    const result = await postWithPayment(phoneEndpoint(chain, 'numbers/renew'), { phoneNumber }, `Renew BlockRun phone number ${phoneNumber}`);
+    if (!result.ok) {
+        const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
+        throw new Error(message);
+    }
+    return {
+        phone_number: String(result.body.phone_number ?? phoneNumber),
+        expires_at: String(result.body.expires_at ?? ''),
+        paid: 5.0,
+    };
+}
+export async function buyNumber(opts) {
+    const chain = loadChain();
+    const body = { country: opts.country || 'US' };
+    if (opts.areaCode)
+        body.areaCode = opts.areaCode;
+    const result = await postWithPayment(phoneEndpoint(chain, 'numbers/buy'), body, `Provision a new BlockRun phone number (${opts.country || 'US'})`);
+    if (!result.ok) {
+        const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
+        throw new Error(message);
+    }
+    return {
+        phone_number: String(result.body.phone_number ?? ''),
+        expires_at: String(result.body.expires_at ?? ''),
+        chain: result.body.chain || chain,
+        paid: 5.0,
+    };
+}
+export async function releaseNumber(phoneNumber) {
+    const chain = loadChain();
+    const result = await postWithPayment(phoneEndpoint(chain, 'numbers/release'), { phoneNumber }, `Release BlockRun phone number ${phoneNumber}`);
+    if (!result.ok) {
+        const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
+        throw new Error(message);
+    }
+    return {
+        released: Boolean(result.body.released),
+        phone_number: String(result.body.phone_number ?? phoneNumber),
+    };
+}

package/package.json

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